REST API
Inbox and contacts
DM, mention and comment conversations, replies sent by hand, contacts, Threads replies waiting for approval, and audience totals.
A conversation is a DM thread, a Threads mention or a Naver Blog comment thread with one person. Replying to a DM sends a DM; replying to a mention or a comment answers in public under it.
A DM can only go out within 24 hours of the person's last message. Outside that window sending answers 403 window_closed. After you reply by hand, automations hold back for 30 minutes in that conversation.
Conversations
GET/v1/conversations
Conversations, latest message first. Filter by state, kind, unread, starred, account, platform or search.
| Name | Type | Description |
|---|---|---|
state | query | open (default) or closed. |
kind | query | dm, mention or comment. |
unread | query | 1 for unread only. |
starred | query | 1 for starred only. |
accountId | query | One connected account. |
platform | query | One platform id, e.g. instagram. |
search | query | Matches the username, the name or the last message. |
before | query | A lastMessageAt from the previous page. |
limit | query | 1-200. |
{
"data": [
{
"id": "cnv_91d2",
"accountId": "acc_7f3c",
"account": { "platform": "instagram", "handle": "@brand" },
"contact": { "id": "ctc_44a0", "username": "jiyoung", "name": "Jiyoung", "optedOut": false },
"kind": "dm",
"state": "open",
"unread": true,
"lastMessagePreview": "Is it still available?",
"window": { "open": true, "expiresAt": "2026-10-03T09:12:00.000Z", "mode": "window" }
}
],
"hasMore": false,
"counts": { "open": { "total": 1, "unread": 1 } }
}GET/v1/conversations/{id}
One conversation with its contact and messages.
POST/v1/conversations/{id}/messages
Reply as the account: a DM in DM conversations, a public reply in mention and comment conversations.
| Name | Type | Description |
|---|---|---|
textRequired | string | What to send. |
mediaId | string | Attach one uploaded file to a DM. |
{ "data": { "id": "msg_0c7e", "mid": "aWdfZAG…", "sentAs": "window" } }POST/v1/conversations/{id}/drafts/{messageId}
Send a draft an automation prepared for approval, optionally with edited text.
DELETE/v1/conversations/{id}/drafts/{messageId}
Throw a draft away without sending it.
POST/v1/inbox/sync
Import recent conversations from the channel for one account.
State
POST/v1/conversations/{id}/read
Mark it read.
POST/v1/conversations/{id}/open
Reopen a closed conversation.
POST/v1/conversations/{id}/close
Close it. It moves out of the open list.
POST/v1/conversations/{id}/star
Star it.
POST/v1/conversations/{id}/unstar
Remove the star.
POST/v1/conversations/{id}/assign
Assign it to a person (userId, defaults to you).
POST/v1/conversations/{id}/unassign
Clear the assignment.
Contacts
GET/v1/contacts
People who wrote to your accounts, with tags, fields, opt-out and whether they follow you where the channel says.
| Name | Type | Description |
|---|---|---|
accountId | query | One connected account. |
tag | query | Contacts with this tag. |
optedOut | query | 1 for people who opted out. |
search | query | Matches the username or the name. |
limit | query | 1-500, defaults to 100. |
GET/v1/contacts/{id}
One contact and their conversations.
PATCH/v1/contacts/{id}
Set tags, custom fields or opt-out.
| Name | Type | Description |
|---|---|---|
tags | string[] | Replaces the tags. Up to 50. |
fields | object | Custom fields to set, merged into the existing ones. |
optedOut | boolean | true stops every automated message to this person. |
POST/v1/contacts/{id}/refresh
Read the profile again from the channel.
DELETE/v1/contacts/{id}
Delete the contact and its conversations and messages on our side. Nothing changes on the channel.
Account level
GET/v1/accounts/{id}/audience
Follower totals, and on Threads a demographic breakdown. Follower lists are not available on any channel.
GET/v1/messaging/violations
Messages an automation did not send because a channel rule stopped it, newest first.
Threads replies waiting for approval
GET/v1/threads/pending-replies
Replies held for approval on a Threads account.
| Name | Type | Description |
|---|---|---|
accountIdRequired | query | A connected Threads account. |
POST/v1/threads/pending-replies/{replyId}
Approve or ignore one held reply.
| Name | Type | Description |
|---|---|---|
accountIdRequired | string | The Threads account that holds the reply. |
approve | boolean | false ignores the reply. Defaults to true. |