API referenceMessages

POST /inbox/conversations

Start a conversation (X only; Meta platforms only allow replies): sends the FIRST live DM to participantId or participantUsername. Text ≤10,000 or one attachment (mediaUrl or mediaId). X answers 403 when the person does not accept DMs from the account. Queued for approval (202) while approval applies

POST
/inbox/conversations

Authorization

BearerAuth
headerAuthorizationBearer <token>

API key sk_...

Request Body

application/json
  1. body
accountId*string

X account id

participantId?string

Numeric X user id

participantUsername?string

@username (instead of participantId)

text?string
Lengthlength <= 10000
mediaUrl?string

Public https URL of an image, GIF or video

mediaId?string

Id of an uploaded media

attachmentType?string
Value in"image""video"

Response Body

{message, conversation}

application/json
  1. response
message?
conversation?
Example Request
curl -X POST 'https://example.com/api/v1/inbox/conversations' \  -H 'Content-Type: application/json' \  -d '{  "accountId": "string"}'
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 GET

Direct-message conversations of this organization (Instagram, Messenger, WhatsApp, X), latest message first. Filled by inbound webhooks and POST /inbox/conversations/sync

POST /inbox/conversations/sync POST

Backfill conversations from Meta for an account: up to pages × limit conversations, each with its latest messages (Meta returns details for the 20 most recent messages only). Idempotent; no customer webhooks are emitted