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
channel | List / get / edit note / delete | Send |
|---|---|---|
whatsapp | GET /conversation-messages-whatsapp | POST /conversation-messages-transform-outgoing-whatsapp |
instagram | GET /conversation-messages-instagram | POST /conversation-messages-transform-outgoing-instagram |
messenger | GET /conversation-messages-messenger | POST /conversation-messages-transform-outgoing-messenger |
webchat | GET /conversation-messages-webchat | POST /conversation-messages-transform-outgoing-webchat |
sms | GET /conversation-messages-sms | POST /conversation-messages-sms |
playground | GET /conversation-messages-playground | POST /conversation-messages-playground |
| Operation | Page |
|---|---|
| List messages of a conversation | List messages |
| Get one message | Get a message |
| Send text, media, location or an internal note | Send a message |
| Send a WhatsApp template | Send a WhatsApp template |
| Edit an internal note | Edit a note |
| Delete a message | Delete 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).
| Field | Type | Channels | Description |
|---|---|---|---|
_id | string | all but playground | Read-only. Message ID. |
id | integer | playground | Read-only. Message ID. |
conversation_id | integer | Conversation of the message. | |
organization_id | integer | Organization. | |
contact_id | integer | null | Contact of the conversation. | |
message_type | string | text, 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_text | string | null | Message text or media caption. | |
text | string | Text copy used by SMS, webchat and playground (message_text mirrors it). On SMS, text is the field you send. | |
destination | string | incoming (from the contact), outgoing (to the contact), internal (note, WhatsApp/Instagram/Messenger/webchat) or system. | |
role | string | null | playground | user for messages you send as the contact. |
message_id | string | Channel message ID (for example the WhatsApp wamid). | |
whatsapp_status | string | Delivery status reported by WhatsApp: sent, delivered, read, or failed. | |
messenger_status | string | messenger | Delivery status reported by Messenger, e.g. sent. |
delivery_status | string | null | sms | queued, sent, delivered, failed or received. |
status | string | null | playground | Message status. |
read | boolean | Whether the message was read in the inbox. Default false. | |
timestamp | string | null | Channel timestamp of the message. | |
media_url | string | URL of the image, audio, video or document. | |
media_urls | string[] | null | sms | Media URLs of an MMS. |
filename | string | Original file name of the attachment. | |
file_name | string | webchat, playground | Original file name of the attachment. |
mime_type | string | MIME type of the attachment. | |
file_type | string | null | playground | MIME type of the attachment. |
file_size | integer | webchat, playground | Attachment size in bytes. |
s3_key / s3_path | string | null | playground | Storage key and s3:// path of the attachment. |
conversation_file_id | string | webchat, playground | Conversation file of the attachment. |
location_latitude / location_longitude | string | number | whatsapp, instagram | Location messages: coordinates. |
location_name / location_address | string | whatsapp, instagram | Location messages: place name and address. |
revoked | boolean | null | The contact deleted the message in WhatsApp. | |
edited | boolean | null | The message was edited (by the contact in WhatsApp, or an edited internal note). | |
message_text_original | string | null | Text before the edit. | |
order_data | object | null | WhatsApp catalog order sent by the contact. | |
interactive_data | object | null | Interactive reply (list or button) sent by the contact. | |
interactive_type | string | null | Type of the interactive reply. | |
button_data | object | null | Quick-reply button pressed by the contact. | |
campaign_id | integer | null | whatsapp, sms | Campaign that sent the message. |
is_bulk | boolean | sms | Sent by a bulk SMS campaign. |
is_echo | boolean | whatsapp, instagram, sms | true 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_history | boolean | Message imported from the WhatsApp Business app history when the number was connected. | |
from / to | string | null | sms | Sender and recipient phone numbers. |
error_code / error_message | string | null | sms | Provider error when the SMS failed. |
error | object | null | Error details when sending or the AI reply failed. | |
contact_deleted | boolean | null | sms | The contact was deleted. |
meta_contact_first_name / meta_contact_last_name | string | null | Contact name at the time of the message. | |
meta_contact_avatar_url | string | null | Contact avatar. | |
meta_contact_phone | string | null | sms | Contact phone. |
meta_contact_channel_wa_user_id | string | null | Contact's WhatsApp Business-Scoped User ID, when Meta sent one. | |
user_id | integer | null | Team member who sent the message. | |
meta_user_first_name / meta_user_last_name | string | null | Sender name. | |
meta_user_avatar_url | string | null | Sender avatar. | |
meta_user_role | string | null | Sender platform role. | |
ai_assistant_id | integer | null | AI assistant that wrote the message. | |
ai_assistant_name | string | null | Name of that assistant. | |
ai_model | object | null | all but sms | Model used for the AI reply. |
ai_structured_data | object | null | all but sms | Structured output returned with the AI reply. |
automation_id / automation_name | integer / string | null | Automation that sent the message. | |
automation_execution_id | integer | null | Automation execution that sent it. | |
is_from_automation | boolean | null | playground | Sent by an automation. |
follow_up_details | object | null | Details of an AI follow-up message. | |
change_metadata | object | null | Details of a system message that records a change (assignment, stage, ...). | |
tool_metadata | object | null | Details of an AI tool call message. | |
created_at | string (date-time) | Read-only. Creation time. | |
updated_at | string (date-time) | Read-only. Last update time. | |
deleted_at | string (date-time) | null | Read-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.