Inbox · Messages

List conversations

Returns conversations, one page at a time.

GEThttps://api.pozy.ai/v1/inbox/conversations

listInboxConversations

Request

Send your API key as Authorization: Bearer pz_live_.... Read-only keys can call it. Keys with the messages resource group disabled get 403 resource_group_disabled. Authentication

Query parameters

Name	Type	Notes
`profileId`	string
`platform`	string	One of `facebook`, `instagram`, `twitter`, `bluesky`, `reddit`, `telegram`, `whatsapp`, `imessage`, `sms`
`status`	string	One of `active`, `archived`
`folder`	string	One of `inbox`, `requests`Default `inbox`
`sortOrder`	string	One of `asc`, `desc`Default `desc`
`limit`	integer	Default `50`1 to 100
`cursor`	string
`accountId`	string
`tags`	string

Example

curl -X GET "https://api.pozy.ai/v1/inbox/conversations?limit=50" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/inbox/conversations?limit=50", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);

import os
import requests

resp = requests.get(
    "https://api.pozy.ai/v1/inbox/conversations",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={
        "limit": 50,
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Response

200 on success

dataarray of object
22 child fields
- idstring
- platformstring
- accountIdstring
- accountUsernamestring
- pageIdstring
  Can be null.
- participantIdstring
- participantNamestring
- participantPicturestring
  Can be null.
- participantVerifiedTypestring
  One of blue, government, business, none. Can be null.
- businessScopedUserIdstring
- whatsappUsernamestring
- lastMessagestring
- updatedTimestring (date-time)
- statusstring
  One of active, archived.
- unreadCountinteger
  At most 1000. Can be null.
- threadControlstring
  One of app, ai_agent, other.
- folderstring
  One of requests.
- isGroupboolean
- urlstring
  Can be null.
- instagramProfileobject
  Can be null.
  5 child fields
  isFollowerboolean
  Can be null.
  isFollowingboolean
  Can be null.
  followerCountinteger
  Can be null.
  isVerifiedboolean
  Can be null.
  fetchedAtstring (date-time)
  Can be null.
- metadataobject
  Can be null.
  22 child fields
  ctwa_clidstring
  ctwa_source_idstring
  ctwa_source_typestring
  ctwa_source_urlstring
  ctwa_headlinestring
  ctwa_bodystring
  ctwa_media_typestring
  ctwa_image_urlstring
  ctwa_video_urlstring
  ctwa_thumbnail_urlstring
  ctwa_captured_atstring (date-time)
  meta_ad_idstring
  meta_ad_sourcestring
  meta_ad_typestring
  meta_ad_refstring
  meta_ad_titlestring
  meta_ad_photo_urlstring
  meta_ad_video_urlstring
  meta_ad_post_idstring
  meta_ad_product_idstring
  meta_ad_flow_idstring
  meta_ad_captured_atstring (date-time)
- adAttributionobject
  Can be null.
  11 child fields
  adIdstringrequired
  Can be null.
  namestringrequired
  Can be null.
  syncedbooleanrequired
  campaignIdstringrequired
  Can be null.
  campaignNamestringrequired
  Can be null.
  adSetIdstringrequired
  Can be null.
  adSetNamestringrequired
  Can be null.
  adAccountIdstringrequired
  Can be null.
  adAccountNamestringrequired
  Can be null.
  platformPostIdstringrequired
  Can be null.
  isExternalbooleanrequired
  Can be null.
paginationobject
- hasMoreboolean
- nextCursorstring
  Can be null.
metaobject
- accountsQueriedinteger
- accountsFailedinteger
- failedAccountsarray of object
  6 child fields
  - accountIdstring
  - accountUsernamestring
    Can be null.
  - platformstring
  - errorstring
  - codestring
    Can be null.
  - retryAfterinteger
    Can be null.
- lastUpdatedstring (date-time)
- accountsSkippedarray of object
  2 child fields
  - accountIdstring
  - platformstring

200 response

{
  "data": [
    {
      "id": "6bfebd43ddc270f6d2c56fc5",
      "platform": "instagram",
      "accountId": "696e0b682d0a31188e7a2ba9",
      "accountUsername": "acme",
      "pageId": "675e1e95e076854531b4d051",
      "participantId": "6f0150243551cb6ee41f35e0",
      "participantName": "Acme",
      "participantPicture": "string",
      "participantVerifiedType": "blue",
      "businessScopedUserId": "61f84cc05876a1c25c483817",
      "whatsappUsername": "acme",
      "lastMessage": "Hello from Pozy",
      "updatedTime": "2026-10-02T09:00:00.000Z",
      "status": "active",
      "unreadCount": 42,
      "threadControl": "app",
      "folder": "requests",
      "isGroup": true,
      "url": "https://pozy.ai/media/example-1.jpg",
      "instagramProfile": {
        "isFollower": true,
        "isFollowing": true,
        "followerCount": 42,
        "isVerified": true,
        "fetchedAt": "2026-10-02T09:00:00.000Z"
      },
      "metadata": {
        "ctwa_clid": "692eb88a2c90929f2394053b",
        "ctwa_source_id": "6bf4334a1a6cba0bd31d44ae",
        "ctwa_source_type": "string",
        "ctwa_source_url": "https://pozy.ai/media/example-1.jpg",
        "ctwa_headline": "string",
        "ctwa_body": "string",
        "ctwa_media_type": "string",
        "ctwa_image_url": "https://pozy.ai/media/example-1.jpg",
        "ctwa_video_url": "https://pozy.ai/media/example-1.jpg",
        "ctwa_thumbnail_url": "https://pozy.ai/media/example-1.jpg",
        "ctwa_captured_at": "2026-10-02T09:00:00.000Z",
        "meta_ad_id": "61e6bf8a5c69195f41e50bb7",
        "meta_ad_source": "string",
        "meta_ad_type": "string",
        "meta_ad_ref": "string",
        "meta_ad_title": "string",
        "meta_ad_photo_url": "https://pozy.ai/media/example-1.jpg",
        "meta_ad_video_url": "https://pozy.ai/media/example-1.jpg",
        "meta_ad_post_id": "65196d015f4a678a60d69639",
        "meta_ad_product_id": "6ea27f3b17ac3128973b7ea9",
        "meta_ad_flow_id": "68770d6fe4e2e877d0403360",
        "meta_ad_captured_at": "2026-10-02T09:00:00.000Z"
      },
      "adAttribution": {
        "adId": "6f40fa2fb0a7e728dd1a73b7",
        "name": "Acme",
        "synced": true,
        "campaignId": "65a3737dd8b11ea61f199e6e",
        "campaignName": "Acme",
        "adSetId": "60484b408d44e7c2492bfec5",
        "adSetName": "Acme",
        "adAccountId": "666219aad7bab67ace411e4f",
        "adAccountName": "Acme",
        "platformPostId": "637f799b3039e6602e83fa4f",
        "isExternal": true
      }
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "string"
  },
  "meta": {
    "accountsQueried": 42,
    "accountsFailed": 42,
    "failedAccounts": [
      {
        "accountId": "696e0b682d0a31188e7a2ba9",
        "accountUsername": "acme",
        "platform": "instagram",
        "error": "string",
        "code": "string",
        "retryAfter": 1
      }
    ],
    "lastUpdated": "2026-10-02T09:00:00.000Z",
    "accountsSkipped": [
      {
        "accountId": "696e0b682d0a31188e7a2ba9",
        "platform": "instagram"
      }
    ]
  }
}

Errors

Errors use one shape: { error, type, code, param?, details? }. The ones you are most likely to see here:

400	invalid_request_error	A parameter or body field is missing or invalid. `param` names it.
401	authentication_error	The API key is missing, revoked or expired.
403	permission_error	The key is scoped to other profiles or has this resource group disabled.
429	rate_limit_error	Too many requests this minute. Wait for `Retry-After` seconds.

Every code is listed in Errors.

Request

Query parameters

Example

Response

Errors

More in Messages