Skip to main content

Messages

Refer to our message definition for more information.

List#

POST /messages.list

This is a paginated endpoint. Messages are sorted from oldest to latest.

Sample request

{
"conversation_id": "4242-4242-4242-424242",
"cursor": "next-page-uuid", // optional
"page_size": 2 // optional
}

Sample response

{
"data": [
{
"id": "{UUID}",
"content": {"text": "Hello World"},
// source message payload
"state": "{String}",
// delivery state of message, one of PENDING, FAILED, DELIVERED
"from_contact": true,
"sent_at": "{string}",
// ISO 8601 date string
"source": "{String}",
// one of the possible sources
"metadata": {
"sentFrom": "iPhone"
}
// metadata object of the message
}
],
"pagination_data": {
"previous_cursor": "",
"next_cursor": "",
"total": 1
}
}

Send#

POST /messages.send

Sends a message to a conversation and returns a payload. Whatever is put on the message field will be forwarded "as-is" to the source's message endpoint. Therefore, the payload will look differently for each source. Refer to each source's documentation to see learn how to send text, media, and many more message types.

Sample request

{
"conversation_id": "a688d36c-a85e-44af-bc02-4248c2c97622",
"message": {
// Source specific body
}
}

Sample response

{
"id": "{UUID}",
"content": "{\"text\":\"Hello\"}",
"state": "pending|failed|delivered",
"from_contact": true,
// See glossary
"sent_at": "{string}",
//'yyyy-MM-dd'T'HH:mm:ss.SSSZ' date in UTC form, to be localized by clients
"source": "{String}",
// one of the possible sources
"metadata": {
"sentFrom": "iPhone"
}
// metadata object of the message
}

Starting a conversation

The previous flow covers the use cases of most messaging sources. However, some sources such as SMS or Whatsapp also allow you to send messages to contacts that did not previously message you first. This means that you can create new conversations with them if you know their source recipient id.

Sample request

{
"source_recipient_id": "+491234567",
"channel_id": "<airy uuid>",
"message": {
// Source specific body
}
}

Sample response

{
"id": "{UUID}",
"content": "{\"text\":\"Hello world\"}", // Source specific body
"state": "pending|failed|delivered",
"from_contact": true,
"sent_at": "{string}",
"source": "{String}",
"metadata": {}
}

Send from Google's Business Messages source#

POST /messages.send

Sends a message to a conversation from Google's Business Messages source and returns a payload.

Note that when you send a message from this source, you must specify a representative, the individual or automation that composed the message. Google's Business Messages supports "BOT" and "HUMAN" as the representativeType. Find more information on Google's Business Messages guide.

Whatever is put on the message field will be forwarded "as-is" to the source's message endpoint.

Sending a text message

{
conversation_id: 'a688d36c-a85e-44af-bc02-4248c2c97622',
message: {
text: 'Hello!',
representative: {
representativeType: 'HUMAN',
},
},
}

Sample response

{
"id": '{UUID}',
"content": {
"text": 'Hello!',
"representative": {
"representativeType": 'HUMAN',
},
},
"delivery_state": 'pending|failed|delivered',
"from_contact": 'true|false',
// See glossary
"sent_at": '{string}',
//'yyyy-MM-dd'T'HH:mm:ss.SSSZ' date in UTC form, to be localized by clients
"source": 'google',
"metadata": {
"sentFrom": 'iPhone',
},
// metadata object of the message
}

Suggest replies#

POST /messages.suggest-replies

Suggest a set of replies for a given message ID. UI clients can then show these replies to agents to help them respond to user inquiries.

Sample request

{
"message_id": "uuid",
"suggestions": {
"suggestion-id-1": {
"content": {"text": "Great that it worked. Is there anything else you need?"},
},
"suggestion-id-2": {
"content": {"text": "Have a nice day!"},
},
},
}

Sample response

The updated message including the suggested replies.

{
"id": "{UUID}",
"content": {"text": "Hello World"},
"state": "{String}",
"from_contact": true,
"sent_at": "{string}",
"source": "{String}",
"metadata": {
"suggestions": {
"suggestion-id-1": {
"content": {"text": "Great that it worked. Is there anything else you need?"},
// source specific content field (same as message content)
},
"suggestion-id-2": {
"content": {"text": "Have a nice day!"},
},
},
},
// metadata object of the message including the reply suggestions
}
Last updated on