PostZen
Inbox

Search direct message conversations

GET
/v1/inbox/conversations/search

Searches the conversations PostZen has already synced — Meta exposes no message search API, so this reads PostZen's own copy and refreshes it first. Message text matches whole tokens, case- and accent-insensitively (cafe finds café, art does not match start); participant names and usernames match on substring. Setting direction narrows the search to message text only, so a thread that matched only on the participant's name is excluded. Read-only and read-write API keys are accepted.

Authorization

bearerAuth
AuthorizationBearer <token>

PostZen API key.

In: header

Query Parameters

query*string

Search term.

direction?string

Match only messages the account received (incoming) or sent (outgoing). Restricts matching to message text.

accountId?string

Restrict the read to one connected account. Omitted, every Instagram account the key can reach is queried.

profileId?string

Restrict the read to accounts on one profile.

platform?string

Restrict the read to one platform. Direct messages cover Instagram only; any other value is a validation error.

limit?integer

Page size.

cursor?string

Pagination cursor from pagination.nextCursor. Unlike the list cursor this one is an offset into the result set, so it is only valid for the same query.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/inbox/conversations/search?query=string"
{  "data": [    {      "conversation": {        "id": "t_17845791234567890",        "platform": "instagram",        "accountId": "k17d8s9f0a1b2c3d4e5f6g7h8i",        "participantName": "Jane Doe",        "participantUsername": "janedoe",        "status": "active",        "lastMessage": "Is the sale still on?",        "lastMessageAt": "2026-08-18T16:04:11.000Z"      },      "matchCount": 2,      "matches": [        {          "id": "aWdfZGFtOm1zZ18x",          "text": "Is the sale still on?",          "direction": "incoming",          "timestamp": "2026-08-18T16:04:11.000Z"        },        {          "id": "aWdfZGFtOm1zZ18w",          "text": "The sale runs through Friday.",          "direction": "outgoing",          "timestamp": "2026-08-17T09:12:44.000Z"        }      ]    }  ],  "pagination": {    "hasMore": false,    "nextCursor": null  },  "meta": {    "accountsQueried": 2,    "accountsFailed": 0,    "failedAccounts": [],    "lastUpdated": "2026-08-18T16:10:00.000Z"  }}
{  "error": "Direct messages support Instagram accounts only.",  "code": "platformUnsupported",  "platform": "tiktok"}
{  "error": "Unauthorized"}
{  "error": "Reconnect the account to grant PostZen access to its messages.",  "code": "platformCapabilityMissing",  "platform": "instagram"}
{  "error": "That conversation could not be found.",  "code": "conversationNotFound"}
{  "error": "This connection needs to be reauthorized before its messages can be read.",  "code": "connectionDead"}
{  "error": "rate_limited",  "retryAfter": 30}
{  "error": "Failed to create post"}

List direct message conversations GET

Returns the Instagram direct message threads PostZen holds for the accounts this key can reach, newest activity first, and refreshes that stored copy from the platform as a side effect (throttled per account, so a tight polling loop costs nothing extra). `meta` reports which accounts could not be refreshed; their stored threads are still returned. Read-only and read-write API keys are accepted.

Get a direct message conversation GET

Returns one thread, refreshing PostZen’s stored copy from the platform first. Read-only and read-write API keys are accepted.