Custom channel adapter

Custom bridge for messages between Conversations and third-party systems

A channel adapter bridges Medallia Conversations and third-party systems, managing communication, session maintenance, and message parsing.

Custom message adapter is a bridge between Conversations and the channel provider/messaging service

To implement a channel adapter:

  • Create your custom channel adapter to bridge the communications between the systems.

  • In Medallia Experience Cloud create a Custom channel to define the behavior of the channel, and set up the connection between the adapter and Medallia Conversations.

Typical adapter call-flow

The adapter makes and receives REST API calls with Medallia Conversations to pass messages and manage the session, and it relays the information to the messaging service that interacts with the user. A typical API call-flow looks like this:

Call flow between components. Adapter starts conversation. For each new message Conversations starts a 'typing' indicator, determines message to send, stops 'typing' indicator, and sends outbound message. Adapter delivers message to customer via the provider, and sends the response to Conversations as an inbound message. When finished, Conversations sends an end of conversation message to the adapter.

Authentication

The adapter must implement authorization for inbound and outbound communications with Medallia Experience Cloud. For details, see Adapter authentication.

Debugging call-flows

Medallia Conversations provides diagnostic reports that detail the information received and sent from each custom channel. Review the report to reveal the detailed information sent and received by the channel.

Start a conversation

Trigger conversations in one of two ways.

From the adapter — The adapter starts a conversation by sending a signal to Medallia Conversations that includes the channel ID and conversation ID. It can also provide additional details, such as an agent identifier or customer segmentation data. This method is ideal for real-time chat systems like web-based live-chat surveys or point-of-sale terminal prompts, where minimal transactional information is available at the conversation's outset. Furthermore, more data can be added to the Conversation record later through a data append process. For more information, see Starting a conversation via API.

From imported data — Conversations can also be initiated using transactional data published to the Medallia Experience Cloud via an Import API. This data is evaluated to decide if a conversation should be started, based on predefined rules. When the criteria are met, a conversation is initiated, and a message is sent to the customer.

Typing indicator

Medallia Conversations can 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, and later sends typing-off followed by the outbound message. For details, see Typing signal.

Sending outbound messages

Medallia Conversations sends 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. For details, see Outbound message.

Provide delivery-status receipts

The adapter can provide delivery status receipts through a separate call using the globally-unique identifier of the sent message. If the adapter is unable to provide delivery status information, the Conversations channel can be configured to consider all outbound messages that receive an HTTP 200 (OK) status code as successfully sent. Providing delivery status updates is recommended, as it enables the use of Medallia Health Check to assess the program's health. For details, see Delivery-status receipts.

Forward inbound messages

The adapter should forward inbound messages (those sent in reply by the customer) to Medallia Conversations, which then processes the request and responds appropriately. Further follow-up messages defined in the Conversation's configuration are triggered as separate outbound message requests. For details, see Inbound message.

End of conversation signal

Medallia Conversations can provide notification at the end of a conversation, which can be used to implement a "handover" between Medallia Conversations and other chatbots. For details, see End of conversation.