Medallia Conversations connects with third-party communications systems by leveraging the Conversations APIs. In this guide, we’re going to review how to build an adapter that communicates with Medallia Conversations.
A channel adapter is an application that handles the communication between Medallia Conversations and the service that is responsible for messaging with the end user. Medallia Conversations determines which message to send, maintains the session, and parses the customer response. All communication between the adapter and Medallia Conversations is performed asynchronously.
Each adapter is configured as a custom channel in the Conversations configuration interface. The channel contains the connection details for the adapter, as well as various settings that determine the behavior of the channel. For more information on how to set up a new custom channel, please refer to the product documentation.
Use Cases
An adapter is responsible for handling the different use cases as part of the Medallia Conversations exchange. The following sequence diagram provides a high-level view of the various steps:
Starting Conversations
Conversations are triggered in one of two ways.
The adapter initiates a conversation by sending a signal to Conversations with the channel id and conversation id specified. The adapter may also pass additional information, such as an agent identifier or customer segmentation information. This approach is useful for real-time chat systems such as web-based live-chat surveys or point-of-sale terminal prompts, where low-latency and little transactional information is known at the start of a conversation. In addition to the data provided by the adapter, additional information may be appended to the Conversation record in the future through a data append process.
Alternatively, conversations are started by transactional data being published to Medallia Experience Cloud through an Import API. The transactional data is sampled to determine whether a Conversation is warranted (based on your configured ruleset). If so, then a Conversation is triggered and a message is sent to the customer.
Sending outbound messages
Medallia Conversations will send each message to the adapter in an API request. The adapter should process the request and respond appropriately. As part of the API response, the adapter should provide a globally-unique identifier of this message for future tracking and delivery status updates.
Providing delivery-status receipts
The adapter may provide delivery status receipts via a separate call using the sent message’s globally-unique identifier. If the adapter can’t provide delivery status information, the Conversations channel can be configured to treat all outbound messages that receive an HTTP 200 (OK) status code as sent. It is recommended to provide delivery status updates as this allows leveraging Medallia Health Check to review the health of the program.
Forwarding inbound messages
The adapter should forward inbound messages (i.e. those sent in reply by the customer) to Medallia Conversations. Medallia Conversations processes the request and responds appropriately. Further follow-up messages defined in the Conversations configuration are triggered as separate requests, as outlined in Sending outbound messages.
End of Conversation signal
Medallia Conversations can provide notifications at the end of a conversation, which can be used to implement a ‘handover’ between Conversations and other chatbots. The end-of-conversation notification is provided as a separate request. For an explanation of all the situations that can trigger an end-of-conversation notification, see our product documentation.
Typing indicator
Medallia Conversations can also send notifications to indicate typing, a useful way to show the user that their reply is being processed and a response formulated. Conversations first sends a typing on request, followed by typing off, and then the actual outbound message request.
API Endpoints
Due to Conversation’s high volume and low-latency requirements, the Conversations API leverages its own API gateway. All API requests need to be directed to the specific data center where your Conversations account is hosted. Retrieve the base URL from your administration interface's URL as shown below:
In this example, the Conversations account is hosted in Medallia's Seattle data center, and the base URL for all API requests is therefore https://conversations.sea1.medallia.com.
Each custom channel configuration is allocated a unique Channel ID, used for passing inbound messages back to Conversations. The channel ID is found in the channel settings:
Authentication
The Conversations API uses OAuth 2.0 with the client credentials grants for authentication.
The OAuth endpoint can be constructed by taking the base Conversations URL and adding /oauth/token. For the example above, the OAuth URL would be https://conversations.sea1.medallia.com/oauth/token.
Requirements for a Custom Adapter
The following are a collection of high-level requirements and considerations for implementation a custom adapter.
Rate limits
Medallia Conversations is designed to handle real time communication at scale and, as such, does not implement rate limiting in either direction. The adapter needs to be able to handle all requests in a timely manner. As a rule of thumb, the adapter should be able to handle at least 100 messages per second, but should be assessed for each implementation.
Timeouts
In order to process a large number of requests, the Conversations APIs operate in an asynchronous manner. Medallia Conversations expects a response to any HTTP request sent to the adapter within 10 seconds. Since the actual delivery of the message might take longer, the adapter should first respond to the request before attempting delivery. If there are any issues with the delivery of the message, the adapter should pass this information back to Conversations through a separate delivery status request.
Retries and error handling
Medallia Conversations will retry communications to the channel adapter a maximum of 5 times with a delay of 10 seconds between each attempt. It is imperative that the adapter responds with an appropriate status code before the timeout as the Conversations APIs might otherwise retry a successfully delivered message, resulting in two identical messages being sent to the customer.
The adapter should have a similar retry mechanism in case the Conversations APIs are not reachable at that moment.
Managing Conversations
When initiating a conversation, the channel adapter must specify the associated keyword or conversation identifier. This information is found in the administration interface for Medallia Conversations.
It is also possible to retrieve the list of conversations programmatically. The adapter can use the Conversations list API to dynamically integrate into third-party UIs, allowing an admin to select which conversation to trigger without having to reference the Conversations admin interface or to update the adapter code. A typical use case for this is to map a given skill or intent in a chat solution to a conversation.