Send a message
Send a message to the contact of a conversation, or store an internal note. Use the send service of the conversation's channel.
Endpoint
channel | Send with |
|---|---|
whatsapp | POST /conversation-messages-transform-outgoing-whatsapp |
instagram | POST /conversation-messages-transform-outgoing-instagram |
messenger | POST /conversation-messages-transform-outgoing-messenger |
webchat | POST /conversation-messages-transform-outgoing-webchat |
sms | POST /conversation-messages-sms (see below) |
playground | POST /conversation-messages-playground (see below) |
WhatsApp, Instagram, Messenger and webchat
The organization, contact and channel identifiers are taken from the conversation; you only send the content. The sender is the API key's user.
Body
| Name | Type | Required | Description |
|---|---|---|---|
conversation_id | integer | Yes | Conversation to write in. |
message_type | string | Yes | See the table below. note stores an internal note (destination: internal) that the contact never sees. |
message_text | string | For text and note | Text, or the caption of a media message. |
s3_key | string | For media | Key of the uploaded file (s3PathWithoutBucket from Upload a file). |
file_name | string | For media | Original file name. |
file_type | string | For media | MIME type, e.g. image/jpeg. |
file_size | integer | No | Size in bytes. |
conversation_file_id | string | No | _id of the conversation file. |
location | object | For location | { "latitude", "longitude", "name", "address" }. Latitude and longitude are required. |
replied_to_message_id | string | No | WhatsApp: _id of a message of the conversation to quote (reply to). Ignored for notes. |
Message types per channel
message_type | Messenger | Webchat | ||
|---|---|---|---|---|
text | yes | yes | yes | yes |
note | yes | yes | yes | no (webchat messages do not accept the internal destination) |
image, video, audio | yes | yes | yes | yes |
document | yes | yes | no | yes |
file | yes | no | no | no |
location | yes | yes | no | yes |
template | WhatsApp templates | no | no | no |
Request
Image with caption (after uploading the file):
Internal note:
Location:
Response
The stored message:
json
Rules
- 24-hour window: WhatsApp, Instagram and Messenger only accept free-form messages within 24 hours of the contact's last message. Outside it, WhatsApp needs a template. Notes are always allowed.
- Do not disturb / blacklist: a contact blacklisted for WhatsApp returns
403 Forbidden; Instagram and Messenger respect the contact's do-not-disturb setting for the channel. - WhatsApp messages go out from the conversation's number (
whatsapp_channel_id).
SMS
| Name | Type | Required | Description |
|---|---|---|---|
conversation_id | integer | Yes | SMS conversation. |
organization_id | integer | Yes | Your organization ID. |
text | string | Yes | Message text (can be "" for an MMS with media only). |
destination | string | Yes, to send | outgoing. The default is incoming, which stores the message without sending it. |
message_type | string | No | text (default), or image / video / audio / document with media. |
media_urls | string[] | No | Public URLs of the media to send as MMS. |
media_url, mime_type, filename | string | No | Media shown in the inbox. |
from / to | string | No | Default to the conversation's our_phone_number and contact_phone. |
The response is the stored message with delivery_status: "queued", or "failed" with error_message when the provider rejected it. Phone numbers on the organization's SMS blacklist are rejected.
Playground
| Name | Type | Required | Description |
|---|---|---|---|
conversation_id | integer | Yes | Playground conversation. |
organization_id | integer | Yes | Your organization ID. |
message_type | string | Yes | text, or a media type with the file fields below. |
destination | string | Yes | incoming to talk as the contact. |
text or message_text | string | Yes | Message text (one is copied to the other). |
contact_id | integer | No | Contact of the conversation. |
role | string | No | user. |
s3_key, s3_path, file_name, file_type, file_size, conversation_file_id | No | Attachment fields (media_url is built from s3_key). |
Unknown fields are rejected on the playground service.
Errors
| Status | When |
|---|---|
400 / 500 | conversation_id or message_type missing, the conversation does not exist, a media message without s3_key, or the channel rejected the message. |
403 Forbidden | The contact is blacklisted for the channel. |
Report an issue with this documentation
Please log in to report issues with our documentation.