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

POST
/conversation-messages-transform-outgoing-whatsapp

channelSend with
whatsappPOST /conversation-messages-transform-outgoing-whatsapp
instagramPOST /conversation-messages-transform-outgoing-instagram
messengerPOST /conversation-messages-transform-outgoing-messenger
webchatPOST /conversation-messages-transform-outgoing-webchat
smsPOST /conversation-messages-sms (see below)
playgroundPOST /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

NameTypeRequiredDescription
conversation_idintegerYesConversation to write in.
message_typestringYesSee the table below. note stores an internal note (destination: internal) that the contact never sees.
message_textstringFor text and noteText, or the caption of a media message.
s3_keystringFor mediaKey of the uploaded file (s3PathWithoutBucket from Upload a file).
file_namestringFor mediaOriginal file name.
file_typestringFor mediaMIME type, e.g. image/jpeg.
file_sizeintegerNoSize in bytes.
conversation_file_idstringNo_id of the conversation file.
locationobjectFor location{ "latitude", "longitude", "name", "address" }. Latitude and longitude are required.
replied_to_message_idstringNoWhatsApp: _id of a message of the conversation to quote (reply to). Ignored for notes.

Message types per channel

message_typeWhatsAppInstagramMessengerWebchat
textyesyesyesyes
noteyesyesyesno (webchat messages do not accept the internal destination)
image, video, audioyesyesyesyes
documentyesyesnoyes
fileyesnonono
locationyesyesnoyes
templateWhatsApp templatesnonono

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

POST
/conversation-messages-sms stores the message and, when destination is outgoing, sends it.

NameTypeRequiredDescription
conversation_idintegerYesSMS conversation.
organization_idintegerYesYour organization ID.
textstringYesMessage text (can be "" for an MMS with media only).
destinationstringYes, to sendoutgoing. The default is incoming, which stores the message without sending it.
message_typestringNotext (default), or image / video / audio / document with media.
media_urlsstring[]NoPublic URLs of the media to send as MMS.
media_url, mime_type, filenamestringNoMedia shown in the inbox.
from / tostringNoDefault 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

POST
/conversation-messages-playground writes in an AI assistant playground conversation (channel: playground, see Create a conversation). A message with destination: incoming acts as the contact and the conversation's AI assistant replies in the thread; read the reply with List messages.

NameTypeRequiredDescription
conversation_idintegerYesPlayground conversation.
organization_idintegerYesYour organization ID.
message_typestringYestext, or a media type with the file fields below.
destinationstringYesincoming to talk as the contact.
text or message_textstringYesMessage text (one is copied to the other).
contact_idintegerNoContact of the conversation.
rolestringNouser.
s3_key, s3_path, file_name, file_type, file_size, conversation_file_idNoAttachment fields (media_url is built from s3_key).

Unknown fields are rejected on the playground service.

Errors

StatusWhen
400 / 500conversation_id or message_type missing, the conversation does not exist, a media message without s3_key, or the channel rejected the message.
403 ForbiddenThe contact is blacklisted for the channel.

Report an issue with this documentation

Please log in to report issues with our documentation.