Terminology

Term	Meaning
Kafka	Cluster of servers that can handle hundreds of megabytes of reads and writes per second. It receives events created in the system, being the central data backbone of LivePerson.
Send API	REST interface that allows consumers to establish conversations via REST interface to UMS.
Messaging Window API	Protocol that allows complete control over the messaging window look, behavior and implementation source. It leverages peripheral REST APIs – like Domain Discovery, Token creation, Agent Profile – and Messaging API, that helps establish the WebSocket connection between the Messaging Window and LivePerson’s UMS Messaging service.
Messaging API	WebSocket interface with which is possible to connect to the UMS Messaging service, creating and maintaining conversations.
Webhooks Notification Service	Channel with which Conversational Cloud sends messaging related events to the connector application (forwards UMS events to the configured endpoints).
Connector application	Brands’ custom app which implements the Connector API to enable their external messaging source with Conversational Cloud.
AppJWT	Json Web Token which contains the OAuth2.0 bearer token to be used within the Connector API’s calls. AppJWT is used to request a ConsumerJWS for each identifiable consumer.
ConsumerJWS	Unique token which identifies the brand’s consumer along their custom identifier in their Conversational Cloud account.
External Consumer ID	Brands’ unique custom identifier for their consumers.
LivePerson Consumer ID	Conversational Cloud default unique consumer identifier.

What is the Connector API?

The Connector API enables developers to build applications that connect common messaging channels with Conversational Cloud.

A connector is a broker between Conversational Cloud data and a messaging channel's messages and data. The connector receives messages and events from a messaging platform, transforms them into the Conversational Cloud language and passes it to the agent.

The Connector API allows to create/open and close conversations, pass messages to and from the agents, set the consumer profile upon conversation creation.

In addition, the connector can also make sure that the consumer will be notified of agent activity during the conversation, and vice versa, using Webhooks notifications.

From brands perspective, the Connector API consists of two main components:

Send API: with which is possible to send HTTPS requests based on the Messaging Window API framework. This component of the Connector API handles communication between the Connector and Conversational Cloud, allowing to communicate events from the third party application to Conversational Cloud.
Webhooks Notification Service: this component sends notifications from Conversational Cloud based on the Messaging Window API framework to the connector Webhooks HTTPS-endpoints. These notifications communicate any messaging events both from the agent and consumer to the connector, such as agent/consumer replies, closed conversation, typing and so on.

Why do we use the Connector API?

By providing brands the Connector API, we allow them to keep their messaging implementations - external bot, custom messaging source connectors - outside of LivePerson.

For example: a brand can have a bot talking to a consumer on a given channel with no involvement from LivePerson. When the bot needs a human to be involved, it can use the Connector API to create a conversation and inform LivePerson of any consumer messages.

Indeed, there are two primary reasons / use cases to utilize the Connector API:

Brands - To create their own custom connectors. This will enable their consumers to engage with them via many distribution channels whilst using more than one device, not using our out of the box dedicated connectors. Another example would be a connector for an SMS Gateway of their choice, different from Twilio. A connector developed by a brand would normally be hosted on the brand's servers.
Product solutions - Connector applications developed by LivePerson, focusing on the same functionalities as the above use case except that we are providing it to them. In this case, our deliverables will be hosted by our cloud solutions.

Here below and example of Connector API solution:

Pros and cons

Here are summarized the positive and negative consequences of brand adopting of Connector API:

Pros	Cons
Cheaper for the brand as they don’t pay credits for conversations that were fully resolved by the bot.	LivePerson makes less earnings from bots being outside of the platform.
The Connector API works with any and every platform and technology stack
Not much work on LivePerson side outside of consulting

Capabilities enabled by the Connector API

Consumer side

Capability	Achieved by	Endpoint
Create a new conversation and send SDEs in one step	Messaging SEND API	CONVERSATION
Send text messages	Messaging SEND API	SEND
Send images	Messaging SEND API	SEND
See SENT, READ and RECEIVED indications	Webhooks	N/A
Send chat state events (COMPOSING (i.e. Consumer is typing), ACTIVE, INACTIVE etc.)	Messaging SEND API	SEND
See chat state events (COMPOSING (i.e. Agent is typing), ACTIVE, INACTIVE etc.)	Webhooks	N/A
Send conversation metadata - Structured content identifier metadata	Messaging SEND API	SEND
Close conversation	Messaging SEND API	SEND
Send CSAT (Customer Satisfaction) & FCR (First Contact Resolution) ratings	Messaging SEND API	SEND

Agent side

Being the Connector API implementation dedicated only for applications/connectors on the consumer side, the below agent capabilities are the ones already provided out of the box by Conversational Cloud and the Agent Workspace. Connector API currently support all of these:

Resume a conversation
Transfer a conversation to a different skill
Send a text message
Send structured content
See SENT, READ and RECEIVED indications
See indication that the consumer is typing
Close a conversation

In other words, the Connector API brings new functionality (via the Messaging Send API and Webhooks) only to the consumer side. On the agent side, it simply supports some of the already existing Conversational Cloud capabilities and allows them to be used in connector applications.

Technical Details [LivePerson]

From LivePerson developers point of view, Connector API consist of:

The inbound channel, represented by the Send API
The outbound channel, done by the WebHooks Notification Service

The configuration service, containing the configuration with Houston.

The must-have dependencies are AppJWT and AC AppInstall.

Here below the high level architecture of the Connector API:

Configuration steps

1 - Onboard the connector [Brand + LivePerson]

The connector is a server application used to make HTTPS calls on behalf of consumers to Conversational Cloud. For that purpose, the application must be registered and known to Conversational Cloud for authorization and user validation. This process can happen even before any connector development.

In order to register the application, brands should contact us: they need to provide details regarding their connector application, via a predetermined JSON schema (known as the Application Installation Manifest).

Here the Application Installation Manifest JSON template to be filled by the brand:

The main sections to be filled are:

client_name - name of brand’s Connector Application. This will also be shown to the agent as the source of the conversation in the Consumer Info widget.
description - optional key.
Webhooks URL endpoints - these will be used as URL endpoints for Conversational Cloud to send its notification events to the brand's connector. Note: these endpoints must be exposed as HTTPS.
max_retries - optional key. Used to configure the maximum number of retries which our Webhooks service will attempt in case of a failed request.
Engagement related fields - this affects the Engagement design possibilities when designing a campaign for messaging. Without a clear reason to change them, brands can use the default values found in the schema.

After the brand completes the JSON Template with the required data, the LivePerson team will register that connector application.

As an alternative to writing the whole JSON payload, brands can login into the Connector Hub using their account Id credentials. In this page, is it possible to create the Connector application using our UI, specifying step by step the data needed.

With this tool, brands can autonomously get their App credentials without involving the LivePerson engineering team, so the next step 2 can be avoided.

2 - Creating the brand application on Houston [LivePerson]

Once the brand sent us the App Installation Manifest JSON, to install it on Houston:

Go to Supportal page and using LPA credentials access to Houston page for the brand account ID;
Select App Management tab:

Copy and paste the App Installation Manifest into the App installation tab in the Template text box and press the Install button:

When installation is complete and successful, it should be returned a 201 Created response;
Go to the Private installed Apps tab and save the App Installation Id and Secret values:

Share these values to the brand to let them perform any Connector API calls.

3 - Getting an application JWT [Brand]

LivePerson uses OAuth 2.0 grant type Client Credentials in order to allow apps to access the Send API. The responsible Authorization Server Sentinel generates access tokens for any rightfully authorized client. The access token is a JSON Web Token (JWT) encoding information about the granted access and must be attached to any follow-up request to the Send API. The AppJWT identifies the connector to be a valid application, which is allowed to identify consumers and send consumer events to the messaging service.

So, after LivePerson successfully registered the connector, brands will receive two important parameter values which will serve to authorize the connector application prior to using the Connector API:

The app installation id, also named as client_id
- Example value 75588e18-0213-4e33-8174-883acac7e3c4
The app secret, also named as client_secret
- Example value kgvbkk7glku72jgtmpi6l4a872

These will be used for the first authorization request to Conversational Cloud in order to identify the brand connector and provide it with an AppJWT.

Here below the HTTPS request to get the AppJWT token:

Method: POST

URL:

https://{{sentinelDomain}}/sentinel/api/account/{{accountID}}/app/token?v=1.0&grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}

Content-Type: application/x-www-form-urlencoded

sentinelDomain is retrievable from Domain API searching for sentinel

The sentinel service will answer in accordance with OAuth 2.0, providing the AppJWT as a bearer token, in this form:

{

"access_token": "----AppJWT----",

"token_type": "Bearer"

}

The AppJWT has an expiration time of 1 hour, not editable.

4 - Getting a consumer JWS [Brand]

The AppJWT is not sufficient to identify a consumer with Conversational Cloud. Using a valid AppJWT, brands can obtain a consumer JWS (JSON Web Signature) to identify the customers in Conversational Cloud.

The Consumer JWS is the unique identifier of the user (customer) and used by the connector in conjunction with the AppJWT to access Conversational Cloud on behalf of the consumer. Both the ConsumerJWS and the AppJWT will be passed in the headers of both the conversation and send requests to Conversational Cloud in order to authenticate the request.

Here below the HTTPS request to get the ConsumerJWS token:

Method: POST

URL:

https://{{idpDomain}}/api/account/{{accountID}}/consumer?v=1.0

Content-Type: application/json

Authorization: ----AppJWT----

Body:

{

"ext_consumer_id":"---external_consumer_identifier---"

}

idpDomain is retrievable from Domain API searching for idp

As response body:

{

"token": "----ConsumerJWS----"

}

The ConsumerJWS structure, if decoded, is:

{

"account_id": "---LP_CC_Account_id---",

"ext_consumer_id": "---external_consumer_identifier---",

"lp_consumer_id": "---standard_LP_user_id---"

}

Which contains the userId value to correctly recognize the customer within the Conversational Cloud. The ConsumerJWS has no expiration time.

5 - Develop and run the connector [Brand]

The previously obtained AppJWT and ConsumerJWS will be passed together in the requests’ headers of every API call to Conversational Cloud, respectively in the HttpHeader.Authorization and HttpHeader.X-LP-ON-BEHALF for authorization of the connector and identification of the consumer.

6 - Architectural view of initial configuration [LivePerson]

Here below two schematic overview of the previous explained steps:

Send API

The Send API consists of two types of calls:

CONVERSATION - Batch Payload. This API call creates/opens a new conversation and sets the consumer profile.
SEND - One Payload. This API call can be used to send a message and close a conversation or set the consumer profile.

Message format

Every message sent by the brand’s client or by the server should be translated into an appropriate JSON format.

The kind of message is denoted by the kind property in the top level of the JSON object, and can be any of the following:

req, a message sent from the client/connector. The server will reply with a response message.
resp, a message sent by the server in response to a client/connector request message.
notification, a message sent from the server to the client/connector.

Every message has a type. The structure of the body of the message can be changed for different types. The type of message is denoted by the type property in the top level of the JSON object.

Below is an example of a request message with the type of ms.PublishEvent:

{

"kind": "req",

"id": "1",

"type": "ms.PublishEvent",

"body": {

"dialogId": "{{conversationId}}",

"event": {

"type": "ContentEvent",

"contentType": "text/plain",

"message": "Text message from messaging connector"

}

}

}

Below is an example of a request message with the type of cm.UpdateConversationField:

{

"kind": "req",

"id": 5,

"type": "cm.UpdateConversationField",

"body": {

"conversationId": "{{conversationId}}",

"conversationField": {

"field": "CSATRate",

"csatRate": 5,

"csatResolutionConfirmation": true,

"status": "FILLED"

}

}

}

General response format

Responses are sent with some kind of correlation to the request that they are answering. Every request message must state the id string for the request. The server will reply with the same id in the response message as the value of the reqId field in the top level JSON object of the response message.

The sequence field is an optional counter. For example, tracking the times that the same request has been sent to Conversational Cloud, doubles its value, starting with zero value for the first request, two for the second request, four for the third request, etc.

The response message will also contain a code field. This field will be populated with the status code of the request, following the HTTP semantics.

Below is an example of a response message to the previous shown ms.PublishEvent request (reqId = 1):

{

"code": "OK",

"body": {

"sequence": 0

},

"reqId": "1"

}

HTTP Status codes list:

Code	Description
200	Successful response. Returns a message and a ConversationID.
400	The input was invalid, please check the JSON body.
401	Unauthorized. Check headers or `AppJWT` expiration time or the `ConsumerJWS` validity.
429	Too many requests. API limit reached.

Errors responses

The Send API returns an error response for every authorization or authentication failure. Any error response contains a JSON payload which details the error title, details about the error and both an HTTP error code and a specific code for the type of error encountered.

Here below a response example if the AppJWT is missing:

{

"kind": "resp",

"code": 401,

"body": {

"title": "AppJWT is missing",

"details": "AUTHORIZATION header is not present",

"errorCode": 40104

},

"type": ".ReqBody$ErrorResp"

}

The following table shown error response body structure:

Property	Description	Value Type	Notes
kind	The messaging event kind.	String: “resp”	Always use resp for responses.
code	The HTTP status code.	Integer: 401	See the next table for the error codes
body	JSON body detailing the error.	Object: see below rows
body.title	Title of the error response.	String: “AppJWT is missing”
body.details	Details about the error.	String: “AUTHORIZATION header is not present”
body.errorCode	A unique code identifying each possible error response.	Integer: 40104	The first three digits represent the HTTP status code and the last two digits are a changing number. See the next table for further details.
type	The type of the response.	String: .ReqBody$ErrorResp	Always .ReqBody$ErrorResp for error response.

Error Code	Title	Details	Comment
40001	Missing parameter	Brand Id is missing	This response will also be generated when mandatory claims in the AppJwt are missing. For example, when claim iss is not present or does not have the value sentinel.
40102	Invalid AppJWT	AppJWT has expired or is invalid
40103	Invalid ConsumerJWS	ConsumerJWS is invalid
40104	ConsumerJWS is missing	X_ON_BEHALF_HEADER is not present
40105	AppJWT is missing	AUTHORIZATION header is not present

CONVERSATION

The CONVERSATION method is a batch-endpoint (this means that the body can contain several payloads). It takes a set of at least two JSON payloads.

The order of the array is important, since Conversational Cloud expects to receive these payloads in that order. It returns an array of corresponding JSON payloads in the response.

The most important value obtained by this endpoint is the conversationId which will be used for the subsequent SEND calls to Conversational Cloud.

Request details

Method: POST

URL:

https://{{domain}}/api/account/{{accountID}}/messaging/consumer/conversation?v=3

Header:

Content-Type: application/json

Authorization: {{AppJWT}}

X-LP-ON-BEHALF: {{ConsumerJWS}}

Body:

See the next paragraphs

domain is retrievable from Domain API searching for asyncMessagingEnt.

This method expects a set of JSON payloads, each representing a different type of request to the Conversational Cloud messaging service. The order of the payloads is important in order to create a new conversation.

First, the payload with the type userprofile.SetUserProfile appears;
Then, the payload with the type cm.ConsumerRequestConversation appears.

The payload with the type userprofile.SetUserProfile is mandatory. Its body can essentially be passed empty or with some engagement attributes in order for the Agent to see the Consumer Info in the Conversational Cloud Agent Workspace.

For the sake of simplicity, the next request body example illustrates the minimal JSON payload which is mandatory for conversation creation in Conversational Cloud:

[

{

"kind": "req",

"id": "1,",

"type": "userprofile.SetUserProfile",

"body": {}

},

{

"kind": "req",

"id": "2,",

"type": "cm.ConsumerRequestConversation",

"body": {

"brandId": "{{accountID}}"

}

}

]

The above payloads are only shown for example purposes. We strongly recommend not to create conversations in that way, without user information passed in the body of the both payloads.

As best practice, we recommend always adding users information through the conversation creation, in order to enable the routing / targeting of the right skill or engagement in Conversational Cloud.

Passing user information is done through the payload with the type userprofile.SetUserProfile:

If the authenticatedData object in the body is not passed (left blank or deleted altogether), there will be no consumer information for the Agent in Conversational Cloud's Agent Workspace.
Under the authenticatedData object, you can pass an lp_sdes array. This array is used to send engagement attributes (SDEs) to Conversational Cloud.
The SDEs are used to populate the consumer information widget for the Agent, in Conversational Cloud's Agent Workspace.

Again, as a best practice we strongly recommend to pass SDEs when creating a new conversation.

The SDEs supported for sending are the Customer Info and Personal Info SDEs.

Here a request body example illustrating how to create a conversation and send SDEs in one request:

[{

"kind": "req",

"id": "1,",

"type": "userprofile.SetUserProfile",

"body": {

"authenticatedData": {

"lp_sdes": [

{

"type": "ctmrinfo",

"info": {

"socialId": "1234567890",

"ctype": "vip"

}

},

{

"type": "personal",

"personal": {

"firstname": "John",

"lastname": "Doe",

"gender": "MALE"

}

}

]

}

}

},

{

"kind": "req",

"id": "2,",

"type": "cm.ConsumerRequestConversation",

"body": {

"brandId": "{{accountID}}"

}

}]

In the following table, are listed every properties you can add to the cm.ConsumerRequestConversation.body payload:

Property	Description	Value Type	Mandatory
ttrDefName	Defines the urgency of the conversation	String: "NORMAL" / "URGENT" / "PRIORITIZED" / null	x
campaignInfo	Contains the campaignId and engagementId fields	Strings: { "campaignId": "99999", "engagementId": "888888" }	x
channelType	Which channel type is used	String: Always use "MESSAGING”	✓
brandId	LivePerson site ID - Account ID	String	✓
skillId	Skill ID you would like to route the conversation to	String: use “-1” as default to target all skills available	x
conversationContext	Describes the conversation environment	SharkContext object made of strings. In the next section will be shown in details	x

The cm.ConsumerRequestConversation.body payload can contain the conversationContext field: its elements are related to the consumer session, with all details needed for monitoring and reporting purposes. Here below the list:

Property	Description	Value Type	Mandatory
visitorId	The LivePerson identifier to the current consumer device	String: "A3ZTY3Zjk1MDExZTczYTU4"	x
sessionId	The LivePerson identifier to the current monitor session of this consumer device	String: "ys2wSqaSRSOJGki7VhEDKQ"	x
interactionContextId	contextId retrieved by the Engagement Monitoring API endpoint	String: “2”	x
type	Type of conversationContext	String: Always use "SharkContext" when using Monitoring API properties	x
lang	The conversation language, according to the IETF (ISO-639-1 and ISO-3166)	String: "en-US" Check first if the language used is configured for the engagement	x

Response details

An example of successful response (Code status 200). The response array will contains single payloads for every request payloads sent (reqIDs):

[

{

"code": "OK",

"body": {

"msg": "OK User Profile set successfully"

},

"reqId": "1,"

},

{

"code": "OK",

"body": {

"conversationId": "8602832d-dce1-446b-8445-0d51f5926a42"

},

"reqId": "2,"

}

]

Authentication

Connector API doesn’t support authentication, like we usually do with oAuth2.0 Code or Implicit flow. The CONVERSATION call is not able to federate any brand’s authentication.

The presence of the authenticatedData field in the userprofile.SetUserProfile payload only indicates the type of SDEs passed: this object can contain Customer Info and Personal Info fields, which LivePerson usually links to any authenticated data. In this case the entire object only adds customers information, needed by the brand for their Agents.

This means the Conversational Cloud will show any of these data as “authenticated”, with the blue tick, but actually they won't be, as no oAuth2.0 flow is used.

Routing settings

In the conversation creation phase, i.e. through the first CONVERSATION call, it is possible to enforce routing in three ways:

Using the SkillID field in the cm.ConsumerRequestConversation.body. With this brands can directly route conversations to the target skills.
Using the SDEs rules on Houston. In this way is possible to create routing rules basing on:
1. CustomerInfo.CustomerType
2. CustomerInfo.CompanyBranch
3. PersonalInfo.Gender
4. PersonalInfo.Language

This configuration has to be done by LivePerson on the brand’s account backend.

Setting up campaigns and engagements as usual and use the Campaign ID and the Engagement ID to the Conversational Cloud through the campaignInfo field in the cm.ConsumerRequestConversation.body. In this way it is possible to route the consumer conversation to the desired skill as designed by the Campaign Builder. This will also allow the Agent to see the name of the brand connector as the source of the conversation in the Consumer info widget

The best practice recommended by LivePerson is to use the third way. For that, in order to retrieve the campaign properties, you must use the Monitoring API.

The Engagement method of the Monitoring API allows brands to obtain an engagement for a consumer only if both the following apply:

There is no active conversation for this consumer;
The consumer is eligible for an engagement.

By sending the user required information, will be returned the engagement properties: campaignId, engagementId, visitorId, sessionId and more, to fill the campaignInfo field and the conversationContext object in the cm.ConsumerRequestConversation.body payload of the CONVERSATION call.

The following request body example shows how to use these data for routing:

[{

"kind": "req",

"id": "1,",

"type": "userprofile.SetUserProfile",

"body": {

"authenticatedData": {

"lp_sdes": [

{

"type": "ctmrinfo",

"info": {

"socialId": "1234567890",

"ctype": "vip"

}

},

{

"type": "personal",

"personal": {

"firstname": "John",

"lastname": "Doe",

"gender": "MALE"

}

}

]

}

}

},

{

"kind": "req",

"id": "2,",

"type": "cm.ConsumerRequestConversation",

"body": {

"ttrDefName": "NORMAL",

"campaignInfo": {

"campaignId": "99999",

"engagementId": "888888"

},

"conversationContext": {

"visitorId": "A3ZTY3Zjk1MDExZTczYTU4",

"sessionId": "ys2wSqaSRSOJGki7VhEDKQ",

"interactionContextId": "2",

"type": "SharkContext",

"lang": "en-US"

},

"channelType": "MESSAGING",

"brandId": "{{accountID}}",

"skillId": "-1"

}

}

]

SEND

The SEND method allows sending a JSON payload to the Conversational Cloud. This method, differently from the CONVERSATION endpoint, is used mainly to send a message from the consumer to the agent or to close a conversation.

The connector application can use this method for one action at a time:

Send a text message
Close a conversation
Send metadata
Set user profile (send SDEs)
Send chat-state events (e.g. consumer is typing)

Request details

Method: POST

URL:

https://{{domain}}/api/account/{{accountID}}/messaging/consumer/conversation/send?v=3

Header:

Content-Type: application/json

Authorization: {{AppJWT}}

X-LP-ON-BEHALF: {{ConsumerJWS}}

Body:

Messaging Window API JSON payload.

This payload would normally have one of these types:

ms.PublishEvent
cm.UpdateConversationField

See the next paragraphs for request examples

domain is retrievable from Domain API searching for asyncMessagingEnt.
For the JSON Body payload, see the next Messaging Window API section with the examples. For a more complete list use the Request Builder to get an example of the accepted payloads.

Payload structures

In the following table, are listed main properties you can add to the ms.PublishEvent type body payload:

Property

Description

Value Type

Mandatory

dialogId

The conversationId created by CONVERSATION request

String: "8602832d-dce1-446b-8445-0d51f5926a42"

✓

event

The messaging event object

It contains different types of events, with related fields.

Below there is a detailed list of the data to be passed.

✓

Based on the event.type, it will be sent different payload structures depending on the use case chosen. Here a comprehensive list:

1 - Send a text message (consumer to agent)

Property	Description	Value Type	Mandatory
type	The messaging event type	ContentEvent	✓
contentType	Which content is sent	String: "text/plain" for text message	✓
message	Text/content message	String	✓

JSON example

{

"kind":"req",

"id":"1",

"type":"ms.PublishEvent",

"body":{

"dialogId":"{{conversationId}}",

"event":{

"type":"ContentEvent",

"contentType":"text/plain",

"message":"Hi from Send Message only - Send a line"

}

}

}

2 - Send a file (consumer to agent)

To successfully enable a brand’s consumer to send a file (images) during a conversation, the brand’s connector application needs to follow these steps:

Request an upload URL for the consumer file using the payload type ms.GenerateURLForUploadFile, to subsequently send the consumer file in the LivePerson Swift storage service.

Here below the payload body details:

Property

Description

Value Type

Mandatory

fileSize

File size given in Bytes. Limited to 3MB. Oversized requests will be rejected

String

✓

fileType

Which content is sent

String:

“JPG” / “JPEG” / “PNG” / “GIF”

✓

{

"kind":"req"

"id":"3",

"type":"ms.GenerateURLForUploadFile",

"body":{

"fileSize":"1024",

"fileType":"JPG"

},

}

Extract relativePath, temp_url_sig, temp_url_expires from the response, to use them in the next request. Here below a response example:

{

"code": "OK",

"body": {

"relativePath": "/v1/AUTH_async-images/64467156/6be59ddb8f54d88845a4fd4987cf5717878eacd2f893b7a7331717f113d2589f_uuid_326931e5-062f-46cb-b981-a383040d2cb8_04-06-2018_04-10-59-845.PNG",

"queryParams": {

"temp_url_sig": "dd9e3bdb2bebbc254653f0d090922b40489ca6e",

"temp_url_expires": "1528099919"

}

},

"reqId": "3"

}

Upload the file to the storage (as binary using the swift storage)

Method: PUT

URL:

https://{{swiftDomain}}/{{relativePath}}?temp_url_sig={{temp_url_sig}}&temp_url_expires={{temp_url_expires}}

swiftDomain is retrievable from Domain API searching for swift.
relativePath, temp_url_sig, temp_url_expires from the previous response (file expiration is set to 1 minute by default).
Successful response will give HTTP code status 201, else 401 for failure.

Publish the file as a message inside the conversation

Once the consumer file is saved in storage, the connector app will publish the file URL along with an optional caption and thumbnail as a message for the agent.

To send the optional thumbnail, the connector app needs to convert the image file to base64. The output will populate the parameter imageData.

Here below the payload body details:

Property	Description	Value Type	Mandatory
dialogId	The conversationId created by CONVERSATION request	String: "8602832d-dce1-446b-8445-0d51f5926a42"	✓
type	The messaging event type	String: “ContentEvent”	✓
contentType	Which content is sent	String: "hosted/file"	✓
message	Array of properties describing the file	Object: see below rows	✓
message.caption	Description	String: "File logo"	x
message.relativePath	Path extracted on step 2	String	✓
message.fileType	Same type of the step 1	String: “JPG” / “JPEG” / “PNG” / “GIF”	✓
message.preview	The base64 data conversion of the file	String: "data:image/png;base64,{{imageData}}"	x

Here below an example of the request for publishing the image file link:

{

"kind": "req",

"id": "3",

"type": "ms.PublishEvent",

"body": {

"dialogId": "{conversationId}",

"event": {

"type": "ContentEvent",

"message": {

"caption": "File logo",

"relativePath": "{{relativePath}}",

"fileType": "JPEG",

"preview": "data:image/png;base64,{{imageData}}"

},

"contentType": "hosted/file"

}

}

}

Request a download URL for the consumer file using the payload type ms.GenerateURLForDownloadFile. Here the payload body details:

Property

Description

Value Type

Mandatory

relativePath

Path extracted on step 2

String

✓

Example request:

{

"kind": "req",

"id": "3",

"type": "ms.GenerateURLForDownloadFile",

"body": {

"relativePath": "{{relativePath}}"

}

}

The response details will contain relativePath, temp_url_sig, temp_url_expires (like the upload step), to be used for the next step. Here an example:

{

"code": "OK",

"body": {

"relativePath": "/v1/AUTH_async-images/64467156/5f3aab9eb95ff60f159cab500e3a83f1aba98a99749c07143fbda2dece70e601_uuid_5c68d4e8-3bde-40ac-86c2-1e5f43089cd4_07-06-2018_09-47-15-947.JPEG",

"queryParams": {

"temp_url_sig": "384bcb0b188920909d4a068473824e964ecbffcd",

"temp_url_expires": "1528379356"

}

},

"reqId": "3"

}

Download the file from the storage (use this call like for the upload step)

Method: GET

URL:

https://{{swiftDomain}}/{{relativePath}}?temp_url_sig={{temp_url_sig}}&temp_url_expires={{temp_url_expires}}

swiftDomain is retrievable from Domain API searching for swift.
relativePath, temp_url_sig, temp_url_expires from the previous response (file expiration is set to 1 minute by default).
Successful response will give HTTP code status 200, else 401 for failure.

3 - Send messaging State Events

Property	Description	Value Type	Mandatory
type	The messaging event type	String: “ContentEvent”	✓
contentType	Which content is sent	String: "text/plain" for text message	✓
message	Text/content message	String	✓

JSON example

{

"kind":"req",

"id":"1",

"type":"ms.PublishEvent",

"body":{

"dialogId":"{{conversationId}}",

"event":{

"type":"ContentEvent",

"contentType":"text/plain",

"message":"Hi from Send Message only - Send a line"

}

}

}

4 - Consumer accepted a message

Property	Description	Value Type	Mandatory
type	The messaging event type	String: “AcceptStatusEvent”	✓
status	Acceptance status of the message sent by the Agent to the Consumer	String: "ACCEPT" (message was accepted by the consumer) "READ" (message was read by the consumer) "ACCESS" (Consumer has accessed the file) "NACK" (message not received) "ACTION" (used in conjunction with metadata to reply on structured content sent by the Agent)	✓
sequenceList	List of sequence values	Array of integers: [1,2]	✓

JSON example

{

"kind":"req",

"id": "0",

"type": "ms.PublishEvent",

"body": {

"dialogId": "{{conversationId}}",

"event": {

"type": "AcceptStatusEvent",

"status": "ACCEPT",

"sequenceList": [1,2]

}

}

}

5 - Close a conversation

Here below the two ways to close a conversation:

Close the conversation

{

"kind":"req",

"id":1,

"type":"cm.UpdateConversationField",

"body": {

"conversationId":"{{conversationId}}",

"conversationField":{

"field":"ConversationStateField",

"conversationState":"CLOSE"

}

}

}

Close the dialog - for triggering PCS bots

{

"kind": "req",

"id": 1,

"type": "cm.UpdateConversationField"

"body": {

"conversationId": "{{conversationId}}",

"conversationField": {

"field": "DialogChange",

"field": "UPDATE",

"dialog": {

"dialogId": "{{conversationId}}",

"state": "CLOSE",

"closedCause": "Closed by consumer"

}

}

}

}

6 - General JSON examples

Consumer is typing

{

"kind":"req",

"id":"1",

"type":"ms.PublishEvent",

"body":{

"dialogId":"{{conversationId}}",

"event":{

"type":"ChatStateEvent",

"chatState":"COMPOSING"

}

}

}

Consumer has accepted the message

{

"kind":"req",

"id": "0",

"type": "ms.PublishEvent",

"body": {

"dialogId": "{{conversationId}}",

"event": {

"type": "AcceptStatusEvent",

"status": "ACCEPT",

"sequenceList": [1,2]

}

}

}

Webhooks Notification Service

Webhooks limitations

Brands should consider that:

Webhooks events order is on best effort basis and it is not guaranteed;
For example, if a notification of a certain event failed the first time and was only delivered successfully after one or more retries, then it is possible that a subsequent event will be delivered before.
As long as the retry policy is not exhausted, then event duplications are possible.
Data event loss is possible;
- For example, when a failed notification request is retried, once the retry policy is exhausted - e.g. all the retry attempts fail, the event will be dropped.

Webhooks best practises

On the brand’s servers it is important that the Webhook endpoint is highly available and resilient. In order to reduce the probability of losing events, brands should decouple receiving notifications from business logic, e.g. by placing incoming notifications in a queue and returning HTTP 200 OK immediately.

We're authorizing you