Avaya Experience Platform™
Developer Guides

Custom Messaging

Suggest Edits

What is Custom Messaging?

Avaya Experience Platform™ Digital provides built-in In-App and Social messaging capabilities. However, if you want to integrate an existing messaging infrastructure or any other third-party messaging providers with Avaya Experience Platform™, you can use our APIs and achieve this. Such an integration is called Custom Messaging and the next sections explain in detail how it can be accomplished.

Prerequisites

Before we can start, you'll need to make sure you have a few things set up

🚧

You must be an Avaya Experience Platform™ customer with Messaging enabled

In order to use Custom Messaging, you must be an Avaya Experience Platform™ customer with Messaging enabled on your account. If you are not currently or lost your credentials, please contact your Avaya representative.

📘

You must have a Client ID and Secret Provided to you by Your Avaya Experience Platform™ Administrator or Representative

Please review How to Authenticate with Avaya Experience Platform™ APIs to continue

Overview

To integrate your messaging provider with Avaya Experience Platform™, a Messaging Connector can be built which on the one hand communicates with the provider and on the other hand calls Avaya Experience Platform™ Digital APIs for sending and receiving messages. The Messaging Connector may be a standalone service or can be a piece of software hosted on your Messaging Provider infrastructure. An overview of how custom messaging can be accomplished is provided in the image below. The following sections describe each step involved in custom messaging integration in detail.

Overview Flow

Add Channel Provider

To begin Custom Messaging integration, an Element representing the Custom Messaging Connector needs to be added in the Avaya Experience Platform™ Administration. The connector is the source of channel for Avaya Experience Platform™, hence it is also referred as the Channel Provider. To add a Custom Messaging Connector Element, follow the steps below

  1. Go to your Avaya Experience Platform™ Administration application
  2. Sign in as an Account Administrator
  3. Navigate to "Element Inventory" and select "New" > "Digital Connector" > "Messaging"
  4. Provide details about your Messaging Connector
  • Name - Any name that you would like to give to your new Messaging Connector Element
  • Callback URL - A callback URL hosted by your connector to receive events related to integrations when they are created, updated or deleted by Account Administrator for this Element. This is an optional field. If the callback URL is provided, the operations on the integrations will fail if the callback request fails. Details about the information sent as part of the callback request is provided here
  1. Click "Save" once you have filled the data.
  2. Your new Messaging Connector Element will appear in the list of Elements.
  3. You can edit the Messaging Connector Element and copy the "Channel Provider Id" which was automatically generated by the system to uniquely identify this Element. This Id must be used to fill the value of the field channelProviderId which is required while subscribing to Digital Notifications and also send messages into Avaya Experience Platform™.

If your business needs integrations with multiple Providers and you wish to handle this using separate Connectors, you can create multiple Custom Messaging Elements representing each Connector. The number of Custom Messaging Connectors that can be created for an Account is limited to 5.

Create and Configure Custom Messaging Integration

Once the Custom Messaging Connector Element is created, the next step is to create an Integration for it. An Integration represents the entry point for messaging interactions related to a business function. Various configurations that define how a messaging interaction will be treated in the contact center, like routing queues, routing attributes, orchestration workflows, automated apps and context data matching rules, are associated with an Integration. For a Custom Messaging Connector Element, a maximum of 10 Integrations can be created to represent various business functions. To create a Custom Messaging Integration, follow the below steps

  1. Go to your Avaya Experience Platform™ Administration application
  2. Sign in as an Account Administrator
  3. Navigate to "Channels" and select "Messaging"
  4. From the "Integration Type" dropdown, select "Custom Messaging"
  5. A second drop down with the name "Providers" will appear. Select the Custom Messaging Connector Element that you had created in the previous section.
  6. Once you select the Element, a "Create Integration" button will appear. Once you click on this button, you will be redirected to "New Integration" page where you can provide the "Name" of Integration.
  7. Click on the "Save" button, to create the new Integration which will be visible within the list of Integrations
  8. From this list of Integrations, you can select the Integration and "Edit" it to change the name or copy the "Integration Id" which was automatically generated by the system to uniquely identify this Integration. This Id will be required to be passed as businessAccountName in the API to send messages into Avaya Experience Platform™.
  9. In the list of Integrations, you can also select the Integration and "Configure Routing Settings" to define the business rules for this Integration.

Subscribing for Engagement Events

In order to receive events occurring for engagements handled inside the Avaya Experience Platform™, a Digital Notifications subscription will be required for the Custom Messaging Connector. This can be done using the Create Subscription API. The Connector needs to expose a REST endpoint and pass the URL as the callbackUrl along with the interested eventTypes and its channelProviderId while creating the subscription. The channelProviderId here is the "Channel Provider Id" field which is visible on editing the Custom Messaging Connector Element (discussed in this section).

When an event related to an engagement occurs within Avaya Experience Platform™, based on the eventTypes subscribed, the registered callbackUrl will be invoked with the entire event data. The REST endpoint on the Connector which is hosting the callbackUrl must return 200 OK as the HTTP response. In case the Connector fails to process the request and returns a retryable error response, Avaya Experience Platform™ will keep retrying to send the event with exponentially increasing time intervals. Here is the list of retryable error responses:

  • 401 - Unauthorized
  • 404 - Not Found
  • 429 - Too Many Requests
  • 502 - Bad Gateway
  • 503 - Service Unavailable
  • 504 - Gateway Timeout

Although the Connector can subscribe for any eventTypes, subscribing for MESSAGES or sometime just CC_MESSAGES is usually sufficient to handle asynchronous messaging use cases. For efficient communication and better performance, make sure the Connector is subscribing only to the eventTypes that are needed.

Sending Message

Now that you have successfully setup the Messaging Connector, you are ready to start building the conversation flow between your Provider and Avaya Experience Platform™ through your Connector.

When your connector receives a message, sent by the End User, from your Provider, it should send the message to Avaya Experience Platform™ by using the Send Message API.

The channelProviderId that was generated when we added the Messaging Element and the businessAccountName which is the "Integration Id" generated when we created an Integration are two key parameters that will ensure that correct business rules are applied to the engagement within Avaya Experience Platform™ when this API is called. Use the channelId as Messaging for Custom Messaging Integration. To make sure all messages of a conversation thread are also considered part of a conversation within Avaya Experience Platform™, pass the unique conversation identifier of your provider as providerDialogId in this API.

Avaya Experience Platform™ internally creates a new engagement if it could not find an active engagement for the providerDialogId sent as part of the message. The workflow is triggered for the new engagement which, based on its design, would direct the conversation to automated responses or route to an agent. Subsequent messages sent with the same providerDialogId will utilize the same engagement until the engagement is closed by automated apps or agent or by the system. If a message is sent after the engagement is closed, a new engagement will be again created for Avaya Experience Platform™. Avaya Experience Platform™ Agents can view all the messages exchanged for a conversation that might have spanned across multiple engagements.

Sending Typing Indicator

In addition to sending messages, the Connector can indicate Avaya Experience Platform™ that the End User has started typing by using Digital Custom Messaging API. On receiving the request, Avaya Experience Platform™ shows the typing indicator to the recipient participants for 6 seconds.

Typing Indicator events are considered as low priority events and hence sent using the best effort, in order to maximize the network usage.

Receiving Events

As the Connector had already subscribed for engagement events using its channelProviderId, any events that now occur on the engagement will be notified to the Connector using the registered callbackUrl, if the events match the subscribed eventTypes. To send auto response messages or messages from agents to the End User, the Connector must at least subscribe for CC_MESSAGES event type and forward the message events, it receives, to the Messaging Provider.

Rich Media and Attachments

The Send Message API and the Message Event support exchange of messages with rich media and attachments.

List of rich media types supported for messages received from contact center:

  • Image
  • File
  • Action buttons
  • Postback
  • Link
  • Location Request
  • Reply buttons
  • Location
  • Carousel

Checkout the examples here

List of rich media types supported for messages sent by customer:

  • Image
  • File
  • Postback (when customer clicks on a postback button sent by contact center)
  • Reply (when customer clicks on a reply button sent by contact center)
  • Location (when customer clicks on a location request button sent by contact center)

Checkout the examples for Send Message API

The Media Store Signed URI APIs provide an easy mechanism to upload and download attachments part of the messages.

Sending Messages with Attachments

To send a message from customer that has an image or a file attached, the attachment first needs to be uploaded to Avaya Experience Platform™. This is a three step process:

  1. Call the Generate Upload URI API and pass the details about the attachment. Avaya Experience Platform™ will generate a Signed URL to upload this attachment and send it back as uploadSignedUri along with mediaId in the response.

  2. Use the Signed URL from the uploadSignedUri field (without altering the URL) for uploading the attachment file. This URL unlike other APIs, does not require any Authorization headers. The Signed URL to upload attachments is valid only for 1 hour.

  3. Once the attachment is successfully uploaded, pass the mediaId (received in the first step) as attachmentId in the attachments array of the Send Message API.

For asynchronous messaging, currently only a single image or file attachment is allowed in a message.

Receiving Messages with Attachments

When an agent or automated apps sends a message with image or file attachment, the Message event that will be sent in the callback will contain a Signed Download URL in the url field inside attachments. This URL can be accessed without any Authorization headers to download the attachment. The Signed URL to download attachments is valid only for 30 days.

Your agents might need to use the same media files in messages multiple times. For example, images in a carousel, images in reply buttons or a common file document that can be shared with any user. It is recommended to avoid uploading such media files onto Avaya Experience Platform™. Instead, use your Content Delivery Network (CDN) or file repository where you might be already hosting such media files.

Events

Admin Callback: Integration Events

When your Account Admin will creates, updates or deletes an Integration under your Custom Messaging Provider Element which has a "Callback URL" , a request with POST method will sent to the "Callback URL". Here is an example of the body sent in the callback request when the Account Admin creates an Integration:

{
 "eventType": "INTEGRATION_CREATED",
 "integrationId": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "providerId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "integrationName": "My Support Integration",
 "integrationType": "custom-messaging-integrations",
 "accountId": "ABCDEF"
}

Example of the callback request when the Account Admin updates an Integration:

{
 "eventType": "INTEGRATION_UPDATED",
 "integrationId": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "providerId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "integrationName": "My New Support Integration",
 "integrationType": "custom-messaging-integrations",
 "accountId": "ABCDEF"
}

Example of the callback request when the Account Admin deletes an Integration:

{
 "eventType": "INTEGRATION_DELETED",
 "integrationId": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "providerId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "integrationName": "My New Support Integration",
 "integrationType": "custom-messaging-integrations",
 "accountId": "ABCDEF"
}

Engagement Callback: Message Events

Let us look at few examples of different types of messages that the Connector might receive as part of the callback request. Note that if your Connector has used ALL, MESSAGES or CUSTOMER_MESSAGES as eventTypes while subscribing to Digital Notifications, callback URL will be invoked for customer messages that were sent into Avaya Experience Platform™ by your Connector. To receive messages sent only by the Contact Center, subscribe using CC_MESSAGES as eventTypes.

Agent sends a plain text message

{
 "eventType": "MESSAGES",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "messageId": "f314569c-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "businessAccountName": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "channelId": "Messaging",
 "senderParticipantId": "277cacfe-710c-11eb-9439-0242ac130002",
 "senderParticipantName": "Jane Doe",
 "senderParticipantType": "AGENT",
 "body": {
   "elementType": "text",
   "elementText": {
     "text": "Good Morning. How can I help you?",
     "textFormat": "PLAINTEXT"
   },	
 },
 "headers": {
   "sourceType": "custom:my-provider",
   "sourceAddress": "support-page"
 },
 "messageIndex": 6,
 "recipientParticipants": [
   {
     "participantId": "[email protected]",
     "connectionId": "1349bcb1-fbf4-457c-af26-376da7bedc3c",
     "displayName": "John Doe",
     "participantType": "CUSTOMER",
     "providerParticipantId": "[email protected]",
     "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018 "
   }
 ],
 "parentMessageId": "6b5e9a72-710c-11eb-9439-0242ac130002",
 "providerDialogId": "616imlgwg266hjs670nl",
 "receivedAt": "2018-11-13T20:25:39.534Z",
 "lastUpdatedAt": "2018-11-13T20:25:39.734Z"
}

Agent sends a file to customer

{
 "eventType": "MESSAGES",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "messageId": "f314569c-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "status": "DELIVERED",
 "businessAccountName": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "channelId": "Messaging",
 "providerDialogId": "616imlgwg266hjs670nl",
 "senderParticipantId": "277cacfe-710c-11eb-9439-0242ac130002",
 "senderParticipantName": "Jane Doe",
 "senderParticipantType": "AGENT",
 "body": {
   "elementType": "file",
   "elementText": {
     "text": "This file contains car's brochure",
     "textFormat": "PLAINTEXT"
   }
 },
 "headers": {
   "sourceAddress": "My support page",
   "sourceType": "custom:my-provider"
 },
 "attachments": [
   {
     "attachmentId": "0ffa058c-77c7-4dbc-9fce-b0ee9e5ccd67",
     "name": "my-file.txt",
     "contentType": "text/plain",
     "url": "https://us.cc.avayacloud.com/api/media-store/v1beta/media/b03976ea-7e8b-11ea-bc55-0242ac130003?ttl=1672839427321&signature=8ac27e8f48f997d1a889b4b6111c3ad9fb92974a7efa4913dca92ffa43ac709f",
     "size": 2383
   }
 ],
 "messageIndex": 6,
 "recipientParticipants": [
   {
     "participantId": "6c66cfbfa5b8c841297103d4",
     "connectionId": "1349bcb1-fbf4-457c-af26-376da7bedc3c",
     "displayName": "John Doe",
     "participantType": "CUSTOMER",
     "providerParticipantId": "ad27a746b4c621a292c43f81",
     "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018"
   }
 ],
 "receivedAt": "2018-11-13T20:25:39.536Z",
 "lastUpdatedAt": "2018-11-13T20:25:39.734Z"
}

Agent sends an image to customer

{
 "eventType": "MESSAGES",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "messageId": "f314569c-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "status": "DELIVERED",
 "businessAccountName": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "channelId": "Messaging",
 "providerDialogId": "616imlgwg266hjs670nl",
 "senderParticipantId": "277cacfe-710c-11eb-9439-0242ac130002",
 "senderParticipantName": "Jane Doe",
 "senderParticipantType": "AGENT",
 "body": {
   "elementType": "image",
   "elementText": {
     "text": "Here is a picture",
     "textFormat": "PLAINTEXT"
   }
 },
 "headers": {
   "sourceAddress": "My support page",
   "sourceType": "custom:my-provider"
 },
 "attachments": [
   {
     "attachmentId": "0ffa058c-77c7-4dbc-9fce-b0ee9e5ccd67",
     "name": "my-picture.png",
     "contentType": "image/png",
     "url": "https://us.cc.avayacloud.com/api/media-store/v1beta/media/b03976ea-7e8b-11ea-bc55-0242ac130003?ttl=1672839427321&signature=8ac27e8f48f997d1a889b4b6111c3ad9fb92974a7efa4913dca92ffa43ac709f",
     "size": 2383
   }
 ],
 "messageIndex": 8,
 "recipientParticipants": [
   {
     "participantId": "6c66cfbfa5b8c841297103d4",
     "connectionId": "1349bcb1-fbf4-457c-af26-376da7bedc3c",
     "displayName": "John Doe",
     "participantType": "CUSTOMER",
     "providerParticipantId": "ad27a746b4c621a292c43f81",
     "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018"
   }
 ],
 "receivedAt": "2018-11-13T20:25:39.536Z",
 "lastUpdatedAt": "2018-11-13T20:25:39.734Z"
}

Agent sends a message with a postback, link and location request buttons to customer

{
 "eventType": "MESSAGES",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "messageId": "f314569c-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "status": "DELIVERED",
 "businessAccountName": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "channelId": "Messaging",
 "providerDialogId": "616imlgwg266hjs670nl",
 "senderParticipantId": "277cacfe-710c-11eb-9439-0242ac130002",
 "senderParticipantName": "Jane Doe",
 "senderParticipantType": "AGENT",
 "body": {
   "elementType": "text",
   "elementText": {
     "text": "Choose an option",
     "textFormat": "PLAINTEXT",
     "richMediaPayload": {
       "actions": [
         {
           "type": "postback",
           "text": "Book Appointment",
           "payload": "BOOK_APPOINTMENT"
         },
         {
           "type": "link",
           "text": "Get more information",
           "uri": "https://example.com/documents/info"
         },
         {
           "type": "locationRequest",
           "text": "Send Your Location"
         }
       ]
     }
   }
 },
 "headers": {
   "sourceAddress": "My support page",
   "sourceType": "custom:my-provider"
 },
 "messageIndex": 6,
 "recipientParticipants": [
   {
     "participantId": "6c66cfbfa5b8c841297103d4",
     "connectionId": "1349bcb1-fbf4-457c-af26-376da7bedc3c",
     "displayName": "John Doe",
     "participantType": "CUSTOMER",
     "providerParticipantId": "ad27a746b4c621a292c43f81",
     "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018"
   }
 ],
 "receivedAt": "2018-11-13T20:25:39.536Z",
 "lastUpdatedAt": "2018-11-13T20:25:39.734Z"
}

Agent sends a message with reply buttons to customer

{
 "eventType": "MESSAGES",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "messageId": "f314569c-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "status": "DELIVERED",
 "businessAccountName": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "channelId": "Messaging",
 "providerDialogId": "616imlgwg266hjs670nl",
 "senderParticipantId": "277cacfe-710c-11eb-9439-0242ac130002",
 "senderParticipantName": "Jane Doe",
 "senderParticipantType": "AGENT",
 "body": {
   "elementType": "text",
   "elementText": {
     "text": "Choose an option",
     "textFormat": "PLAINTEXT"
   },
   "richMediaPayload": {
     "actions": [
       {
         "type": "reply",
         "text": "Upset",
         "payload": "UPSET",
         "iconUrl": "https://example.com/icons/upset.png"
       },
       {
         "type": "reply",
         "text": "Good",
         "payload": "GOOD",
         "iconUrl": "https://example.com/icons/good.png"
       },
       {
         "type": "reply",
         "text": "Perfect",
         "payload": "PERFECT",
         "iconUrl": "https://example.com/icons/perfect.png"
       }
     ]
   }
 },
 "headers": {
   "sourceAddress": "My support page",
   "sourceType": "custom:my-provider"
 },
 "messageIndex": 6,
 "recipientParticipants": [
   {
     "participantId": "6c66cfbfa5b8c841297103d4",
     "connectionId": "1349bcb1-fbf4-457c-af26-376da7bedc3c",
     "displayName": "John Doe",
     "participantType": "CUSTOMER",
     "providerParticipantId": "ad27a746b4c621a292c43f81",
     "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018"
   }
 ],
 "receivedAt": "2018-11-13T20:25:39.536Z",
 "lastUpdatedAt": "2018-11-13T20:25:39.734Z"
}

Agent sends a carousel to customer

{
 "eventType": "MESSAGES",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "messageId": "f314569c-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "status": "DELIVERED",
 "businessAccountName": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "channelId": "Messaging",
 "providerDialogId": "616imlgwg266hjs670nl",
 "senderParticipantId": "277cacfe-710c-11eb-9439-0242ac130002",
 "senderParticipantName": "Jane Doe",
 "senderParticipantType": "AGENT",
 "body": {
   "elementType": "text",
   "elementText": {
     "text": "Choose an option",
     "textFormat": "PLAINTEXT"
   },
   "richMediaPayload": {
     "items": [
       {
         "mediaUrl": "https://example.com/cars/images/carmodel1.png",
         "description": "This is hybrid car",
         "title": "CarModel1",
         "actions": [
           {
             "payload": "CAR_MODEL_1",
             "text": "Select",
             "type": "postback"
           },
           {
             "text": "More info",
             "type": "link",
             "uri": "https://example.com/cars/info-carmodel1"
           }
         ]
       },
       {
         "mediaUrl": "https://example.com/cars/images/carmodel2.png",
         "description": "This is hybrid car",
         "title": "CarModel2",
         "actions": [
           {
             "payload": "CAR_MODEL_2",
             "text": "Select",
             "type": "postback"
           },
           {
             "text": "More info",
             "type": "link",
             "uri": "https://example.com/cars/info-carmodel2"
           }
         ]
       }
     ]
   }
 },
 "headers": {
   "sourceAddress": "My support page",
   "sourceType": "custom:my-provider"
 },
 "messageIndex": 6,
 "recipientParticipants": [
   {
     "participantId": "6c66cfbfa5b8c841297103d4",
     "connectionId": "1349bcb1-fbf4-457c-af26-376da7bedc3c",
     "displayName": "John Doe",
     "participantType": "CUSTOMER",
     "providerParticipantId": "ad27a746b4c621a292c43f81",
     "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018"
   }
 ],
 "receivedAt": "2018-11-13T20:25:39.536Z",
 "lastUpdatedAt": "2018-11-13T20:25:39.734Z"
}

Agent sends a location to customer

{
 "eventType": "MESSAGES",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "messageId": "f314569c-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "status": "DELIVERED",
 "businessAccountName": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "channelId": "Messaging",
 "providerDialogId": "616imlgwg266hjs670nl",
 "senderParticipantId": "277cacfe-710c-11eb-9439-0242ac130002",
 "senderParticipantName": "Jane Doe",
 "senderParticipantType": "AGENT",
 "body": {
   "elementType": "location",
   "elementText": {
     "text": "You can visit this showroom near to you",
     "textFormat": "PLAINTEXT"
   },
   "richMediaPayload": {
     "coordinates": {
       "lat": -18.516634,
       "long": 73.928104
     },
     "location": {
       "address": "Nth Floor, UVW Park, XYZ Street, Some Country, PIN CODE - 123456",
       "name": "Showroom Address"
     }
   }
 },
 "headers": {
   "sourceAddress": "My support page",
   "sourceType": "custom:my-provider"
 },
 "messageIndex": 6,
 "recipientParticipants": [
   {
     "participantId": "6c66cfbfa5b8c841297103d4",
     "connectionId": "1349bcb1-fbf4-457c-af26-376da7bedc3c",
     "displayName": "John Doe",
     "participantType": "CUSTOMER",
     "providerParticipantId": "ad27a746b4c621a292c43f81",
     "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018"
   }
 ],
 "receivedAt": "2018-11-13T20:25:39.536Z",
 "lastUpdatedAt": "2018-11-13T20:25:39.734Z"
}

Customer sends a plain text message

{
 "eventType": "MESSAGES",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "messageId": "f314569c-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "status": "DELIVERED",
 "businessAccountName": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "channelId": "Messaging",
 "providerDialogId": "616imlgwg266hjs670nl",
 "providerSenderId": "6c66cfbfa5b8c841297103d4",
 "providerMessageId": "64c8a96f6461998368455ec1",
 "senderParticipantId": "6c66cfbfa5b8c841297103d4",
 "senderParticipantName": "John Doe",
 "senderParticipantType": "CUSTOMER",
 "body": {
   "elementType": "location",
   "elementText": {
     "text": "I need help to proceed further on this",
     "textFormat": "PLAINTEXT"
   }
 },
 "headers": {
   "sourceAddress": "My support page",
   "sourceType": "custom:my-provider"
 },
 "messageIndex": 6,
 "recipientParticipants": [
   {
     "participantId": "6c66cfbfa5b8c841297103d4",
     "connectionId": "1349bcb1-fbf4-457c-af26-376da7bedc3c",
     "displayName": "John Doe",
     "participantType": "CUSTOMER",
     "providerParticipantId": "ad27a746b4c621a292c43f81",
     "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018"
   }
 ],
 "receivedAt": "2018-11-13T20:25:39.536Z",
 "lastUpdatedAt": "2018-11-13T20:25:39.734Z"
}

Customer sends a file

{
 "eventType": "MESSAGES",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "messageId": "f314569c-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "status": "DELIVERED",
 "businessAccountName": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "channelId": "Messaging",
 "providerDialogId": "616imlgwg266hjs670nl",
 "providerSenderId": "6c66cfbfa5b8c841297103d4",
 "providerMessageId": "64c8a96f6461998368455ec1",
 "senderParticipantId": "6c66cfbfa5b8c841297103d4",
 "senderParticipantName": "John Doe",
 "senderParticipantType": "CUSTOMER",
 "body": {
   "elementType": "file",
   "elementText": {
     "text": "This file contains the details",
     "textFormat": "PLAINTEXT"
   }
 },
 "headers": {
   "sourceAddress": "My support page",
   "sourceType": "custom:my-provider"
 },
 "attachments": [
   {
     "attachmentId": "0ffa058c-77c7-4dbc-9fce-b0ee9e5ccd67",
     "name": "my-file.txt",
     "contentType": "text/plain",
     "url": "https://us.cc.avayacloud.com/api/media-store/v1beta/media/b03976ea-7e8b-11ea-bc55-0242ac130003?ttl=1672839427321&signature=8ac27e8f48f997d1a889b4b6111c3ad9fb92974a7efa4913dca92ffa43ac709f",
     "size": 2383
   }
 ],
 "messageIndex": 6,
 "recipientParticipants": [
   {
     "participantId": "6c66cfbfa5b8c841297103d4",
     "connectionId": "1349bcb1-fbf4-457c-af26-376da7bedc3c",
     "displayName": "John Doe",
     "participantType": "CUSTOMER",
     "providerParticipantId": "ad27a746b4c621a292c43f81",
     "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018"
   }
 ],
 "receivedAt": "2018-11-13T20:25:39.536Z",
 "lastUpdatedAt": "2018-11-13T20:25:39.734Z"
}

Customer sends an image

{
 "eventType": "MESSAGES",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "messageId": "f314569c-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "status": "DELIVERED",
 "businessAccountName": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "channelId": "Messaging",
 "providerDialogId": "616imlgwg266hjs670nl",
 "providerSenderId": "6c66cfbfa5b8c841297103d4",
 "providerMessageId": "64c8a96f6461998368455ec1",
 "senderParticipantId": "6c66cfbfa5b8c841297103d4",
 "senderParticipantName": "John Doe",
 "senderParticipantType": "CUSTOMER",
 "body": {
   "elementType": "image",
   "elementText": {
     "text": "Here is the image",
     "textFormat": "PLAINTEXT"
   }
 },
 "headers": {
   "sourceAddress": "My support page",
   "sourceType": "custom:my-provider"
 },
 "attachments": [
   {
     "attachmentId": "0ffa058c-77c7-4dbc-9fce-b0ee9e5ccd67",
     "name": "my-car-photo.png",
     "contentType": "image/png",
     "url": "https://us.cc.avayacloud.com/api/media-store/v1beta/media/b03976ea-7e8b-11ea-bc55-0242ac130003?ttl=1672839427321&signature=8ac27e8f48f997d1a889b4b6111c3ad9fb92974a7efa4913dca92ffa43ac709f",
     "size": 2383
   }
 ],
 "messageIndex": 6,
 "recipientParticipants": [
   {
     "participantId": "6c66cfbfa5b8c841297103d4",
     "connectionId": "1349bcb1-fbf4-457c-af26-376da7bedc3c",
     "displayName": "John Doe",
     "participantType": "CUSTOMER",
     "providerParticipantId": "ad27a746b4c621a292c43f81",
     "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018"
   }
 ],
 "receivedAt": "2018-11-13T20:25:39.536Z"
}

Customer sends responds by clicking on a postback button

{
 "eventType": "MESSAGES",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "messageId": "f314569c-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "status": "DELIVERED",
 "businessAccountName": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "channelId": "Messaging",
 "providerDialogId": "616imlgwg266hjs670nl",
 "providerSenderId": "6c66cfbfa5b8c841297103d4",
 "providerMessageId": "64c8a96f6461998368455ec1",
 "senderParticipantId": "6c66cfbfa5b8c841297103d4",
 "senderParticipantName": "John Doe",
 "senderParticipantType": "CUSTOMER",
 "body": {
   "elementType": "postback",
   "elementText": {
     "text": "",
     "textFormat": "PLAINTEXT"
   },
   "richMediaPayload": {
     "selectedAction": {
       "type": "postback",
       "text": "Book Appointment",
       "payload": "BOOK_APPOINTMENT"
     }
   }
 },
 "headers": {
   "sourceAddress": "My support page",
   "sourceType": "custom:my-provider"
 },
 "messageIndex": 6,
 "recipientParticipants": [
   {
     "participantId": "6c66cfbfa5b8c841297103d4",
     "connectionId": "1349bcb1-fbf4-457c-af26-376da7bedc3c",
     "displayName": "John Doe",
     "participantType": "CUSTOMER",
     "providerParticipantId": "ad27a746b4c621a292c43f81",
     "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018"
   }
 ],
 "receivedAt": "2018-11-13T20:25:39.536Z",
 "lastUpdatedAt": "2018-11-13T20:25:39.734Z"
}

Customer sends responds by clicking on a reply button

{
 "eventType": "MESSAGES",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "messageId": "f314569c-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "status": "DELIVERED",
 "businessAccountName": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "channelId": "Messaging",
 "providerDialogId": "616imlgwg266hjs670nl",
 "providerSenderId": "6c66cfbfa5b8c841297103d4",
 "providerMessageId": "64c8a96f6461998368455ec1",
 "senderParticipantId": "6c66cfbfa5b8c841297103d4",
 "senderParticipantName": "John Doe",
 "senderParticipantType": "CUSTOMER",
 "body": {
   "elementType": "reply",
   "elementText": {
     "text": "",
     "textFormat": "PLAINTEXT"
   },
   "richMediaPayload": {
     "selectedAction": {
       "type": "reply",
       "text": "Good",
       "payload": "GOOD",
       "iconUrl": "https://example.com/icons/good.png"
     }
   }
 },
 "headers": {
   "sourceAddress": "My support page",
   "sourceType": "custom:my-provider"
 },
 "messageIndex": 6,
 "recipientParticipants": [
   {
     "participantId": "6c66cfbfa5b8c841297103d4",
     "connectionId": "1349bcb1-fbf4-457c-af26-376da7bedc3c",
     "displayName": "John Doe",
     "participantType": "CUSTOMER",
     "providerParticipantId": "ad27a746b4c621a292c43f81",
     "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018"
   }
 ],
 "receivedAt": "2018-11-13T20:25:39.536Z",
 "lastUpdatedAt": "2018-11-13T20:25:39.734Z"
}

Customer shares location

{
 "eventType": "MESSAGES",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "messageId": "f314569c-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "status": "DELIVERED",
 "businessAccountName": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018",
 "channelId": "Messaging",
 "providerDialogId": "616imlgwg266hjs670nl",
 "providerSenderId": "6c66cfbfa5b8c841297103d4",
 "providerMessageId": "64c8a96f6461998368455ec1",
 "senderParticipantId": "6c66cfbfa5b8c841297103d4",
 "senderParticipantName": "John Doe",
 "senderParticipantType": "CUSTOMER",
 "body": {
   "elementType": "location",
   "elementText": {
     "text": "",
     "textFormat": "PLAINTEXT"
   },
   "richMediaPayload": {
     "coordinates": {
       "lat": -18.516634,
       "long": 73.928104
     },
     "location": {
       "address": "Nth Floor, UVW Park, XYZ Street, Some Country, PIN CODE - 123456",
       "name": "Office Address"
     }
   }
 },
 "headers": {
   "sourceAddress": "My support page",
   "sourceType": "custom:my-provider"
 },
 "messageIndex": 6,
 "recipientParticipants": [
   {
     "participantId": "6c66cfbfa5b8c841297103d4",
     "connectionId": "1349bcb1-fbf4-457c-af26-376da7bedc3c",
     "displayName": "John Doe",
     "participantType": "CUSTOMER",
     "providerParticipantId": "ad27a746b4c621a292c43f81",
     "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018"
   }
 ],
 "receivedAt": "2018-11-13T20:25:39.536Z",
 "lastUpdatedAt": "2018-11-13T20:25:39.734Z"
}

Engagement Callback: Other Engagement Events

Apart from MESSAGE events, there are other events like ENGAGEMENT_CREATED, PARTICIPANT_ADDED, PARTICIPANT_DISCONNECTED, TYPING and ENGAGEMENT_ERROR that can occur on an engagement and your connector can listen for. Here are examples of each of these event types.

Engagement Created

{
 "eventType": "ENGAGEMENT_CREATED",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "conversation": "sell car",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018 ",
 "businessAccountName": "dad95e94-4592-4922-92f4-dbfb2663c009",
 "initiatorParticipantId": "[email protected]",
 "customerIdentifiers": {
   "emailAddresses": [
   	"[email protected]"
   ],
   "phoneNumbers": [
   	"+91 20 4101 8003"
   ]
 },
 "engagementParameters": {
   "model": "512GTB",
   "interestedModel": "488GTB"
 },
 "providerDialogId": "616imlgwg266hjs670nl",
 "sourceType": "Facebook",
 "sourceAddress": "https://www.facebook.com/Ixcc-112670754648669"
}

Participant Added

{
 "eventType": "PARTICIPANT_ADDED",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "channelId": "Messaging",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018 ",
 "connectionId": "f3c8400d-c44f-4451-8316-e75c4efb8zz9",
 "participantId": "e3c8400d-c44f-4451-8316-e75c4efb8cc7",
 "displayName": "Andy Morgan",
 "participantType": "AGENT",
 "providerDialogId": "616imlgwg266hjs670nl"
}

Participant Disconnected

{
 "eventType": "PARTICIPANT_DISCONNECTED",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "accountId": "ABCDEF",
 "channelId": "Messaging",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018 ",
 "connectionId": "f3c8400d-c44f-4451-8316-e75c4efb8zz9",
 "participantId": "e3c8400d-c44f-4451-8316-e75c4efb8cc7",
 "displayName": "Andy Morgan",
 "participantType": "AGENT",
 "providerDialogId": "616imlgwg266hjs670nl",
}

Typing Indicator

{
  "eventType": "TYPING",
  "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
  "eventDate": "2018-11-13T20:25:39.734Z",
  "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
  "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
  "accountId": "ABCDEF",
  "providerDialogId": "616imlgwg266hjs670nl",
  "channelProviderId": "09a9cba2-f8bb-4b7f-8405-48f82290f30e",
  "senderParticipantId": "277cacfe-710c-11eb-9439-0242ac130002",
  "senderParticipantType": "AGENT",
  "senderParticipantDisplayName": "Jane Doe",
  "channelId": "Messaging",
  "businessAccountName": "e94e278d-72e7-48cc-80fc-dba9f8dd1c36",
  "sourceType": "custom-messaging:my-provider",
  "sourceAddress": "https://my-provider.com/page-id",
  "externalRecipientParticipants": [
    {
      "participantId": "[email protected]",
      "providerParticipantId": "ad27a746b4c621a292c43f81"
    }
  ]
}

Engagement Error

{
 "eventType": "ENGAGEMENT_ERROR",
 "type": "ENGAGEMENT_CREATION_FAILED",
 "title": "Error occurred while creating an engagement",
 "detail": "Unable to create an engagement",
 "engagementId": "8d7cf5b8-70ad-11eb-9439-0242ac130002",
 "dialogId": "fc741b00-710b-11eb-9439-0242ac130002",
 "providerDialogId": "616imlgwg266hjs670nl",
 "channelProviderId": "334b31f7-ebad-4363-b128-0bbbfd4b6018 ",
 "accountId": "ABCDEF",
 "channelId": "Messaging",
 "correlationId": "zc38400d-c44f-4451-8316-e75c4efbt779",
 "eventDate": "2018-11-13T20:25:39.734Z"
}

Updated about 2 months ago