Dialogue Cloud

Generic Dialogue Provider Developer Guide

Note This product is part of an Invitation Release. Please contact your Sales Contact for more information.

Note Enterprise license and higher

Note Additional Anywhere365 WebAgent license required.

Requirements

  • Generic Dialogue Provider installed

  • ClientId and Client Secret for KeyCloak

 

Introduction

This document describes the use of the Generic Dialogue Provider. Examples are provided.

 

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. Keycloak can be used to asymmetrically sign the tokens with a private key using RS256. 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 re

Send a POST request to KeyCloak token API.

Example:

Copy
HTTP Request
POST https://KEYCLOUK_FQDN/auth/realms/GDP/protocol/openid-connect/token

The following x-www-form-urlencoded body is required:

Key

Value

client_id

<provided client id>

grant_type client_credentials
client_secret <provider client secret

 

Response body example:

Copy
JSON
{
   "access_token":"eyJhbGciOiJSUzI1NzdInR5cCIgOiAiSldUIiwia2lkIiA6ICJvTnltdnNCQWFQYmlxX2VnTzBEVzdJanczdnFjX3ZrT3lSWjNRYlJmQ3NNIn0.eyJleHAiOjE2NDM4MjM4ODcsImlhdCI6MTY0Mzc4Nzg4NywianRpIjoiYWI5MjQzNWYtY2E0OC00MDE4LTgwMmUtNTVkYWJjMmU4YTM4IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL0dEUCIsImF1ZCI6ImFjY291bnQiLCJzdWIiOiJiYjc2MTVjMi02ZjRkLTRiMmEtYTRmZi01OWY5ZDk4MGEwMzciLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJHRFBfVG9rZW4iLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbIioiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJkZWZhdWx0LXJvbGVzLWdkcCJdfSwicmVzb3VyY2VfYWNjZXNzIjp7IkdEUF9Ub2tlbiI6eyJyb2xlcyI6WyJ1bWFfcHJvdGVjdGlvbiJdfSwiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwiY2xpZW50SWQiOiJHRFBfVG9rZW4iLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImNsaWVudEhvc3QiOiIxNzIuMTcuMC4xIiwicHJlZmVycmVkX3VzZXJuYW1lIjoic2VydmljZS1hY2NvdW50LWdkcF90b2tlbiIsImNsaWVudEFkZHJlc3MiOiIxNzIuMTcuMC4xIn0.G8ZQspIJ38ELrXvWle4vW4DIJFWP0hTT4QUeqB16kOxaSuyY8kBAvj200BPJzwQO__ffoyV9TMGIWBHydbOQf4Dws_fVR7oS5ahlZitG8v5Txnm2q053LBkLLJVSmpW9_NvSW4DgegsvPLuAzSsuA7fCg7vId7wozcFUGBVfm0pARhMgo5_Lc9q6Yev03y6ztT3-F5jruqxv6vewTJHmL8bM0-hTcwA3mgWlxlp1k1Sg97f5oNTW97eVagesgTjHrdXdHwLf4FgroIgUZELsq8XQwjimloqMp708s68PEXKMeUpILo7_VlKKefC5jIEbrdDPZQIlQZJioryzG2KlaCw",
   "expires_in":36000,
   "refresh_expires_in":0,
   "token_type":"Bearer",
   "not-before-policy":0,
   "scope":"profile 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:

Copy
POST Request
POST https://FQDN/GenericDialogueProvider/api/v1/message

Request body example:

Copy
JSON
{
   "direction":"Inbound",
   "participants":[
      {
         "role":"Sender",
         "uri":"customer@example.com",
         "name":"Customer Name" // optional
      },
      {
         "role":"Receiver",
         "uri":"agent@anywhere365.net",
         "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 DialogueManager database and the endpoint returns 201 CREATED with the ID of the created message in the response body.

Response body example:

Copy
JSON
{
   "id":"bb539d7c-67fd-4b2b-9a82-9283443c1c57"
}

 

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:

Copy
HTTP Request
POST https://FQDN/GenericDialogueProvider/api/v1/dialogue

Response body example:

Copy
JSON
{
   "id":"4c61290a-b6f6-4db1-b97f-7732764fbb53"
}

 

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:

Copy
HTTP Request
POST https://FQDN/GenericDialogueProvider/api/v1/message/bb539d7c-67fd-4b2b-9a82-9283443c1c57/link

Request body example:

Copy
JSON
{
   "dialogueId":"4c61290a-b6f6-4db1-b97f-7732764fbb53"
}

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 The CallBack feature 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:

Copy
HTTP Request
POST https://FQDN/GenericDialogueProvider/api/v1/subscribe

Request body example:

Copy
JSON
{
   "callbackUrl":"https://mytestapp.free.beeceptor.com/my/api/path"
}

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). An 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:

Copy

HTTP Request

POST https://FQDN/GenericDialogueProvider/api/v1/dialogue/4c61290a-b6f6-4db1-b97f-7732764fbb53/connect

Request body example:

Copy
JSON
{
   "uccId":"ucc_"
}

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:

Copy
HTTP Request
GET https://FQDN/GenericDialogueProvider/api/v1/message/bb539d7c-67fd-4b2b-9a82-9283443c1c57

Response body example:

Copy
JSON
{
   "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@anywhere365.net"
      }
   ],
   "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 event including the message ID of the reply to be sent. This message ID can be used to retrieve the message through a Get 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:

Copy
HTTP Request
PATCH https://FQDN/GenericDialogueProvider/api/v1/message/bb539d7c-67fd-4b2b-9a82-9283443c1c57

Request body example:

Copy
JSON
{
   "providerId":"1234"
}

 

Get 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 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:

Copy
HTTP Request
GET https://FQDN/GenericDialogueProvider/api/v1/dialogue/4c61290a-b6f6-4db1-b97f-7732764fbb53

Response body example:

Copy
JSON
{
   "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:

Copy
HTTP Request
POST https://FQDN/GenericDialogueProvider/api/v1/dialogue/4c61290a-b6f6-4db1-b97f-7732764fbb53/disconnect

Note: 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 it to the 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:

Copy
HTTP Request
POST https://FQDN/GenericDialogueProvider/api/v1/unsubscribe

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 connected before an agent can interact with a it and a subscription 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.

Copy
JSON
{
   "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).

Copy
JSON
{
   "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.

Copy
JSON
{
   "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.

Copy
JSON
{
   "timestamp":"2022-01-01T01:01:01.0000001+00:00",
   "name":"DialogueEvent",
   "type":"Closed",
   "dialogueId":"0473cbce-cc9c-4afb-bb16-53fef61227b8",
   "payload":null
}