WhatsApp

• Your WhatsApp number is connected in Pixl, under Connections › Channels.
• Templates are created in Pixl and approved by WhatsApp before you can send them.
• A template starts a conversation; a free-text reply only works within 24 hours of the person's last message.
• Scopes: campaigns:write to send a template to a person or to numbers, chat:write to send in a conversation and read messages, and deployments:read and workspace:read to find your number's id.

POST/whatsapp/messagesScope: campaigns:write

Sends one approved template to one person, with that person's own values, and returns the message. The person is found in your contacts by number, or added. The message goes into their conversation on that number, and when they reply, the agent answers there as usual.

curl -X POST "https://api.pixlagents.com/api/v1/whatsapp/messages" \
  -H "Authorization: Bearer $PIXL_API_KEY" \
  -H 'Idempotency-Key: ext_123-reminder-1' \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+919876543210",
  "template_name": "appointment_reminder",
  "language": "en",
  "variables": [
    "Asha",
    "Saturday 10:30 am"
  ],
  "agent_id": "agent_123",
  "contact_name": "Asha Rao",
  "external_ref": "ext_123"
}'

{
  "message_id": "msg_456",
  "conversation_id": "conv_987",
  "contact_id": "contact_321",
  "status": "sent",
  "external_ref": "ext_123"
}

• status is sent: WhatsApp accepted it. Its delivery and reading come as message.status events, or with the message when you read it.
• A marketing template goes out only between 09:00 and 21:00 where the person is. Outside that, it's refused with outside_send_window, and detail.opens_at (UTC) says when to send. Pixl doesn't queue it. Utility and authentication templates go at any hour.
• Send an Idempotency-Key header, up to 128 characters, to retry safely: the same key within 7 days returns the first answer and sends nothing. A refused send doesn't keep its key. Without one, a retry sends again.

Every refusal is { "detail": { "code", "message" } }, and nothing is saved:

Sending to a list of numbers, or to one person by phone_number_id, needs the id Pixl gives your WhatsApp number. Find it once and keep it:

• Your business: GET /workspaces/{workspace_id}/businesses. Most workspaces have one; use the one with is_default: true.
• Its WhatsApp accounts: GET /businesses/{business_id}/whatsapp-accounts.
• The account's numbers: GET /businesses/{business_id}/whatsapp-accounts/{account_id}/phones. The id of your number is the one to send from.

curl "https://api.pixlagents.com/api/v1/businesses/business_123/whatsapp-accounts/account_456/phones" \
  -H "Authorization: Bearer $PIXL_API_KEY"

[
  {
    "id": "number_789",
    "e164": "+918012345678",
    "display_name": "Sample Clinic",
    "quality_rating": "GREEN"
  }
]

POST/agents/{agent_id}/broadcastScope: campaigns:write

Sends one approved template to a list of numbers, from your number, in your agent's name. Replies come back to that agent. Every number gets the same values; for one person with their own, use the send above.

curl -X POST "https://api.pixlagents.com/api/v1/agents/agent_123/broadcast" \
  -H "Authorization: Bearer $PIXL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Appointment reminder, Asha Rao",
  "template_name": "appointment_reminder",
  "template_language": "en",
  "phone_number_id": "number_789",
  "recipient_ids": [
    "+919876543210"
  ],
  "template_params": {
    "body_variables": [
      "Asha",
      "Saturday 10:30 am"
    ]
  }
}'

{
  "campaign_id": "campaign_456",
  "status": "queued"
}

It sends straight away. Each number still passes the consent rules below, so one may be skipped while the others go. Keep campaign_id to see who got it.

GET/campaigns/{campaign_id}/recipientsScope: campaigns:read

curl "https://api.pixlagents.com/api/v1/campaigns/campaign_456/recipients" \
  -H "Authorization: Bearer $PIXL_API_KEY"

{
  "campaign_id": "campaign_456",
  "channel": "whatsapp",
  "recipients": [
    {
      "recipient_id": "recipient_789",
      "status": "read",
      "phone": "+919876543210",
      "name": "Asha Rao",
      "contact_id": "contact_321",
      "sent_at": "2026-10-26T05:00:04",
      "delivered_at": "2026-10-26T05:00:06",
      "read_at": "2026-10-26T05:03:41",
      "replied_at": null,
      "whatsapp_message_id": "wamid.HBgM",
      "error": null,
      "conversation_id": "conv_987"
    }
  ],
  "total": 1,
  "status_counts": {
    "read": 1
  }
}

• status moves from pending to sent, delivered, read and replied. failed and skipped say why in error.
• conversation_id is the person's conversation, once the template is in it. Use it to reply.
• Large lists come in pages: limit (up to 2,000) and offset. status_counts always covers the whole send.

POST/chat/conversations/{conversation_id}/send-templateScope: chat:write

Sends one template in an existing WhatsApp conversation, from the number that conversation is on. Use it when the 24-hour window has closed. To see which templates the conversation's number can send, and why any can't, use GET /chat/conversations/{conversation_id}/templates.

curl -X POST "https://api.pixlagents.com/api/v1/chat/conversations/conv_987/send-template" \
  -H "Authorization: Bearer $PIXL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "template_name": "appointment_reminder",
  "variables": [
    "Asha",
    "Saturday 10:30 am"
  ]
}'

{
  "status": "ok",
  "message_id": "msg_456",
  "content": "Hi Asha, a reminder of your appointment on Saturday 10:30 am."
}

Templates with a header image, video or document, a header variable or a variable button link can't be sent here; send them to the number instead. Refusals come back with the reason in detail:

POST/chat/{conversation_id}/send-as-humanScope: chat:write

Sends a free-text reply in a conversation, as a person on your team. On WhatsApp it only works within 24 hours of the person's last message; after that, send a template. A reply doesn't switch the agent off: it still answers the person's next message.

curl -X POST "https://api.pixlagents.com/api/v1/chat/conv_987/send-as-human" \
  -H "Authorization: Bearer $PIXL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Thanks Asha, see you on Saturday."
}'

{
  "status": "ok",
  "message_id": "msg_457"
}

• 400: outside the 24-hour window, or the message couldn't be sent. detail says which.
• 403: the person opted out, or your team turned off people sending from this agent's conversations.

Every send checks the person's consent first. You can't switch these checks off.

• Someone who texted STOP, or who is on your opt-out list, gets nothing you start: no template, no reply. A send to a list skips them with error: "opted out".
• If they opted out and then wrote to you again, you may answer inside the 24 hours their message opened.
• Someone who stopped promotions from WhatsApp itself still gets utility templates, like an appointment reminder, but no marketing ones.
• People who ignore promotions rest from them for 30 days. Utility templates still reach them. The switch is in Pixl, under your consent settings.
• If your workspace asks for an opt-in before promotions, marketing templates go only to people with one on record.

To keep Pixl in step with your own records, import opt-ins and add opt-outs through the API: see Contacts and consent.

GET/chatScope: chat:read

Your workspace's conversations, most recently active first.

curl -G "https://api.pixlagents.com/api/v1/chat" \
  -H "Authorization: Bearer $PIXL_API_KEY" \
  --data-urlencode 'channel=whatsapp' \
  --data-urlencode 'include_unreplied_campaigns=true' \
  --data-urlencode 'limit=50'

{
  "conversations": [
    {
      "id": "conv_987",
      "channel": "whatsapp",
      "agent_id": "agent_123",
      "contact_id": "contact_321",
      "contact_name": "Asha Rao",
      "contact_phone": "+919876543210",
      "status": "active",
      "ai_active": true,
      "last_message_at": "2026-10-26T05:04:02",
      "last_inbound_at": "2026-10-26T05:04:02",
      "message_count": 4
    }
  ],
  "total": 1,
  "hidden_count": 0
}

One conversation, with its messages

GET/chat/{conversation_id}Scope: chat:read

curl "https://api.pixlagents.com/api/v1/chat/conv_987" \
  -H "Authorization: Bearer $PIXL_API_KEY"

{
  "id": "conv_987",
  "channel": "whatsapp",
  "contact_opted_out": false,
  "hours_since_last_inbound": 0.4,
  "messages": [
    {
      "id": "msg_456",
      "role": "assistant",
      "content": "Hi Asha, a reminder of your appointment on Saturday 10:30 am.",
      "template_name": "appointment_reminder",
      "delivery_status": "read",
      "delivered_at": "2026-10-26T05:00:06",
      "read_at": "2026-10-26T05:03:41",
      "failure_code": null,
      "failure_reason": null,
      "provider_message_id": "wamid.HBgM",
      "created_at": "2026-10-26T05:00:04"
    },
    {
      "id": "msg_458",
      "role": "user",
      "content": "Yes, I will be there.",
      "delivery_status": "queued",
      "created_at": "2026-10-26T05:04:02"
    }
  ]
}

• role is user for the person and assistant for your side. A reply from your team carries metadata_json.human_sent: true.
• hours_since_last_inbound tells you whether the 24-hour window is open. contact_opted_out tells you whether they opted out.
• Attachments are in attachments, each with a storage_url.
• To find a person's conversation from their number, look them up with GET /contacts (search, with include_channel_auto=true), then use their last_conversation_id, or list with contact_id.
• A long conversation comes in pages when you ask: messages_limit (up to 200) gives the newest that many, oldest first, and messages_next_cursor; pass it as before for older ones. It's null when there are none. Without messages_limit, you get every message.

GET/messagesScope: chat:read

Every message in your workspace's customer conversations, on every channel, oldest first. Use it to keep your system in step, or to catch up after your webhook endpoint was down.

curl -G "https://api.pixlagents.com/api/v1/messages" \
  -H "Authorization: Bearer $PIXL_API_KEY" \
  --data-urlencode 'since=2026-10-27T00:00:00Z' \
  --data-urlencode 'limit=100'

{
  "items": [
    {
      "id": "msg_458",
      "conversation_id": "conv_987",
      "contact_id": "contact_321",
      "channel": "whatsapp",
      "direction": "inbound",
      "sender": {
        "type": "customer",
        "agent_id": null,
        "user_id": null,
        "campaign_id": null
      },
      "text": "Yes, I will be there.",
      "content_restricted": false,
      "template_name": null,
      "status": "received",
      "failure": null,
      "created_at": "2026-10-27T05:04:02Z",
      "sent_at": null,
      "delivered_at": null,
      "read_at": null,
      "failed_at": null,
      "attachments": [],
      "external_ref": null
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0yNyJ9",
  "has_more": false
}

• next_cursor is always there, even on an empty page. When has_more is false, keep the last next_cursor and ask again with it later.
• A message appears about a minute after it's saved, so a page never skips one still being written. For real time, use webhooks.
• status and its times are as they are when you read. A later change doesn't bring a message back into the list: it comes as a message.status event, or read the conversation.
• sender.type: customer, agent, person (a teammate), campaign, api (sent with POST /whatsapp/messages) or system.
• Not in it: the turns of phone calls (use the call log), the agent chat inside Pixl, and test conversations.
• In a health business, the words of call conversations are left out unless your key may read them: text: null, content_restricted: true.

Subscribe to message.status on a webhook to hear of each move as it happens, and to message.received for replies. Each message your side sends carries delivery_status: queued, then sent, delivered and read, or failed. A failed message has WhatsApp's own code in failure_code and a reason in failure_reason. The ones you'll see most: