Are you an LLM? You can read better optimized documentation at /docs/api/messages.md for this page in Markdown format
Messages & Webhooks
Use Perfox as your WhatsApp provider: send text, media and locations you chose, and receive every inbound message and delivery update on your own endpoint. No AI runs on these sends — what you pass is exactly what is sent — but the number you send from must belong to a published agent, which is how Perfox knows which WhatsApp connection to use and where the customer's reply should go.
| Operation | Endpoint | Scope |
|---|---|---|
| Send a message | POST /api/v1/messages | conversations:write |
| List messages | GET /api/v1/messages | conversations:read |
| Read one message | GET /api/v1/messages/{id} | conversations:read |
| Refresh templates from your providers | POST /api/v1/templates/sync | conversations:write |
| List templates | GET /api/v1/templates | conversations:read |
| Subscribe to events | POST /api/v1/webhook-subscriptions | webhooks:write |
| List subscriptions | GET /api/v1/webhook-subscriptions | webhooks:read |
| Update one | PATCH /api/v1/webhook-subscriptions/{id} | webhooks:write |
| Delete one | DELETE /api/v1/webhook-subscriptions/{id} | webhooks:write |
| Send a test delivery | POST /api/v1/webhook-subscriptions/{id}/test | webhooks:write |
Sending
bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/messages" \
-H "Authorization: Bearer sk_…" \
-H "Content-Type: application/json" \
-d '{
"channel": "whatsapp",
"from": "+918000000001",
"to": "+919876543210",
"text": "Your order #4182 has shipped."
}'| Field | Values |
|---|---|
channel | whatsapp — optional, but if sent it must be whatsapp. Any other value is refused, not silently sent on WhatsApp; for sms/email/phone use POST /api/v1/outbound. |
from | The WhatsApp number this goes out on — the platform resolves which agent owns it |
agent_id | Instead of from, never alongside it |
to | The customer's number |
text | The exact words to send |
media | An image, audio clip, video or document — by public URL |
location | A map pin: latitude, longitude, and optional name / address |
template | An approved template plus its variables — the only thing deliverable outside the 24-hour window |
The message is recorded, billed and visible in the Studio like any other, and the customer's reply arrives the same way any other reply does. The only difference is that no model was asked what to say.
A successful send returns 201:
json
{
"id": "01a0…",
"conversation_id": "01a0…",
"agent_id": "01a0…",
"channel": "whatsapp",
"to": "+919876543210",
"from": "+918000000001",
"send_authorized": true,
"status": "sent",
"provider_message_id": "…"
}id is what you pass to GET /api/v1/messages/{id}. status: "sent" means the provider accepted the message; delivery arrives later. Add customer_id to the request to attach the message to a customer you already know instead of looking them up by phone number.
Address by number, not by agent
from is matched exactly against the WhatsApp number on each published agent's Trigger.
- A number no published agent claims → 404
not_found, naming the number. - A number two agents claim → 422
ambiguous_sender, with the competingagent_ids, rather than resolved by picking one. Sendagent_idto choose. - A number whose agent cannot run → 422
sender_agent_invalid, with what is wrong with it.
An agent_id is accepted instead, but sending both is rejected: two ways of saying the same thing that can disagree is how a message ends up on the wrong number.
The message goes out from exactly the from number you name — even when its agent owns more than one WhatsApp number. There is no default sender: an agent_id whose WhatsApp Trigger names no number is refused with 422 no_sender_number.
Where you can send
A to outside the countries Perfox may message (India by default), or a premium-rate or special-rate number, is refused with 422 destination_not_allowed before anything is written — the same rule POST /api/v1/outbound applies.
WhatsApp sends from your workspace are limited per rolling 24 hours (2,000 by default). A send past the limit is not delivered and is reported as a failed send.
Exactly one of text, media, location or template
They are different messages, so sending two would deliver one of them and leave you unable to tell which — the response ids and status are identical either way. The API refuses the request instead.
Outside WhatsApp's 24-hour session window only an approved template is deliverable. Text, media and a location all require an open window, which a customer opens by messaging you. See WhatsApp for the window and for getting templates approved.
Sending a template
json
{
"to": "+919876543210",
"template": {
"name": "order_confirmation",
"language": "en_US",
"body_parameters": ["Priya", "A-1042"],
"header": { "type": "image", "url": "https://www.example.com/order.png" },
"buttons": [{ "sub_type": "quick_reply", "index": 0, "payload": "track" }]
}
}| Field | Meaning |
|---|---|
name | The template's approved name |
language | Its language code, e.g. en_US (the default). The same name in two languages is two templates |
body_parameters | Ordered values for the body's 1, 2 … placeholders. An empty string is allowed |
header | Only when the approved header takes a value: text with header.text, or image / video / document with header.url |
buttons | Values for buttons that take one, matched by index — the button's position in the approved template. quick_reply takes payload; url takes text, the dynamic end of the approved link |
Not sure what a template needs? Ask first.
One-time passcodes (authentication templates)
An AUTHENTICATION template — a one-time passcode — sends the same way, with one rule specific to a Plivo connection.
json
{
"to": "+91 98765 00001",
"template": {
"name": "login_code",
"language": "en_US",
"body_parameters": ["482913", "log in"]
}
}login_code's approved body is "Your verification code is 1. Use it to 2. Do not share it with anyone." — two values, not one, which is exactly the mistake the next section warns about.
On a Plivo connection, send the body only — never buttons
An authentication template's button is a one-tap "copy code" button, and Plivo fills it in itself from the template's own approval — you never supply a value for it. GET /api/v1/templates reflects this: a Plivo authentication template's params carries no buttons to fill in at all.
If you send buttons anyway, Perfox refuses the request straight away with 422 — nothing is sent and nothing is recorded, so you can fix it and retry at once:
json
{
"error": "template_buttons_not_allowed",
"message": "`login_code` is an AUTHENTICATION template on Plivo, which fills its OTP button itself. Send `body_parameters` only — a `buttons` array is rejected by the provider after we accept it.",
"template": "login_code",
"category": "AUTHENTICATION",
"provider": "plivo"
}Perfox can only refuse a template it has on record for your sending number, so sync first. A template it hasn't seen is still sent, and a buttons array then fails later on the delivery receipt as Plivo error 10, "Invalid Message".
This is Plivo-specific, observed with real sends. Perfox has not sent an authentication template through a direct Meta connection, so this rule is not known to carry over — Meta's own docs for one-tap and copy-code authentication templates say the opposite, that the code is sent twice, once in the body and again in the button ("this value must appear twice in the payload" — see Meta's authentication-template documentation).
A sub_type of copy_code is never needed — it isn't part of the send contract either way.
Don't assume the body takes one value. An approved authentication template can take a second value besides the code itself — what the code is for, for example. Sending too few values is accepted (201) and fails afterwards as a Meta 350, Template Parameter Errors — the same asynchronous failure covered in Discovering templates below. Check params.body_parameter_count for the exact template first; don't guess it from its name.
🛑 A 201 here means accepted, not delivered — worth restating because both mistakes above are invisible until the delivery receipt arrives. See Following delivery.
The Sender action still gates it
The owning agent must have a WhatsApp Sender on its canvas, exactly as an agent-written reply must. A provider send is not a way around that gate: without it the request is refused up front with 422 sender_not_authorized, before anything is written — so a message is never recorded as sent when nothing went out. An agent that is still a draft is refused with 422 agent_not_published, and a workspace whose prepaid credit balance can't fund the send gets 402 out_of_credits, also before anything is written.
Discovering templates
A template needs its name, its language and exactly the right values. Getting the count wrong does not fail when you send: the request is accepted, and WhatsApp rejects the message afterwards. It arrives as a failed delivery (see Following delivery) — on Plivo with code 350, Template Parameter Errors. So look it up first.
Discovery is two calls. Sync asks your WhatsApp providers for their templates and keeps a copy; list reads that copy and never contacts a provider, so it is fast and cannot be rate-limited.
bash
# 1. Refresh the copy from your providers
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/templates/sync" \
-H "Authorization: Bearer sk_…"
# 2. Read it
curl "https://<your-workspace>-api.perfox.ai/api/v1/templates" \
-H "Authorization: Bearer sk_…"The list returns every template on every WhatsApp connection in your workspace, with its status, and synced_at — when the copy was last refreshed. A template that takes one body value and an image header comes back like this:
json
{
"templates": [
{
"name": "festive_offer_banner",
"language": "en_US",
"status": "pending",
"category": "MARKETING",
"provider_template_id": "975439852254433",
"provider": "meta_whatsapp",
"credential_id": "meta_whatsapp",
"params": {
"body_parameter_count": 1,
"body_text": "Hello {{1}}, our festive sale is now live and every item in the store carries a special discount this week. Visit us to see the full range before the offer closes.",
"header": { "type": "image" }
}
}
],
"synced_at": "2026-09-27T14:28:39.561Z"
}Only a template with status: "approved" can be sent. The others are pending, rejected, paused, disabled, or unknown — a status the provider reported that Perfox does not recognise, which is never treated as approved (its original word is in raw_status). The same name can appear twice when two connections hold it; credential_id says which one.
Your agents have the same pair as tools: sync_whatsapp_templates and list_whatsapp_templates.
What params tells you
| Field | Meaning |
|---|---|
body_parameter_count | How many values body_parameters must carry |
body_text | The approved body with its placeholders, so you can match values to slots |
header | Present only when the header takes a value — text needs header.text; image, video and document need header.url. A fixed header is absent: it needs nothing |
buttons | Each button that takes a value, with the index to send and its sub_type. Fixed buttons take nothing and are not listed |
unsupported | Parts of the template this API cannot send. If present, the template is only partly sendable here |
No params means "unknown", not "nothing to fill"
WARNING
When a template has no params, Perfox could not read its structure from the provider. It does not mean the template takes no values — sending none on that assumption is exactly the failed delivery described above.
Meta returns each template's structure with its list, so Meta templates carry params. Plivo returns a summary, so each Plivo template is read separately during a sync; one that could not be read comes back without params. Sync again, or check the template in your provider's console.
When params is missing, the row can also carry params_unavailable, saying why — never alongside params itself:
params_unavailable | Meaning | What to do |
|---|---|---|
rate_limited | Your provider throttled Perfox while it was reading this template | Run POST /api/v1/templates/sync again — the retry usually fills it in |
not_readable | The provider answered, but with no structure Perfox could parse | Re-syncing won't help; check the template in your provider's console |
A row that has params never carries params_unavailable — the reason is dropped the moment a spec arrives.
Templates for one sending number
Pass the number you send from to see only what it can use:
bash
curl "https://<your-workspace>-api.perfox.ai/api/v1/templates?number=%2B919876500001" \
-H "Authorization: Bearer sk_…"Templates belong to a WhatsApp Business Account, not to a number — every number on a business account shares its templates, and one provider account can hold several business accounts. So each template can carry waba_id (its business account) and numbers (the numbers that can send it).
- Any usual spelling of the number works —
+919876500001,919876500001and+91 98765 00001all match (encode+as%2Bin a URL). If a number you expect does not match, sync once: older stored templates are rewritten to one standard form. - A template with no
numbershas no known sending number, so a number filter leaves it out rather than guessing. Sending it from a number it is not on is rejected by WhatsApp after the send is accepted.
When to sync
The values a template takes — its body, placeholder count, header and buttons — are fixed when it is approved, so the copy you read stays right for them. Its status can change on the provider's side at any time: a template you hold as pending may since have been approved, or an approved one paused. Sync before you act on a status, and check synced_at to decide how fresh is fresh enough.
synced_at: null means your workspace has never synced — that is not the same as having no templates. An empty templates list with a timestamp means your providers reported none.
What a sync returns
json
{
"synced": 3,
"changed": 1,
"absent": 0,
"errors": [
{
"provider": "plivo",
"message": "Plivo has no WABA ID on this connection — add it at /credentials (Plivo console → WhatsApp → Business Account) to manage approved templates. Sending a template by name works without it."
}
]
}| Field | Meaning |
|---|---|
synced | Templates recorded from the providers that answered |
changed | Templates whose status or values changed since the last sync — for example one that was approved in between |
absent | Templates your providers no longer report. They are marked, not deleted |
errors | One entry per connection that could not be asked |
errors is part of a successful sync: a connection that could not be asked — a Plivo connection without its WhatsApp Business Account ID, or an expired Meta token — is named, and the templates from the providers that did answer are still recorded.
Sync needs conversations:write, because it calls your providers on your behalf; a read-only key can list but not sync. Sending a template by name works either way — it needs no listing or sync first.
Sending media
The provider fetches the bytes from your URL — you are not uploading to us.
The URL must outlive the send
It has to be publicly reachable and stay reachable until the provider has fetched it. A signed link that expires in thirty seconds is the usual cause of a media message that reports sent and never arrives.
Image
bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/messages" \
-H "Authorization: Bearer sk_…" \
-H "Content-Type: application/json" \
-d '{
"from": "+918000000001",
"to": "+919876543210",
"media": {
"type": "image",
"url": "https://cdn.example.com/orders/4182/label.jpg",
"caption": "Your shipping label for order #4182"
}
}'Document
filename is what the recipient sees in their chat — without it they get document.
bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/messages" \
-H "Authorization: Bearer sk_…" \
-H "Content-Type: application/json" \
-d '{
"from": "+918000000001",
"to": "+919876543210",
"media": {
"type": "document",
"url": "https://cdn.example.com/invoices/INV-4182.pdf",
"filename": "INV-4182.pdf",
"caption": "Invoice for order #4182"
}
}'Video
bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/messages" \
-H "Authorization: Bearer sk_…" \
-H "Content-Type: application/json" \
-d '{
"from": "+918000000001",
"to": "+919876543210",
"media": {
"type": "video",
"url": "https://cdn.example.com/how-to/unboxing.mp4",
"caption": "How to set it up in 60 seconds"
}
}'Audio
bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/messages" \
-H "Authorization: Bearer sk_…" \
-H "Content-Type: application/json" \
-d '{
"from": "+918000000001",
"to": "+919876543210",
"media": { "type": "audio", "url": "https://cdn.example.com/voice/reminder.ogg" }
}'Audio takes no caption
WhatsApp has no caption field for audio. Rather than letting the same request behave differently depending on which provider carries it, the API refuses caption on audio — send the words as a separate text message.
Location
bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/messages" \
-H "Authorization: Bearer sk_…" \
-H "Content-Type: application/json" \
-d '{
"from": "+918000000001",
"to": "+919876543210",
"location": {
"latitude": 12.9716,
"longitude": 77.5946,
"name": "Acme Service Centre",
"address": "MG Road, Bengaluru"
}
}'What each type accepts
type | caption | filename | Notes |
|---|---|---|---|
image | yes | — | jpg / png |
video | yes | — | mp4 |
document | yes | yes | any file; filename is what the recipient sees |
audio | no | — | ogg / mp3 / m4a; refused with a caption |
filename on anything but a document is refused too — the recipient would never see it, so accepting it would be a silent no-op.
Your agents can send media too
The same types are available to an AI agent through its send_whatsapp action — it shares one builder with this API, so what this API can send, an agent can send. An agent must pass a media_url it got from a prior tool result; it is instructed never to invent one.
Formats and size limits are WhatsApp's
Perfox passes your URL to the provider; the codec, container and size rules are Meta's and can change. If a message is accepted here but never delivered, check Meta's supported media types first — a failed delivery status with the provider's reason will also appear on GET /api/v1/messages/{id} and on your message.status webhook.
Following delivery
GET /api/v1/messages/{id} returns the message as sent and where it has got to:
| Field | Meaning |
|---|---|
id, conversation_id, customer_id, agent_id | Who and where |
channel, from, to | The route it took |
kind | text, template, image, audio, video, document or location |
text | What was sent; template_name is added for a template |
status | sent, delivered, read or failed |
status_history | Every transition, each with status, at and — on a failure — error |
error | The provider's reason, when it failed |
provider_message_id | The carrier's id |
created_at / updated_at | Timestamps |
GET /api/v1/messages lists the messages you sent, newest first, as { "messages": [...], "next_cursor" }.
| Parameter | Meaning |
|---|---|
to, from, status | Exact-match filters |
since / until | ISO timestamps — since inclusive, until exclusive |
limit | 1–200, default 50 |
cursor | The next_cursor from the previous page |
The cursor is a position rather than an offset, so messages sent while you page are never skipped.
Receiving
bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/webhook-subscriptions" \
-H "Authorization: Bearer sk_…" \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourapp.example.com/hooks/perfox",
"events": ["message.inbound", "message.status"]
}'json
{
"id": "01a0…",
"url": "https://yourapp.example.com/hooks/perfox",
"events": ["message.inbound", "message.status"],
"status": "active",
"consecutive_failures": 0,
"secret": "whsec_71d948cfc2753fe0…"
}The secret is shown exactly once
Store it now. It is encrypted at rest and there is no endpoint that reads it back — we sign with it, so it cannot be kept as a hash, and a "show me my secret" route would turn one leaked API key into every subscriber's signing key. Lost it? PATCH the subscription with "rotate_secret": true.
Managing a subscription
PATCH /api/v1/webhook-subscriptions/{id} changes any of:
| Field | Values |
|---|---|
url | A new https endpoint — checked the same way as at creation |
events | message.inbound, message.status, or both |
status | active to re-enable (this also clears the failure counter), disabled to pause it yourself |
rotate_secret | true mints a new signing secret, returned once in this response; the old one stops signing immediately |
DELETE /api/v1/webhook-subscriptions/{id} removes the endpoint and returns 204 with no body.
The two events
message.inbound — a customer wrote to you on WhatsApp.
json
{
"id": "01a0d837-782b-770e-b63c-50168bf9c6c6",
"event": "message.inbound",
"created_at": "2026-09-25T10:58:29.035Z",
"data": {
"message_id": "b7e1…",
"channel": "whatsapp",
"from": "+919876543210",
"to": "+918000000001",
"text": "where is my order?",
"profile_name": "Asha",
"received_at": "2026-09-25T10:58:29.033Z"
}
}An image, audio, document or voice note adds a media array. If the vendor would not release the bytes, media_error says so in words rather than leaving an empty attachment — a silent empty attachment is indistinguishable from a message that had none.
message.status — a message you sent changed delivery state (sent, delivered, read or failed; a failure adds error with the provider's reason).
json
{
"id": "01a0…",
"event": "message.status",
"created_at": "2026-09-25T10:59:02.114Z",
"data": {
"message_id": "b7e1…",
"channel": "whatsapp",
"status": "delivered",
"conversation_id": "01a0…",
"occurred_at": "2026-09-25T10:59:02.003Z"
}
}message_id is derived the same way on both events, so you can correlate an inbound message with the delivery updates for your reply.
It is a listener, not a mode
An inbound message reaches your endpoint whether or not an agent also answers it. Subscribing changes nothing about the agent path, and running an agent changes nothing about the webhook — so a number with no agent behind it still reaches you, and a number with one reaches you and gets answered.
Verifying the signature
Every delivery carries:
| Header | Meaning |
|---|---|
X-Perfox-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256> |
X-Perfox-Event | message.inbound, message.status, or webhook.test |
X-Perfox-Delivery | Idempotency key — the same value on every retry |
v1 is HMAC-SHA256 of <t>.<raw body> keyed with your subscription secret.
js
import crypto from 'node:crypto'
// Give yourself the RAW body: express.raw({ type: 'application/json' })
export function verify(raw_body, header, secret) {
const parts = new Map(header.split(',').map((kv) => {
const i = kv.indexOf('=')
return [kv.slice(0, i), kv.slice(i + 1)]
}))
const t = Number(parts.get('t'))
const v1 = parts.get('v1') ?? ''
if (!Number.isFinite(t) || !v1) return false
// Reject a replay — and a future timestamp too, or anything signed "next year"
// can be held and replayed whenever the attacker likes.
if (Math.abs(Math.floor(Date.now() / 1000) - t) > 300) return false
const expected = crypto.createHmac('sha256', secret).update(`${t}.${raw_body}`).digest('hex')
if (expected.length !== v1.length) return false // timingSafeEqual throws on unequal lengths
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
}Verify the raw bytes, before parsing
The signature covers exactly what we sent. Parsing the JSON and re-serialising it changes key order, whitespace and unicode escaping — the result will not match, and the mismatch is very hard to explain from the outside. Keep the raw body, verify, then parse.
The timestamp is inside the signed string rather than beside it. That is what lets you reject a captured delivery by age: a replay older than the five-minute tolerance is refused, and changing the timestamp to make it look fresh invalidates the signature.
Compare in constant time. A plain === on the hex digest leaks the correct signature one byte at a time to anyone who can measure how long your endpoint takes to answer.
Testing your endpoint
bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/webhook-subscriptions/01a0…/test" \
-H "Authorization: Bearer sk_…"json
{ "delivered": true, "status": 200 }The report is synchronous: it tells you the status code your endpoint actually returned, or the transport error if it never answered. The delivery itself is byte-identical in shape to a real one — same envelope, same headers, same signature — and carries the event webhook.test, which cannot be subscribed to and is never emitted for real traffic. A test that differed from live traffic would prove nothing about the integration it exists to de-risk.
When delivery fails
| What happens | Detail |
|---|---|
| Non-2xx or a transport error | Retried with exponential backoff — 6 attempts in all, over about half a minute |
| Attempts exhausted | Recorded as a failed delivery with its full payload |
| 20 consecutive failures | The subscription is disabled, with the reason recorded |
| Any success | The failure counter resets to zero |
GET /api/v1/webhook-subscriptions reports consecutive_failures, last_error, last_failed_at, last_delivered_at and disabled_reason, so a subscriber that has quietly stopped working is visible without reading logs. Re-enable one with PATCH … {"status": "active"}.
Retries carry the same X-Perfox-Delivery
Key your idempotency check on that header. A subscriber that processed attempt one and then timed out can discard attempt two instead of handling the message twice.
URLs we will not accept
Registration is refused — not the first delivery — when a URL is not https, or when its host resolves to a private, loopback or link-local address. The check repeats on every redirect hop, so a URL that redirects inward cannot be used to reach inside the platform.
https is required because a delivery carries the text of your customers' messages. The signature proves who sent a payload; it does nothing about who can read it in transit.
You can now …
- Send WhatsApp messages you wrote yourself, on your own number, through
POST /api/v1/messages - Send an image, video, document, audio clip or map pin by URL — no upload step
- Receive every inbound message and delivery update on your own endpoint, signed and retried
- Verify a delivery, reject a replay, and dedupe a retry
- See at a glance when a subscriber has stopped accepting deliveries, and re-enable it once fixed