Outbound message

Send a Medallia Conversations message to the respondent.

Outbound messages are POST requests from Medallia Conversations to the respondent. The payload contains the respondent ID and the message to deliver. Quick replies are optional and might be provided depending on the configuration of the conversation.

Outbound messages are to the respondent

Request URL

The API endpoint implemented by the Channel Adapter to accept messages from Medallia Conversations.

{customer-adapter-uri}/?access_token={access-token}

{customer-adapter-uri} is the Customer send message URL setting in the Medallia Conversations Custom Channel settings.
{access-token} is the API-Token setting in the Medallia Conversations Custom Channel settings. The token is free-form text, but Medallia recommends using a cryptographically-secure token such as a UUID or other random nonce value. For more information, see API-token.

Request headers

Content-Type: application/json

Additional custom headers can be defined in the Medallia Conversations Channel configuration.

Request payload

This is an example of a Yes or No question to present to the respondent. Each option includes an image to show with the question choice.

{
    "recipient": { "id":"<RECIPIENT_ID >" },
    "message": {
        "text":"<MESSAGE>",
        "quick_replies":[ {
            "content_type":"text",
            "title":"Yes", 
            "payload":"<POSTBACK_PAYLOAD>", 
            "image_url":"<OPTION_IMAGE_URI>" 
        },{ 
            "content_type":"text", 
            "title":"No", 
            "payload":"<POSTBACK_PAYLOAD>", 
            "image_url":"<OPTION_IMAGE_URI>" 
        }] 
    }, "notification_type": "REGULAR" 
}

Request parameters

Minimally the payload must have a recipient:id and the message:text to send.

The Medallia Conversations MAX_MESSAGE_LENGTH Channel setting determines how many characters to include in the message text. By default, the message is split into multiple messages when the text is more than 320 characters. The setting can be increased to a maximum of 1024 characters.


recipient:id `string` or `integer` required	Identifier unique to the respondent, such as phone number, email, or other channel-specific value. For phone numbers, the ID must be in E.164 format.
text `string`	Text message to present to the recipient. The maximum length of the message is 1024 characters, but by default is 320 characters. The length is configurable with the `MAX_MESSAGE_LENGTH` custom Channel configuration setting. For more information, see Channel settings.
quick_replies `object`	Optional array of objects containing the quick response options.
quick_replies:content_type `string` required	Always "`text`".
quick_replies:title `string`	Text of a response option to the quick reply question.
quick_replies:payload `string`	Unique identifier ( UUID) of the quick reply option. The adapter can send the user response as this payload, when the quick reply/option is chosen.
quick_replies:image_url `uri`	Optional URI to an image to display in the message. The adapter can send this as the user's response, when the quick reply option is chosen.
notification_type `string`	Always `"REGULAR"`.

Example: curl request with message, no quick replies

curl --request POST \
  --url {custom-adapter-uri}/?access_token={access-token}
  --header "Content-Type: application/json" \
  --d '{
  "recipient": { "id": "<RECIPIENT_ID>" },
  "message": { "text": "<MESSAGE>" },
  "notification_type": "REGULAR"
}'

Example: curl request with quick replies/options

curl --request POST \
  --url {custom-adapter-uri}/?access_token={access-token}
  --header "Content-Type: application/json" \
  --d '{ 
  "recipient": { "id": "<RECIPIENT_ID>" },
  "message": {
    "text": "<MESSAGE>",
    "quick_replies": [{
        "content_type": "text",
        "title": "Yes",
        "payload": "<OPTION_ID>",
        "image_url": "https://example.com/option_yes.png"
      },
      {
        "content_type": "text",
        "title": "No",
        "payload": "<OPTION_ID>",
        "image_url": "https://example.com/option_no.png"
      }
    ]
  },
  "notification_type": "REGULAR"
}'

Response

A successful response from the adapter includes the respondent and message IDs.

HTTP/1.1 200 
status: 200 
content-type: application/json; 
charset=utf-8 
content-length: 28 
{
    "recipient_id": "<RECIPIENT_ID>", 
    "message_id": "<MESSAGE_ID>" 
}

Responses


Response	Description
200	A successful response includes an array of the customer and message IDs. `recipient_id`: The identifier for the recipient, as sent in the original request. `message_id`: A unique identifier for the message, assigned by the channel adapter.
401	Unauthorized