API resource

Direct messages

List conversations

GET/v1/inbox/conversations

Works on: Instagram, Facebook, X, WhatsApp

DM threads across every account, most recently active first. Paginate with cursor.

Query parameters

platformstring

Only this network.

accountIdstring

Only this account.

statusstring

active or archived.

limitinteger

Page size.

cursorstring

pagination.nextCursor from the previous page.

curl "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations?status=active&limit=20" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "data": [
    {
      "id": "conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt",
      "platform": "instagram",
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "accountUsername": "kevbuildsapps",
      "participantName": "Maya",
      "lastMessage": "Is the course still open?",
      "updatedTime": "2026-09-25T17:02:10.000Z",
      "status": "active",
      "unreadCount": 1
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  }
}

List messages

GET/v1/inbox/conversations/{conversationId}/messages

Works on: Instagram, Facebook, X, WhatsApp

Messages in one thread, oldest first by default.

Path parameters

conversationIdstringrequired

The conv_ id.

Query parameters

accountIdstringrequired

The account (acc_...) the post or conversation belongs to.

limitinteger

Up to 100.

cursorstring

pagination.nextCursor from the previous page.

sortOrderstring

asc (default) or desc.

curl "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations/conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt/messages?accountId=acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "status": "success",
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  },
  "messages": [
    {
      "id": "msg_Hk2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9X",
      "conversationId": "conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt",
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "platform": "instagram",
      "message": "Is the course still open?",
      "senderName": "Maya",
      "direction": "incoming",
      "createdAt": "2026-09-25T17:02:10.000Z",
      "attachments": []
    }
  ]
}

Start a conversation

POST/v1/inbox/conversations

Works on: WhatsApp, X

Messages someone first. If a conversation with them already exists, the message joins that thread.

WhatsApp only delivers free text within 24 hours of the customer’s last message, so a new conversation starts with an approved template: pass templateName, templateLanguage and templateParams (values for the template’s variables, in order). Meta bills the delivery to your WhatsApp Business account. On X, pass message.

Body

accountIdstringrequired

The account (acc_...) the post or conversation belongs to.

participantIdstring

WhatsApp: the phone number in international format (+14165550123). X: the numeric user id.

participantUsernamestring

X handle, instead of participantId.

messagestring

Message text (X).

templateNamestring

WhatsApp: an approved template (see WhatsApp templates and flows).

templateLanguagestring

WhatsApp: the template’s language code, e.g. en_US.

templateParamsstring[]

WhatsApp: values for the text header, body and dynamic URL buttons, in that order.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "participantId": "+14165550123",
    "templateName": "order_update",
    "templateLanguage": "en_US",
    "templateParams": [
      "Sam",
      "#1042"
    ]
  }'
Response 201
{
  "success": true,
  "data": {
    "messageId": "msg_Hk2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9X",
    "conversationId": "conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt",
    "participantId": "14165550123"
  }
}

Search conversations

GET/v1/inbox/conversations/search

Works on: WhatsApp, Instagram, Facebook, X

Finds conversations by words inside messages, or by the contact’s name, username or phone number. Each hit carries up to 3 of its most recent matching messages.

Query parameters

querystringrequired

Text to search for.

directionstring

incoming or outgoing: only match messages sent to you or by you.

platformstring

Limit to one network, e.g. whatsapp.

accountIdstring

The account (acc_...) the post or conversation belongs to.

limitinteger

Maximum conversations to return.

cursorstring

pagination.nextCursor from the previous page.

curl "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations/search?query=refund" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "data": [
    {
      "conversation": {
        "id": "conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt",
        "platform": "whatsapp",
        "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
        "participantName": "Sam Lee",
        "lastMessageAt": "2026-10-09T17:20:00.000Z"
      },
      "matchCount": 1,
      "matches": []
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  }
}

Send a message

POST/v1/inbox/conversations/{conversationId}/messages

Works on: Instagram, Facebook, X, WhatsApp

Replies in the thread. Attach one file with attachmentUrl, which can be a med_ id from Upload media.

Path parameters

conversationIdstringrequired

The conv_ id.

Body

accountIdstringrequired

The account (acc_...) the post or conversation belongs to.

messagestring

Message text. Required unless attaching.

attachmentUrlstring

A med_ id or public URL.

attachmentTypestring

image, video, audio or file.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations/conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt/messages" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "message": "It is! Enrollment closes Friday. Want the link?"
  }'
Response 200
{
  "success": true,
  "data": {
    "messageId": "msg_Hk2Qp7Vz4Ny9Tx1Lm6Rc3Wb8Js5Df0Ga7Ue2Ki4Oq9X",
    "conversationId": "conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt"
  }
}

Mark as read

POST/v1/inbox/conversations/{conversationId}/read

Works on: Instagram, Facebook, X, WhatsApp

Clears the unread count for a conversation.

Path parameters

conversationIdstringrequired

The conv_ id.

Body

accountIdstringrequired

The account (acc_...) the post or conversation belongs to.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations/conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt/read" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r"
  }'
Response 200
{
  "success": true
}

Archive a conversation

PUT/v1/inbox/conversations/{conversationId}

Works on: Instagram, Facebook, X, WhatsApp

Set status to archived to file a thread away, or active to bring it back.

Path parameters

conversationIdstringrequired

The conv_ id.

Body

accountIdstringrequired

The account (acc_...) the post or conversation belongs to.

statusstringrequired

active or archived.

curl -X PUT "https://creatoros-production-5658.up.railway.app/v1/inbox/conversations/conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "status": "archived"
  }'
Response 200
{
  "success": true
}