Request URL

{conversations-api-gateway-host}/apis/v0/channels/{channel-guid}/messages

Request headers

accept: text/plain 
authorization: Bearer 12345
content-type: application/json

For information about the authorization header, see Adapter authentication.

Request payload

The inbound payload has a message element that includes both the trigger keyword that initiates the start of the conversation, and a message ID generated by the adapter/channel service to track the messages for the respondent. Additionally, the trigger_params element contains information about the respondent to be recorded in the Medallia Experience Cloud database.

{
	"object":"page",
	"entry": [{
		"id": "<PAGE_ID>",
		"time": "<UNIX_TIMESTAMP>",
		"messaging": [{
			"sender": { "id": "<CUSTOMER_ID>" },
			"recipient": { "id": "<PAGE_ID>" },
			"message": {
				"mid": "<MESSAGE_ID>",
				"text": "<KEYWORD>",
			},
			"trigger_params": {
				"override_session": false,
				"consumer": {
					"name": "Casey Harley",
					"email": "casey_harley@example.com",
					"first_name": "Casey", 
					"last_name": "Harley"
				},
				"custom": {
					"unitID" : "<UNIT_ID>",
					"<PARAMETER_1_NAME>": "<PARAMETER_1_VALUE>",
					"<PARAMETER_2_NAME>": "<PARAMETER_2_VALUE>"
				}
			}
		}]
	}]
}

Request parameters

Response

Set the Keyword that identifies the conversation

When Medallia Conversations detects a predefined keyword as the message text, it automatically initiates the corresponding conversation with the respondent. For a custom adapter, the initial dialog is sent to the adapter, which then forwards it to the respondent.

Briefly, to define a keyword:

1. In Medallia Conversations, edit the existing Conversation settings.

2. Add the keyword to the Keywords option.

   Press Enter after typing the keyword text to add it to the list of keywords.

3. Click Save to save the change.

Now the custom adapter can use the keyword to trigger the conversation with the respondent.

Trigger parameters

Trigger parameters pass respondent data from the adapter/channel service to E-Fields in the Medallia Experience Cloud database record. This data this includes information about the respondent or event, to be recorded in the feedback record. There are two optional categories of data parameters:

• consumer parameters contain information about the respondent. These four consumer parameters, and all are optional.

  • name
  • email — when included as a consumer parameter, this option must be formatted as an email address or Medallia Conversations flags it as an error
  • first_name
  • last_name

• custom parameters contain any information to record with the response.

  • unitId — a Unit ID is necessary for feedback requests, such as surveys, as it specifies the business unit related to the feedback.
    Tip: If all surveys on the Conversation apply to the same Unit ID, consider setting that ID as a default value in the Conversation settings instead of passing it in the trigger payload.

"trigger_params": {
	"override_session": true,
	"consumer": {
		"name": "Casey Harley",
		"email": "casey_harley@example.com",
		"first_name": "Casey", 
		"last_name": "Harley"
	},
	"custom": {
		"unitID" : "<UNIT_ID>",
		"<PARAMETER_1_NAME>": "<PARAMETER_1_VALUE>",
		"<PARAMETER_2_NAME>": "<PARAMETER_2_VALUE>"
	}
}

To access the entities in Medallia Conversations, use these identifiers in the Template Value for the Parameter definition.

{{paramsJSON.EVENT_VALUE.consumer.name}}
{{paramsJSON.EVENT_VALUE.consumer.email}}
{{paramsJSON.EVENT_VALUE.custom.unit_id}}

In Medallia Conversations, define the parameters in the Conversation Settings editor for the Conversation. For each parameter, choose the Field in the record in which to store the parameter value. And either

• assign a default value to the field, or

• in the Template Value, enter the JSON parameter that identifies the parameter passed to the channel in the API call.