Conversation messages

Messages of a conversation. Each channel has its own message service: read the conversation's channel and use the matching path. Customer-facing messages on Meta channels and webchat are sent through an "outgoing" service that builds the channel payload and then stores the message; SMS and playground messages are sent directly on their message service.

Endpoints

channelList / get / edit note / deleteSend
whatsappGET /conversation-messages-whatsappPOST /conversation-messages-transform-outgoing-whatsapp
instagramGET /conversation-messages-instagramPOST /conversation-messages-transform-outgoing-instagram
messengerGET /conversation-messages-messengerPOST /conversation-messages-transform-outgoing-messenger
webchatGET /conversation-messages-webchatPOST /conversation-messages-transform-outgoing-webchat
smsGET /conversation-messages-smsPOST /conversation-messages-sms
playgroundGET /conversation-messages-playgroundPOST /conversation-messages-playground
OperationPage
List messages of a conversationList messages
Get one messageGet a message
Send text, media, location or an internal noteSend a message
Send a WhatsApp templateSend a WhatsApp template
Edit an internal noteEdit a note
Delete a messageDelete a message

Attachments are uploaded first with Conversation files.

The message object

A WhatsApp message (other channels share the same core fields):

json

Fields

IDs: messages of WhatsApp, Instagram, Messenger, webchat and SMS have a string _id; playground messages have an integer id. The "Channels" column says where a field appears (blank = all channels).

FieldTypeChannelsDescription
_idstringall but playgroundRead-only. Message ID.
idintegerplaygroundRead-only. Message ID.
conversation_idintegerConversation of the message.
organization_idintegerOrganization.
contact_idinteger | nullContact of the conversation.
message_typestringtext, image, video, audio, document, file, sticker, location, contacts, template, note (internal note), reaction, system, error, unsupported, tool/automation events (internal_tool, api_tool, mcp_tool, skill_reading, automation_started, automation_completed, automation_failed), Instagram ig_post / ig_reel. SMS: text, image, video, audio, document, media, template, reaction, note.
message_textstring | nullMessage text or media caption.
textstringText copy used by SMS, webchat and playground (message_text mirrors it). On SMS, text is the field you send.
destinationstringincoming (from the contact), outgoing (to the contact), internal (note, WhatsApp/Instagram/Messenger/webchat) or system.
rolestring | nullplaygrounduser for messages you send as the contact.
message_idstringChannel message ID (for example the WhatsApp wamid).
whatsapp_statusstringwhatsappDelivery status reported by WhatsApp: sent, delivered, read, or failed.
messenger_statusstringmessengerDelivery status reported by Messenger, e.g. sent.
delivery_statusstring | nullsmsqueued, sent, delivered, failed or received.
statusstring | nullplaygroundMessage status.
readbooleanWhether the message was read in the inbox. Default false.
timestampstring | nullChannel timestamp of the message.
media_urlstringURL of the image, audio, video or document.
media_urlsstring[] | nullsmsMedia URLs of an MMS.
filenamestringOriginal file name of the attachment.
file_namestringwebchat, playgroundOriginal file name of the attachment.
mime_typestringMIME type of the attachment.
file_typestring | nullplaygroundMIME type of the attachment.
file_sizeintegerwebchat, playgroundAttachment size in bytes.
s3_key / s3_pathstring | nullplaygroundStorage key and s3:// path of the attachment.
conversation_file_idstringwebchat, playgroundConversation file of the attachment.
location_latitude / location_longitudestring | numberwhatsapp, instagramLocation messages: coordinates.
location_name / location_addressstringwhatsapp, instagramLocation messages: place name and address.
revokedboolean | nullwhatsappThe contact deleted the message in WhatsApp.
editedboolean | nullwhatsappThe message was edited (by the contact in WhatsApp, or an edited internal note).
message_text_originalstring | nullwhatsappText before the edit.
order_dataobject | nullwhatsappWhatsApp catalog order sent by the contact.
interactive_dataobject | nullwhatsappInteractive reply (list or button) sent by the contact.
interactive_typestring | nullwhatsappType of the interactive reply.
button_dataobject | nullwhatsappQuick-reply button pressed by the contact.
campaign_idinteger | nullwhatsapp, smsCampaign that sent the message.
is_bulkbooleansmsSent by a bulk SMS campaign.
is_echobooleanwhatsapp, instagram, smstrue on an outgoing message that was not sent from AchieveApex (the native app, Meta Business Suite, the WhatsApp Business app or a third-party tool) and was reported back by the provider.
is_historybooleanwhatsappMessage imported from the WhatsApp Business app history when the number was connected.
from / tostring | nullsmsSender and recipient phone numbers.
error_code / error_messagestring | nullsmsProvider error when the SMS failed.
errorobject | nullError details when sending or the AI reply failed.
contact_deletedboolean | nullsmsThe contact was deleted.
meta_contact_first_name / meta_contact_last_namestring | nullContact name at the time of the message.
meta_contact_avatar_urlstring | nullContact avatar.
meta_contact_phonestring | nullsmsContact phone.
meta_contact_channel_wa_user_idstring | nullwhatsappContact's WhatsApp Business-Scoped User ID, when Meta sent one.
user_idinteger | nullTeam member who sent the message.
meta_user_first_name / meta_user_last_namestring | nullSender name.
meta_user_avatar_urlstring | nullSender avatar.
meta_user_rolestring | nullSender platform role.
ai_assistant_idinteger | nullAI assistant that wrote the message.
ai_assistant_namestring | nullName of that assistant.
ai_modelobject | nullall but smsModel used for the AI reply.
ai_structured_dataobject | nullall but smsStructured output returned with the AI reply.
automation_id / automation_nameinteger / string | nullAutomation that sent the message.
automation_execution_idinteger | nullAutomation execution that sent it.
is_from_automationboolean | nullplaygroundSent by an automation.
follow_up_detailsobject | nullDetails of an AI follow-up message.
change_metadataobject | nullDetails of a system message that records a change (assignment, stage, ...).
tool_metadataobject | nullDetails of an AI tool call message.
created_atstring (date-time)Read-only. Creation time.
updated_atstring (date-time)Read-only. Last update time.
deleted_atstring (date-time) | nullRead-only. Set when the message is deleted.

Messages can carry extra channel data (for example Instagram story replies, WhatsApp ad referrals or quoted replies in replied_to_message). Treat unknown fields as optional.

Report an issue with this documentation

Please log in to report issues with our documentation.