Delivery-status receipts

Sending delivery-status messages to Medallia Conversations.

Delivery-status receipts are POST requests sent by the adapter to report the status of message deliveries to the respondent.

Request URL

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

Where

conversations-api-gateway-host: the Medallia Experience Cloud hostname to access the Medallia Conversations API gateway.
channel-guid: the ID of the Custom Channel assigned in Medallia Conversations.

Request headers

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

For information about the authorization header, see Adapter authentication.

Request payload

The delivery status message is in the delivery element, which contains the message text and the ID(s) of the messages with that status.

{
    "object":"page",
    "entry": [{
		"id": "<PAGE_ID>",
		"time": <UNIX_TIMESTAMP>,
		"messaging": [{
			"sender": { "id": "<CUSTOMER_ID>" },
			"recipient": { "id": "<PAGE_ID>" },
			"delivery": {
				"mids": [ "<MESSAGE_ID>" ],
				"watermark" : <UNIX_TIMESTAMP> ,
				"status": "<STATUS>"
			},
			"error": {
				"code": <ERROR_CODE>,
				"name": <ERROR_NAME>,
				"message": <ERROR_MESSSAGE>
			}
		}]
	}]
}

Request parameters


object `string` required	Always "page".
entry `array` required	One or more sets of messages (an "entry") targeted to a single channel (a "page").
entry:id `string` or `integer` required	Page ID of the Medallia Conversations Channel — as defined in its Authentication settings — that identifies the unique adapter instance associated with the channel. This value must match the `recipient:id` for the inbound messages.
time `integer`	Unix epoch timestamp of the last event associated with the element. For example, when it was a multi-part message, this is the time of the last message-part.
messaging `array` required	One or more `message` objects.
sender: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.
recipient:id `string` or `integer` required	Page ID of the Medallia Conversations Channel — as defined in its Authentication settings — that identifies the unique adapter instance associated with the channel. This value must match the `recipient:id` for the inbound messages.
watermark `integer` deprecated	Unix epoch timestamp indicating all messages sent before this time have the associate status. Important: Note this old option is deprecated and no longer used by the system, but may optionally be included for compatibility with old implementations.
mids `array of strings` required	An array of message IDs all sent to the same recipient, and which have the same delivery status.
status `string`	Status of the message(s). One of: `failed` — requires an `error` parameter `sent` `delivered` `undelivered` — requires an `error` parameter
error `object`	Required when status is either `failed` or `undelivered`.
code `integer` required	Error code number that identifies the error condition on the host.
name `string` required	Name of the error, such as "Invalid protocol".
message`string`	Text message describing the error.

Example: curl request for successful delivery

curl --request POST \
  --url https://conversations.sc4.medallia.com/apis/v0/channels/channel-guid/messages \
  --header 'accept: text/plain' \
  --header 'authorization: Bearer 12345' \
  --header 'content-type: application/json'curl \
  --d '{
	"object":"page",
	"entry": [{
		"id": "page_id",
		"time": 1770163786,
		"messaging": [{
			"sender": { "id": "customer_id" },
			"recipient": { "id": "page_id" },
			"delivery": {
				"mids": ["msg_id_1", "msg_id_2"],
				"status": "delivered"
			}
		}]
	}]
}'

Example: curl request for failed delivery

curl --request POST \
  --url https://conversations.sc4.medallia.com/apis/v0/channels/channel-guid/messages \
  --header 'accept: text/plain' \
  --header 'authorization: Bearer 12345' \
  --header 'content-type: application/json'curl \
  --d '{
	"object":"page",
	"entry": [{
		"id": "page_id",
		"time": 1770163786,
		"messaging": [{
			"sender": { "id": "customer_id" },
			"recipient": { "id": "page_id" },
			"delivery": {
				"mids": ["msg_id_1", "msg_id_2"],
				"status": "failed"
			},
			"error": {
				"code": 207,
				"name": "Unavailable",
				"message": "Unable to deliver the message(s)"
			}
		}]
	}]
}'

Response


Response	Description
200	The request was processed as expected.
401	Unauthorized. The reason is provided in a human-readable string.
403	Forbidden. `statusCode`: The HTTP status code. `error`: The error code. `message`: The error message.
500	Internal server error. `statusCode`: The HTTP status code. `error`: The error code. `message`: The error message.