Generic Dialogue Provider (GDP) Developer Guide
This article provides an overview of how to use the Generic Dialogue Provider.
Note
An Enterprise license or higher is required to access these features.
Prerequisites
- Generic Dialogue Provider installed, see: Setup Generic Dialogue Provider
- Enabling and configuring AnywhereNow Authentication, see: AnywhereNow Authentication Service
Warning
Enabling AnywhereNow Authentication will impact other applications as well besides GDP. See the list of applications (potentially) affected on the AnywhereNow Authentication page. See: The AnywhereNow products covered by AnywhereNow Authentication:
Authentication
The endpoints of the Generic Dialogue Provider API are secured. The requests to the API have to contain a bearer JWT token in the Authorization header. These tokens needs to be signed for validity. The Generic Dialogue Provider checks them with the public key provided in the appsettings.json.
The following header is required:
| Key | Value |
|---|---|
| Authorization | Bearer <Token> |
Getting a Token
Tokens can be requested via http request
Send a POST request to security token API.
Example:
POST https://login.anywhere365.cloud/auth/realms/<GUID>/protocol/openid-connect/token
Deprecated Authentication Service URL
If you've been not yet migrated to the new Authentication Service, the URL will be:
POST https://auth.anywhere365.cloud/auth/realms/<GUID>/protocol/openid-connect/tokenNote
Replace <GUID GUID stands for Globally Unique Identifier (format is always like 2ed153b4-f632-4766-b846-5b2a769b36d1) and is a pseudo random number used in software applications that is assumed to be unique. The total number of unique keys (2<sup>128</sup> of 3.4028×10<sup>38</sup>) is very large and the probability of the creating the same GUID twice is very small, though not 100% guaranteed. The term GUID is generally used by developers working with Microsoft technologies, while UUID is used everywhere else.> with the "AnywhereNow Tenant ID" provided by your AnywhereNow contact (can be retrieved from OnePortal Formerly known as Partner Portal. A redesigned web portal for managing Dialogue Cloud deployments.).
The following x-www-form-urlencoded body is required:
| Key | Value |
|---|---|
| client_id | genericdialogueprovider |
| grant_type | client_credentials |
| client_secret | <provider client secret> |
Note
client_secret is provided by your AnywhereNow representative (can be retrieved from the OnePortal).
Response body example:
{
"access_token": "****",
"expires_in": 300,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "profile openid email"
}Endpoints
In this section the endpoints are described including examples. The endpoints can be used in the order described.
Create a new inbound message
A typical dialogue is started with an inbound message by a customer.
Send a POST request to the /api/v1/message endpoint to create a new message.
Example:
Request body example:
{
"direction":"Inbound",
"participants":[
{
"role":"Sender",
"uri":"customer@example.com",
"name":"Customer Name" // optional
},
{
"role":"Receiver",
"uri":"agent@anywhere.now",
"name":"Agent Name" // optional
}
],
"content":"my first message",
"sentOrReceived":"2021-11-15T15:15:21.232Z", // optional, will be set to the current date if not provided
"providerId": "00" // optional, message ID in the external system, can be updated later
}Note
There has to be exactly one participant with the role "Sender" and one with the role "Receiver" in the participants list.
When the request is executed, the message will be created, saved in the Dialogue Manager database and the endpoint returns 201 CREATED with the ID of the created message in the response body.
Response body example:
Create a new dialogue
Send a POST request to the /api/v1/dialogue endpoint to create a new dialogue.
A new dialogue will be created, saved in the DialogueManager database and the endpoint returns 201 CREATED with the ID of the created dialogue in the response body.
Example:
Response body example:
Link a message to a dialogue
Send a POST request to the /api/v1/message/{messageId}/link endpoint with the ID of the dialogue in the request body to link a message to a dialogue .
Warning
A message can only be linked to a dialogue once.
The first message linked to a dialogue determines who the customer is.
All consecutive messages that are linked, must contain the same customer. The customer is the Sender in the case of an inbound message and the Receiver in an outbound message.
Example:
POST https://FQDN/GenericDialogueProvider/api/v1/message/bb539d7c-67fd-4b2b-9a82-9283443c1c57/linkRequest body example:
The message is linked to the dialogue and the endpoint returns 200 OK.
Subscribe
A subscription can be done to be able to stay up-to-date with Events happening in the WebAgent, for instance when an agent replies to a message a new event is sent with information about the message. After subscribing, the events are sent to the callback CallBack, an IVR menu feature for voice, enables the customer to leave his / her number to be called back by an available agent during business hours. URL specified in the request (example below). An API has to be running in order to be able to receive the events. They are sent over http(s) using a POST request.
Send a POST request to the /api/v1/subscribe endpoint with the callback URL in the request body to subscribe to events triggered by actions in the WebAgent.
Example:
Request body example:
Note
Only one callback URL can be subscribed to per provider ID configured in SharePoint. If a new subscription is desired, an unsubscribe has to be executed first (see Unsubscribe).
Connect dialogue
Connects a dialogue to a UCC A Unified Contact Center, or UCC, is a queue of interactions (voice, email, IM, etc.) that are handled by Agents. Each UCC has its own settings, IVR menus and Agents. Agents can belong to one or several UCCs and can have multiple skills (competencies). A UCC can be visualized as a contact center “micro service”. Customers can utilize one UCC (e.g. a global helpdesk), a few UCC’s (e.g. for each department or regional office) or hundreds of UCC’s (e.g. for each bed at a hospital). They are interconnected and can all be managed from one central location.. The Dialogue Manager will start a session in the UCC and assign a Skill based on rules defined in the PluginFlowSettings SharePoint list on the first message. In turn the UCC will start hunting for an agent for the dialogue. A conversation will pop up in the WebAgent and a queue item will show up in the queue. All linked messages will appear as soon as an agent accepts the dialogue. The agent can reply or transfer the dialogue to another skill and handle the dialogue.
Note
The Generic Dialogue Provider can handle only one UCC.
Send a POST request to the /api/v1/dialogue/{dialogueId}/connect endpoint with the UCC ID in the request body to connect a dialogue.
Warning
At least one new inbound message is required. In case Dialogue Studio is installed and enabled in the SharePoint of the UCC the dialogue will be connected to Dialogue Studio.
Example:
POST https://FQDN/GenericDialogueProvider/api/v1/dialogue/4c61290a-b6f6-4db1-b97f-7732764fbb53/connectRequest body example:
Note
Make sure the uccId value is in lower case.
The dialogue will be connected and the endpoint returns 200 OK.
The dialogue appears in the WebAgent and can be handled by an agent. Make sure to subscribe before accepting the queue item with the agent to receive Events.
Get a message
A message and its contents can be retrieved though this request. This can be useful to send the message with the external system.
Send a GET request to the /api/v1/message/{messageId} endpoint.
Example:
GET https://FQDN/GenericDialogueProvider/api/v1/message/bb539d7c-67fd-4b2b-9a82-9283443c1c57Response body example:
{
"content":"response from agent",
"dialogueId":"4c61290a-b6f6-4db1-b97f-7732764fbb53",
"direction":"Outbound",
"id":"3657e938-d1ae-42f6-8b89-75e5e39f1be9",
"participants":[
{
"name":"Customer Name",
"role":"Receiver",
"uri":"customer@example.com"
},
{
"name":"Agent Name",
"role":"Sender",
"uri":"agent@anywhere.now"
}
],
"providerId":null,
"sentOrReceived":"2022-01-25T14:12:09.9461771+00:00"
}Update a message
The ID of the message in the external system can be added to the message as providerId. This way a connection has been established between the message in the Dialogue Manager system and the external system (e.g. Exchange), which allows tracking of the messages.
Example
When an agent replies to the inbound message created by the Generic Dialogue Provider an outbound message is created. This will trigger a NewMessage Events including the message ID of the reply to be sent. This message ID can be used to retrieve the message through a Get a message request. After sending this retrieved outbound message with the external system the provider ID can be updated using this patch request.
Send a PATCH request to the /api/v1/message/{messageId} endpoint with the external system message ID as the providerId value in the request body to update the providerId of a message.
Example:
PATCH https://FQDN/GenericDialogueProvider/api/v1/message/bb539d7c-67fd-4b2b-9a82-9283443c1c57Request body example:
Upload attachment
Note
Introduced in DC2024.02
Attachments can be uploaded to messages before the message is linked to a conversation (see Link a message to a dialogue).
Send a POST request to the /api/v1/message/{messageId}/attachment endpoint.
A new attachment will be created, saved in the Dialogue Manager database and the endpoint returns 201 CREATED with the ID of the created attachment in the response body.
Example
POST https://FQDN/GenericDialogueProvider/api/v1/message/4c61290a-b6f6-4db1-b97f-7732764fbb53/attachmentJavaScript example:
function uploadAttachment(messageId, file) {
// Create a FormData object
const formData = new FormData();
// Append the file to the FormData object
formData.append('file', file);
// Configure the fetch request
fetch(`/api/v1/message/${messageId}/attachment`, {
method: 'POST',
body: formData
})
.then(response => {
if (!response.ok) {
throw new Error('Network response was not ok');
}
// Handle successful response as needed
console.log('File uploaded successfully');
})
.catch(error => {
console.error('There was a problem with the fetch operation:', error);
});
}
// Example usage:
const messageId = 'bb539d7c-67fd-4b2b-9a82-9283443c1c57'; // Specify the messageId
const fileInput = document.getElementById('fileInput'); // Assuming you have an input element with id 'fileInput'
fileInput.addEventListener('change', function(event) {
const file = event.target.files[0];
uploadAttachment(messageId, file);
});Download attachments
Note
Introduced in DC2024.02
An attachment can be downloaded from a message.
Send a GET request to the /api/v1/message/{messageId}/attachment/{attachmentId} endpoint
The attachment will be in the response body as a byte array.
Example
GET https://FQDN/GenericDialogueProvider/api/v1/message/4c61290a-b6f6-4db1-b97f-7732764fbb53/attachmentJavaScript example:
function downloadAttachment(messageId, attachmentId) {
fetch(`/api/v1/message/${messageId}/attachment/${attachmentId}`)
.then(response => {
if (!response.ok) {
throw new Error('Network response was not ok');
}
return response.blob();
})
.then(blob => {
// Handle the file data
// For example, you can create a download link or process the file further
// Here's an example of creating a download link:
const url = window.URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'filename'; // Set the desired filename here
document.body.appendChild(a);
a.click();
window.URL.revokeObjectURL(url);
})
.catch(error => {
console.error('There was a problem with the fetch operation:', error);
});
}Remove attachment
Note
Introduced in DC2024.02
An attachment can be removed from a message before the message is linked to a conversation (see: Link a message to a dialogue).
Send a DELETE request to the /api/v1/message/{messageId}/attachment/{attachmentId} endpoint
DELETE /api/v1/message/bb539d7c-67fd-4b2b-9a82-9283443c1c57/attachment/8abeb6f9-c366-4d70-b573-bb5652f65a06Get a dialogue
A dialogue ID and all of its message ID's can be retrieved though this request. This can be useful to see all of the messages in the dialogue. The messages can be retrieved with the Get a message request.
Note
This request can be done when a dialogue has been created without any linked messages to it. The messages array in the response body will then be empty.
Send a GET request to the /api/v1/dialogue/{dialogueId} endpoint.
Example:
GET https://FQDN/GenericDialogueProvider/api/v1/dialogue/4c61290a-b6f6-4db1-b97f-7732764fbb53Response body example:
{
"id":"4c61290a-b6f6-4db1-b97f-7732764fbb53",
"messages":[
{
"id":"3657e938-d1ae-42f6-8b89-75e5e39f1be9"
},
{
"id":"bb539d7c-67fd-4b2b-9a82-9283443c1c57"
}
]
}Disconnect dialogue
When a dialogue is connected (see Connect dialogue), a disconnect can be executed. The disconnect endpoint has the same effect as the agent manually handling the conversation and closing it manually. The dialogue will no longer be visible in the WebAgent, the queue item will disappear, the dialogue will be closed and a Closed Event (see Events) will be sent.
Send a POST request to the /api/v1/{dialogueId}/disconnect endpoint.
Example:
POST https://FQDN/GenericDialogueProvider/api/v1/dialogue/4c61290a-b6f6-4db1-b97f-7732764fbb53/disconnectNote
The agent can no longer interact with the dialogue. The agent can interact again after a new Connect (first Create a new inbound message, then Link a message to a dialogue then execute the Connect dialogue endpoint).
Unsubscribe
It is possible to unsubscribe to the Events, for instance when the Uri to the API which receives the events changes.
Send a POST request to the /api/v1/unsubscribe endpoint.
Example:
Note
After unsubscribing a new subscription can be made (see Subscribe).
Events
Interactions with the dialogues through the WebAgent, or through Dialogue Studio (if it is enabled), will result in events sent through the Generic Dialogue Provider to stay up-to-date. A Dialogue has to be Connect dialogue before an agent can interact with a it and a Subscribe has to have been made before events can be received.
AgentConnected Event
This event is sent when an agent has picked up and accepted the queue item in the WebAgent.
{
"timestamp":"2022-01-01T01:01:01.0000001+00:00",
"name":"DialogueEvent",
"type":"AgentConnected",
"dialogueId":"0473cbce-cc9c-4afb-bb16-53fef61227b8",
"payload":"sip:agent@example.com"
}NewMessage Event
This event is sent when a response to the inbound message is created. This happens after a reply in the WebAgent or a reply from Dialogue Studio (if Dialogue Studio is enabled).
{
"timestamp":"2022-01-01T01:01:01.0000001+00:00",
"name":"DialogueEvent",
"type":"NewMessage",
"dialogueId":"0473cbce-cc9c-4afb-bb16-53fef61227b8",
"payload":"f75ad340-b918-436b-abcc-4682eb73edd5"
}AgentDisconnected Event
This event is sent when the agent disconnects by transferring the dialogue to a skill.
{
"timestamp":"2022-01-01T01:01:01.0000001+00:00",
"name":"DialogueEvent",
"type":"AgentDisconnected",
"dialogueId":"0473cbce-cc9c-4afb-bb16-53fef61227b8",
"payload":"sip:agent@example.com"
}Closed Event
This event is sent when the dialogue is closed. The dialogue will be closed when the agent has handled the dialogue in the WebAgent, when the Disconnect dialogue endpoint is used or when Dialogue Studio is enabled and a "disconnect" end-node is called.
{
"timestamp":"2022-01-01T01:01:01.0000001+00:00",
"name":"DialogueEvent",
"type":"Closed",
"dialogueId":"0473cbce-cc9c-4afb-bb16-53fef61227b8",
"payload":null
}