Messages

Direct messages live in conversations. Each conversation belongs to one connected account and holds the messages between that account and one person (or a group). This page covers reading and answering them. For the overall architecture, start with the Inbox overview.

#List conversations

curl "https://api.pozy.ai/v1/inbox/conversations?profileId=6650c1e2a3b4c5d6e7f80911&status=active&limit=50" \
  -H "Authorization: Bearer $POZY_API_KEY"

let cursor: string | undefined;
do {
  const query = new URLSearchParams({ profileId: "6650c1e2a3b4c5d6e7f80911", status: "active", limit: "50" });
  if (cursor) query.set("cursor", cursor);
  const res = await fetch(`https://api.pozy.ai/v1/inbox/conversations?${query}`, {
    headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.error);
  for (const c of data.data) console.log(c.platform, c.participantName, c.lastMessage);
  cursor = data.pagination.hasMore ? data.pagination.nextCursor ?? undefined : undefined;
} while (cursor);

import os
import requests

params = {"profileId": "6650c1e2a3b4c5d6e7f80911", "status": "active", "limit": 50}
while True:
    resp = requests.get(
        "https://api.pozy.ai/v1/inbox/conversations",
        headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
        params=params,
        timeout=30,
    )
    body = resp.json()
    for c in body["data"]:
        print(c["platform"], c["participantName"], c["lastMessage"])
    if not body["pagination"]["hasMore"]:
        break
    params["cursor"] = body["pagination"]["nextCursor"]

Each conversation carries the participant (participantName, participantPicture, participantVerifiedType), lastMessage, updatedTime, unreadCount and threadControl. Conversations that started from an ad carry adAttribution with the ad, ad set and campaign names. Instagram conversations can carry instagramProfile (isFollower, isFollowing, followerCount, isVerified); treat a missing value as unknown, never as "not a follower".

To find a conversation by what was said, use GET /v1/inbox/conversations/search with query (up to 200 characters) and an optional direction.

#Read messages

GET /v1/inbox/conversations/{conversationId}/messages needs the accountId and returns messages oldest first by default (sortOrder=desc flips it). Pages hold up to 100 messages.

{
  "id": "6650c1e2a3b4c5d6e7f81201",
  "conversationId": "6650c1e2a3b4c5d6e7f80b33",
  "platform": "instagram",
  "direction": "incoming",
  "message": "Hi, is the blue one still in stock?",
  "senderName": "Jane",
  "createdAt": "2026-10-29T14:00:03.000Z",
  "attachments": [],
  "deliveryStatus": null,
  "reactions": [],
  "isEdited": false,
  "isDeleted": false,
  "sentVia": null
}

• direction is incoming or outgoing.
• deliveryStatus on outgoing messages moves through sent, delivered, read, played (voice notes) or failed, where the platform reports it. deliveryError explains a failure.
• attachments[] have a type (image, video, audio, file, sticker, share, template), a url and, for links that expire, a refreshUrl. GET .../attachments/{index} always resolves a fresh link (a redirect by default, or JSON with format=json).
• Edited and unsent messages keep their history in editHistory, isDeleted and deletedAt.
• sentVia names what sent an outgoing message: human, api, broadcast, sequence, workflow, comment_automation or bulk-api. null means unknown, for example a message sent from the platform's own app.

#Reply

POST /v1/inbox/conversations/{conversationId}/messages sends a message into an existing conversation. accountId is required; everything else depends on what you send.

curl -X POST https://api.pozy.ai/v1/inbox/conversations/6650c1e2a3b4c5d6e7f80b33/messages \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b6c0f4e-1f0b-4b38-9a1e-6f2e8d7f1c55" \
  -d '{
    "accountId": "6650c1e2a3b4c5d6e7f80a22",
    "message": "Yes, the blue one is in stock. Want me to hold it?",
    "quickReplies": [
      { "title": "Hold it", "payload": "HOLD_BLUE" },
      { "title": "No thanks", "payload": "NO_THANKS" }
    ]
  }'

import { randomUUID } from "node:crypto";

const res = await fetch("https://api.pozy.ai/v1/inbox/conversations/6650c1e2a3b4c5d6e7f80b33/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    accountId: "6650c1e2a3b4c5d6e7f80a22",
    message: "Yes, the blue one is in stock. Want me to hold it?",
    quickReplies: [
      { title: "Hold it", payload: "HOLD_BLUE" },
      { title: "No thanks", payload: "NO_THANKS" },
    ],
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data);

import uuid

resp = requests.post(
    "https://api.pozy.ai/v1/inbox/conversations/6650c1e2a3b4c5d6e7f80b33/messages",
    headers={
        "Authorization": f"Bearer {os.environ['POZY_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "accountId": "6650c1e2a3b4c5d6e7f80a22",
        "message": "Yes, the blue one is in stock. Want me to hold it?",
        "quickReplies": [{"title": "Hold it", "payload": "HOLD_BLUE"}, {"title": "No thanks", "payload": "NO_THANKS"}],
    },
    timeout=30,
)
print(resp.json())

A 200 means Pozy accepted the message, not that it was delivered. Delivery arrives later as message.sent, then message.delivered and message.read (or message.failed) on platforms that report them.

#What you can send

A postback button with a payload of pozy:workflow:<workflowId> starts that workflow when tapped. See Workflows.

Upload a local file first with POST /v1/media/upload-direct (multipart) and send the returned url as attachmentUrl.

#Messaging windows

Platforms limit when a business can write to a person:

HUMAN_AGENT is refused on automated sends (workflows, sequences, broadcasts). The other message tags were retired by Meta and fail.

#Start a conversation

POST /v1/inbox/conversations opens a new conversation, or appends to the existing one with that person. Name the recipient with participantId or participantUsername.

• X: Pozy checks that the person accepts DMs from your account first and answers 422 with code DM_NOT_ALLOWED when they do not. Pass skipDmCheck: true if you already verified it. X DMs are billed per call (pricing).
• WhatsApp: a first message must be a template: pass templateName, templateLanguage, templateParams and, where the template has them, headerMedia and templateButtonParams.
• TikTok: businesses cannot start conversations.

#Manage conversations

#Message requests

On Facebook, DMs from people the Page has not accepted wait in a requests folder. List them with folder=requests and accept one with POST .../accept, which sends your first message and moves the thread into the inbox. Instagram does not expose the folder (the list answers 400 with PLATFORM_LIMITATION), but accepting still works, and requests arrive as message.received once the person writes.

#Hand a conversation to another app

On WhatsApp, Facebook and Instagram, another app can own a thread, for example Meta's own inbox app or a business agent. While it does:

• Incoming messages still arrive as message.received, flagged metadata.standby: true. Pozy runs no automation on them.
• Your sends answer 409 with code not_thread_owner.

Move the thread with POST /v1/inbox/conversations/{id}/thread-control:

conversation.control_changed fires whenever the owner changes. On WhatsApp, sending any message takes control back, so a bot that answers every message.received must skip standby messages.

#When a send fails

Send an Idempotency-Key with every reply. If the response is lost after a successful send, a retry with the same key returns the original response instead of a second message. A failed (non-2xx) request releases the key, so after an ambiguous 500, check the messages first; an empty result is inconclusive, not proof it was not sent. See Idempotency.

#Endpoints

#Webhook events