Api/v2/conversations/messages/inbound/open

jluncford · October 11, 2021, 7:34pm

I am trying to use api/v2/conversations/messages/inbound/open to send a message to a Genesys queue. I previously implemented this with the callback api however Genesys was automatically trying to call our customer when an agent was assigned, which is not what we want. This needs to be treated as an SMS message.

I need help figuring out how to specify the queue I want the message to be sent to. It appears I have to create an integration within Genesys to do this somehow but it's not at all clear how I go about this. There is a list of Integrations under Admin, but I don't know which to use, if any. How do I get this working? Can anyone help?

Thanks,
Janice

tim.smith · October 11, 2021, 7:46pm

Hello, documentation for configuring and using open messaging, including the supported messaging platforms, can be found here: https://developer.genesys.cloud/api/digital/openmessaging/. If you have specific questions, let me know.

jluncford · October 11, 2021, 10:11pm

Tim,

Everything I've read is about ACD messaging. I can't figure out how to create an Integration that will allow me to specify that integrationId in the /conversations/messages/inbound/open call.

This is in the link you mentioned: You can optionally use an Inbound Message flow in Architect to route inbound open messages to the appropriate agent. To agents, incoming open messages appear with the standard SMS icon along with either the queue name or integration name.

I've been trying to set up an Inbound Message flow in Architect without success because it wants ACD phone numbers or addresses. I don't have these. Is there a way to call /conversations/messages/inbound/open and get it to deposit the message into a specified queue? If that queue has to be set up in an Integration/flow, how do I do that without ACD?

This link: https://developer.genesys.cloud/api/digital/openmessaging/createIntegration
says I have to provide outbound fields, but I'm only doing inbound. I can't find anything about how to set that up.

Thanks,
Janice

anon39326996 · October 11, 2021, 10:17pm

All of the documentation on how to set up open messaging is listed in the resource center: About open messaging - Genesys Cloud Resource Center

Based on what you are describing, it sounds like you're doing something different than you should, but I'm not 100% sure what. You certainly don't need ACD phone numbers or addresses to set up open messaging - it almost sounds like you're setting up either SMS or calls instead of open messaging.

Perhaps post a screenshot of where you're seeing ACD phone numbers or addresses so we can get a better idea of what you are seeing.

jluncford · October 11, 2021, 10:59pm

Here's the documentation chain I'm following:

POST

/api/v2/conversations/messages/inbound/open

Send an inbound Open Message. Send an inbound message to an Open Messaging integration....

It says "Send an inbound message to an Open Messaging integration" so I need an Open Messaging integration.

developer.genesys.cloud/api/digital/openmessaging/createIntegration says:
Create the integration

The first step in setting up open messaging is to create an integration. When you create an integration, specify the outbound webhook URL and the secret token that open messages need to be authenticated on your server. You can also create an integration from the Genesys Cloud Admin UI.
I don't have anything to specify for outbound, I only want inbound.

If I go to Genesys Cloud Admin UI
apps.usw2.pure.cloud/directory/#/admin/integrations/apps
and click Add it goes to Genesys Cloud
and I get a screen of predefined 3rd party integrations to select from.

This isn't what I want.

This link: help.mypurecloud.com/articles/get-started-with-open-messaging/ says

Configure an open messaging integration. When you configure the integration, you specify the outbound webhook URL and the secret token that open messages require for authentication on your server.

Under the link Tim specified above, this is in the Inbound Open Messages section (developer.genesys.cloud/api/digital/openmessaging/inboundMessages)
{
"id": "",
"channel": {
"platform": "Open",
"type": "Private",
"messageId": "",
"to": {
"id": ""

I just want instructions on how to get an Integration ID for an integration that doesn't involve outbound at all. None of the links I've been through explain how to do this. Could someone please give me a link to the actual instructions on how to do this within the Genesys Admin UI?

Thank you,
Janice

tim.smith · October 11, 2021, 11:07pm

Let's take a step back from the technical details for a moment. What is the broader objective you're trying to accomplish? Like Lucie mentioned, it doesn't sound like open messaging is what you want, but I'm not sure what business problem you're trying to solve. If we can understand your goal, there's probably a different solution we can recommend.

jluncford · October 11, 2021, 11:28pm

Here's the business problem I'm trying to solve:

We use Twilio to send automated messages with a link to some patients. Rather than clicking on the link to continue their processing, sometimes they respond to the Twilio SMS message with a question. When we realized this was happening (by viewing Twilio logs) we decided to route these responses into a Genesys Queue set up for receiving these responses so that someone could respond to them from Genesys.

Two weeks ago I was advised to use api/v2/conversations/callbacks to accomplish this. I implemented it and it turned out to be a problem because Genesys was automatically dialing the customers.

Last week I was advised to use api/v2/conversations/messages/inbound/open instead. That was going to deliver the responses to a queue and flag it as a message, which is what we want. While implementing this I found that I have to provide an IntegrationId to this API. I would rather not deal with all that, is there any API I can use that will just put my response message into a Genesys queue? If not, then how do I create that Integration so I can provide an IntegrationId?

BTW, I've been continuing researching messaging and found this statement: "Open messages can originate when an agent sends a message, or as agentless outbound messages that are sent directly by the API. When an open message is sent, the API directs it to the outbound webhook you configure."

Am I correct in interpreting this to mean that open messages only originate from Genesys? If that's the case these won't work for my use case.

(later) I found and watched the DevCast Tutorial 18 | Introduction to the Genesys Cloud Open Messaging API and realize now that the open messages API is intended for 2 way conversations through middleware. This really isn't my use case. All I want to do is to add a message to a queue using an API. Then when the message is assigned to an agent they can use their normal Genesys SMS communication. Is there an API for this?

Thank you,
Janice

tim.smith · October 12, 2021, 12:48pm

Thanks for the explanation! I think Third Party Emails or Chats are what you're looking for. The gist is that you can ACD route a conversation that doesn't actually have any real media in Genesys Cloud. Because there's no media inherent with these types, you are responsible for presenting the content to the agent. For your scenario, I'd suggest creating a third party email or chat and setting properties on attributes with the information from the Twilio SMS. Then configure the queue you route them through to use a script that reads the information from the participant attributes. The agent can then see this information and take whatever steps you define to handle this kind of conversation.

You'll have to choose between an email or a chat type for this. It's materially irrelevant which you choose as the conversation is handled as neither an email nor a chat; it's just ACD routed and you have to provide the media to the agent either way. If you choose email, there are a bunch of properties that can be set but won't apply because that endpoint does other things as well. The chat endpoint is more straightforward.

It's not that the message itself originates from Genesys, but open messaging requires an integration with a known messaging provider (facebook, what's app, etc.) or implementing your own messaging provider integration. You could in theory build an open messaging integration integration with Twilio SMS for this, but that's likely a lot more work than is necessary, especially since it doesn't sound like there's any requirement to send a message back to the customer via the same channel.

jluncford · October 12, 2021, 3:35pm

Tim,

Thanks for your reply. I was thinking that was the case with the open messaging after studying all the documentation I could find on it yesterday.

I'm a developer on our regular products and jumped into Genesys when we noticed the Twilio issue and previously had no exposure to Genesys. I've been trying to pick up what I need quickly. Unfortunately our Genesys consultant company that normally handles Genesys for us sent me down the wrong API path (twice). I really appreciate all the great help you and others provide here in the Developer Forum.

So configuring a queue to use a script is another thing I know nothing about. Would you please give me some links to help me understand what I need to do to get this working (particularly how to create scripts)?

Thank you,
Janice

tim.smith · October 12, 2021, 3:59pm

Not a problem, glad we can help! All of the docs related to scripts can be found in this section of the Resource Center: About scripting - Genesys Cloud Resource Center. A few topics to take special note of:

Scripting concepts - a quick read that covers the basic parts of a script and the workflow for publishing one.
Script input and output variables - you'll want an input variable with the same name as the participant attribute you set when creating the conversation (via the attributes property in the request body). You can then use these variables to display data in the script using a text component.
Set the script on the queue - Under Set behavior and thresholds for all interaction types, see instructions for configuring the default script.

tim.smith · October 12, 2021, 7:29pm

I'm not sure where it's documented, but you have to enable the script for each media type you want to use it with. All are disabled by default. These options are available on the script > script properties menu when editing the script.

jluncford · October 12, 2021, 7:35pm

Tim,

Hah, you responded just after I deleted my message. I figured that out.
But now, it won't display the fields from my script when I am in the interaction. I thought I'd see them in the Interaction Details tab.

This is a line from the chat message's Participant Data:

context.OriginalSent Mon, 11 Oct 2021 12:35:32 GMT

and this is the corresponding text line in the script: Text Sent: {{context.OriginalSent}}

Apparently context wasn't the right prefix. How do I do this?

Thanks,
Janice

jluncford · October 12, 2021, 8:07pm

I found this:

https://developer.genesys.cloud/blog/2021-03-08-accessing-collected-chat-v2-information/#chat-data-in-the-interaction-details-panel

which gives more info. I'll pursue that. Thanks

tim.smith · October 12, 2021, 9:20pm

When you look at the conversation data from the API, the participant attributes are prefixed with context.. However, the script knows this and looks for participant attributes with that prefix automatically. Your variable names should match exactly what you send in the JSON payload when creating the conversation. Here's some info from the test I ran to confirm the behavior:

Request to POST /api/v2/conversations/chats

{
   "queueId": "158bd9f9-a07c-4a96-a22d-eca72929e3f9",
   "provider": "TESTING",
   "attributes": {
     "myattr1":"my value 1",
     "another_attribute":"another value"
   },
   "customerName": "TEST"
}

tim.smith · October 12, 2021, 9:24pm

On that note, I wanted to mention the API Explorer dev tools. It lets you make requests from your browser, no code required. Though there is also a code editor tool and a few other tools to help make your life easier!

jluncford · October 12, 2021, 9:36pm

Tim,

Thanks, I've already spent a lot of time there. I appreciate your great Dev tools.

Now my problem is that the Scripts icon is disabled on my interaction. When I hover over it I see the disable icon of a circle with a slash through it. What do I have to do to enable it?

Thanks,
Janice

tim.smith · October 12, 2021, 9:41pm

I assume that means that there isn't a script assigned to the conversation, but I'm asking around to confirm. Check to be sure the queue the conversation was assigned from is configured for a script for the media type you're using (chat or email). Also note that the setting probably isn't retroactive, so conversations that were sitting in queue when the setting was set may not get the script assigned.

jluncford · October 12, 2021, 9:55pm

Tim,

Thanks so much. I had previously assigned the script to the queue, but it lost it for some reason. I reassigned it and now all is well.

Janice

jluncford · October 12, 2021, 10:55pm

Tim,

Now that I have my data showing up in the script area of the chat, is there a way for me to use the phone number to start an SMS conversation between the assigned agent and our customer?

Thanks,
Janice

tim.smith · October 13, 2021, 1:07pm

Agents can initiate outbound SMS conversations from the client. It's not part of the same conversation though: Send an outbound message on behalf of a queue - Genesys Cloud Resource Center.

General information on configuring SMS messaging can be found here: About SMS messaging - Genesys Cloud Resource Center.