API referenceMessages

POST /inbox/conversations/{id}/messages

Send a LIVE direct message to the participant: text (Instagram ≤1000, Messenger ≤2000 characters) or one attachment (mediaUrl or mediaId), not both. Allowed within 24 hours of the participant's last message, or within 7 days with tag HUMAN_AGENT (needs Meta's Human Agent permission); otherwise 409 outside_messaging_window without calling Meta. WhatsApp conversations take the WhatsAppOutbound fields (text ≤4096, mediaUrl / mediaId / whatsappMediaId with caption, template, interactive, location or reaction, replyTo; no tag): within 24 hours anything, outside only a template. 403 approval_required while approval applies; 403 missing_permission without the messaging permission. Emits message.sent

POST
/inbox/conversations/{id}/messages

Authorization

BearerAuth
headerAuthorizationBearer <token>

API key sk_...

Path Parameters

id*string

Conversation id

Request Body

application/json
  1. body
text?string
Lengthlength <= 2000
mediaUrl?string

Public https URL of the attachment

mediaId?string

Id of an uploaded media (POST /media) with a publicUrl

attachmentType?string

Default: from the media MIME type or the URL extension (else image)

Value in"image""video""audio""file"
tag?"HUMAN_AGENT"

Instagram/Messenger: human agent reply up to 7 days after the participant's last message

Value in"HUMAN_AGENT"
whatsappMediaId?string

WhatsApp: uploaded WhatsApp media id

caption?string

WhatsApp media caption

filename?string

WhatsApp document name

template?unknown

WhatsApp: {name, language, components}

interactive?unknown

WhatsApp: see WhatsAppOutbound

location?unknown

WhatsApp: {latitude, longitude, name?, address?}

reaction?unknown

WhatsApp: {messageId, emoji}

replyTo?string

WhatsApp: wamid of the quoted message

Response Body

{message, conversation}

application/json
  1. response
message?
conversation?
Example Request
curl -X POST 'https://example.com/api/v1/inbox/conversations/string/messages' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "message": {    "id": "string",    "conversationId": "string",    "platformMessageId": "string",    "direction": "inbound",    "type": "text",    "text": "string",    "attachments": [      {        "type": "string",        "url": "string"      }    ],    "postback": {      "title": "string",      "payload": "string"    },    "reactions": [      {        "emoji": "string",        "by": "participant"      }    ],    "replyToMid": "string",    "isEcho": true,    "isDeleted": true,    "status": "received",    "tag": "HUMAN_AGENT",    "sentAt": "2019-08-24T14:15:22Z",    "deliveredAt": "2019-08-24T14:15:22Z",    "readAt": "2019-08-24T14:15:22Z",    "source": "webhook",    "content": null,    "pricing": null,    "error": "string",    "failedAt": "2019-08-24T14:15:22Z"  },  "conversation": {    "id": "string",    "accountId": "string",    "platform": "instagram",    "platformConversationId": "string",    "participant": {      "id": "string",      "username": "string",      "name": "string",      "pictureUrl": "string",      "phone": "string",      "userId": "string",      "parentUserId": "string"    },    "lastMessage": {      "text": "string",      "direction": "inbound",      "at": "2019-08-24T14:15:22Z"    },    "unreadCount": 0,    "lastReadAt": "2019-08-24T14:15:22Z",    "participantReadAt": "2019-08-24T14:15:22Z",    "status": "active",    "messagingWindow": {      "open": true,      "closesAt": "2019-08-24T14:15:22Z",      "humanAgentClosesAt": "2019-08-24T14:15:22Z"    },    "syncedAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}

GET /inbox/conversations/{id}/messages GET

Messages of a conversation, oldest → newest within the page; before pages back in time

POST /inbox/conversations/{id}/read POST

Mark the conversation read in Postgale (unreadCount 0) and, unless platform is false, as seen on Meta (mark_seen; WhatsApp: the latest inbound message is marked read; best effort: a failure or a closed messaging window is returned in warnings)