Messaging
Send WhatsApp templates, replies, media, interactive messages and reactions from your servers, and hear about every delivery, read and reply.
Every WhatsApp message goes out through POST /v1/messages: leave channel out (or set it to whatsapp). The API answers 202 with the message queued; what happens next arrives as message.* events, or through GET /v1/messages/{messageId}. Trovacast holds the Meta tokens — your server never sees one.
Templates and the 24-hour window
WhatsApp decides what you may send by the customer service window: 24 hours that open, and reset, with each message the customer sends you. A reaction from the customer keeps it open too.
| `type` | When it may be sent |
|---|---|
template | Any time, subject to consent. An approved template and its variables. |
text | Only inside the window (1–4,000 characters). Outside it, or when the customer never wrote: 409 MESSAGING_WINDOW_CLOSED. |
media | Only inside the window: an image, video, audio file or document by https link, or by the id of a file you uploaded. |
interactive | Only inside the window: reply buttons, a list, a link button (cta_url) or a WhatsApp Flow. |
location | Only inside the window: a pin on the map. |
contacts | Only inside the window: 1–20 contact cards. |
reaction | Only inside the window: one emoji on a message of the conversation. |
Choose the recipient
- Give exactly one of
contactId,to: { phone }(international format) orconversationId. A reaction may give none: it goes on the conversation of the message it reacts to. - A send by phone uses the contact with that number, or creates it, so it also needs
contacts:write— always,403 API_KEY_SCOPE_MISSINGotherwise. - **Every refusal after the recipient is known carries
contactId** in the error body, so a send by number that created the contact and was then refused tells you which contact to record consent for before you retry.
{
"statusCode": 409,
"code": "CONSENT_REQUIRED",
"contactId": "…",
"message": "…",
"requestId": "…"
}Send a template
Name the template by { id } or by { name, language }, and fill variables with exactly the template’s variable names (var1… or named parameters, header_*, button{i}_var1, button{i}_code) — a missing or unknown name is a 400. quickReplies sets the payload WhatsApp echoes back when the customer taps a quick-reply button: index is the button’s 0-based position among the template’s buttons, the payload 1–256 printable characters.
curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: order-1001-cod-verification' \
-H 'Content-Type: application/json' \
-d '{
"type": "template",
"contactId": "CONTACT_ID",
"template": {
"name": "cod_verification",
"language": "en"
},
"variables": {
"var1": "#1001"
},
"quickReplies": [
{
"index": 0,
"payload": "COD_CONFIRM:1001"
},
{
"index": 1,
"payload": "COD_CANCEL:1001"
}
],
"metadata": {
"orderId": "1001"
}
}'Template values are checked against Meta’s parameter rules before anything is queued — 400 VALIDATION_FAILED, naming the variable — instead of Meta accepting the send and failing it minutes later:
- A text value (header or body) has no line break or tab and no run of more than four spaces.
- The header as rendered stays within 60 characters, the body within 1,024.
- A URL button’s value has no whitespace, and the link it completes stays within 2,000 characters.
- A copy code (and an authentication template’s one-time code) is at most 15 characters, without spaces.
- A media header is an
httpslink.
metadata — at most 20 keys of 1–40 A-Za-z0-9_.-, values up to 500 characters — is stored on the message and echoed on it and on its webhooks. It is stored unencrypted: never put personal data in it.
Reply inside the window
To answer a customer, send on their conversation: conversationId is on every message.received. The message goes to that conversation’s contact, from the number the customer wrote to. replyToMessageId (on text, media and interactive) quotes a message of the same conversation — one the customer sent, or one of yours already sent — and the reply carries it as context.
curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: reply-1001-shipping' \
-H 'Content-Type: application/json' \
-d '{
"type": "text",
"conversationId": "CONVERSATION_ID",
"text": "Thanks — your order #1001 ships tomorrow.",
"replyToMessageId": "MESSAGE_ID"
}'A quoted message from another conversation, or one WhatsApp has no id for yet (still queued, or failed), is 409 REPLY_TARGET_UNAVAILABLE; an unknown id is 404 REPLY_TARGET_NOT_FOUND.
Media
media: { url, caption?, fileName? }. The url is an https link on a public host: it is fetched once, when the message is accepted (no redirects followed, 20 seconds to answer), checked and stored, and WhatsApp is sent Trovacast’s copy. The file is fetched only after every other check has passed, so a refused send fetches nothing.
- A JPEG or PNG image (up to 5 MB); an MP4 or 3GP video, or AAC, AMR, MP3, M4A or OGG audio (up to 16 MB); a PDF, Word, Excel, PowerPoint or plain-text document (up to 16 MB). The bytes must be what the type claims.
caption(up to 1,024 characters) shows under an image, video or document — audio carries none.fileNameis a document’s name as the customer sees it (default: the link’s last path segment).- Refusals:
400 MEDIA_URL_REFUSED,422 MEDIA_FETCH_FAILED,413 MEDIA_TOO_LARGE,415 MEDIA_TYPE_UNSUPPORTED,422 MEDIA_CONTENT_MISMATCH, and503 MEDIA_NOT_ENABLEDon a deployment that keeps no media.
curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: invoice-1001' \
-H 'Content-Type: application/json' \
-d '{
"type": "media",
"conversationId": "CONVERSATION_ID",
"media": {
"url": "https://cdn.shop.test/invoices/1001.pdf",
"fileName": "invoice-1001.pdf",
"caption": "Your invoice for order #1001"
}
}'Upload once, send by id
When the file is not on a public link, upload it: POST /v1/media (multipart/form-data, the file in file, an optional fileName; scope messages:write). It is checked once like a link’s file — a type WhatsApp delivers, bytes that are what the type says, the type’s size cap — stored encrypted under your project, and answered with its id and expiresAt (7 days). Send media: { id, caption? } any number of times before then; each send keeps its own copy, so DELETE /v1/media/{mediaId} or the expiry never touches what was sent. A test key’s uploads are its own: another mode’s id, or an expired one, is 404 MEDIA_NOT_FOUND.
curl https://api.trovacast.com/v1/media \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: invoice-1001-upload" \
-F "file=@invoice-1001.pdf;type=application/pdf"
# Node.js: const form = new FormData();
# form.append('file', new Blob([bytes], { type: 'application/pdf' }), 'invoice-1001.pdf');
# const media = await client.uploadMedia({ body: form });
# Python: media = client.upload_media(body=FileUpload(data, "invoice-1001.pdf", "application/pdf"))curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: invoice-1001-upload' \
-H 'Content-Type: application/json' \
-d '{
"type": "media",
"conversationId": "CONVERSATION_ID",
"media": {
"id": "MEDIA_ID",
"caption": "Your invoice for order #1001"
}
}'Interactive messages
Reply buttons — interactive: { type: "button", body, header?, footer?, buttons: [{ id, title }] }, 1–3 buttons — or a list — interactive: { type: "list", body, header?, footer?, button, sections: [{ title?, rows: [{ id, title, description? }] }] }, 1–10 sections (titled when more than one), at most 10 rows in all. When the customer taps, message.received carries button: { text, payload } with the id you set: that is how you attribute the answer.
| Field | Limit |
|---|---|
body | 1,024 characters |
header, footer | 60 characters, one line |
Button id / title | 256 / 20 characters; ids unique, titles unique |
List button | 20 characters |
Section title | 24 characters |
Row id / title / description | 200 / 24 / 72 characters |
curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: order-1001-cod-buttons' \
-H 'Content-Type: application/json' \
-d '{
"type": "interactive",
"conversationId": "CONVERSATION_ID",
"interactive": {
"type": "button",
"body": "Please confirm your cash-on-delivery order #1001.",
"buttons": [
{
"id": "COD_CONFIRM:1001",
"title": "Confirm"
},
{
"id": "COD_CANCEL:1001",
"title": "Cancel"
}
]
}
}'- A link button —
interactive: { type: "cta_url", body, header?, footer?, action: { displayText, url } }:displayTextup to 20 characters,urlanhttpslink (no credentials, up to 2,000 characters). Nothing comes back when it is tapped. - A WhatsApp Flow —
interactive: { type: "flow", body, header?, footer?, flow: { id, cta, token?, action?, screen?, data?, mode? } }:idis the Flow’s,ctathe button (up to 20 characters),token(up to 200) comes back with the customer’s answers;actionisnavigate(the default: opensscreen, withdataup to 4 KB of JSON) ordata_exchange(asks the Flow’s endpoint);mode: "draft"tests an unpublished Flow.
curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: order-1001-slot-flow' \
-H 'Content-Type: application/json' \
-d '{
"type": "interactive",
"conversationId": "CONVERSATION_ID",
"interactive": {
"type": "flow",
"body": "Book your delivery slot for order #1001.",
"flow": {
"id": "1234567890123456",
"cta": "Book a slot",
"token": "order-1001",
"action": "navigate",
"screen": "SLOTS",
"data": {
"orderId": "1001"
}
}
}
}'Locations and contact cards
type: "location" with location: { latitude, longitude, name?, address? } (degrees; a name up to 256 characters, an address up to 512) sends a pin. type: "contacts" with contacts: [{ name, phones?: [{ phone, type? }], emails?: [{ email, type? }], organization? }] sends 1–20 cards — WhatsApp shows each by its name, and a card carries up to 10 phones and 10 emails. A card is someone’s personal data: it is stored encrypted, like a text.
curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: order-1001-store-location' \
-H 'Content-Type: application/json' \
-d '{
"type": "location",
"conversationId": "CONVERSATION_ID",
"location": {
"latitude": 19.076,
"longitude": 72.8777,
"name": "Acme Store, Bandra",
"address": "12 Hill Road, Mumbai 400050"
}
}'Reactions
reaction: { messageId, emoji } puts one emoji on a message of the conversation — one the customer sent, or one of yours already sent. Anything but exactly one emoji (skin tones, flags and joined sequences count as one) is a 400. A message of another conversation, one WhatsApp has no id for, one more than 30 days old, or a reaction is 409 REPLY_TARGET_UNAVAILABLE. WhatsApp reports a reaction sent only, never delivered or read, and removing a reaction is not offered.
Which number sends
A project can have several WhatsApp numbers, and each conversation is one contact on one number. A send goes from the default number unless senderId names another — every number’s senderId is listed by GET /v1/whatsapp/account (numbers[].senderId) and shown on each conversation. To answer a customer who wrote to a number that is not the default, send with their conversationId: by contactId alone the message would go from the default number, where that customer opened no window (409 MESSAGING_WINDOW_CLOSED). A senderId that is not the conversation’s number is a 400; a conversation whose number has since been removed is 409 NO_SENDER_AVAILABLE.
A contact known only by a WhatsApp username (no phone number) can be sent text replies and utility or marketing templates, but Meta refuses authentication templates to them: 422 RECIPIENT_PHONE_REQUIRED.
Consent and other checks
Every check the console applies runs before the 202 and again when the message is actually sent: the project’s messaging product, the contact’s state, the template’s approval (409 TEMPLATE_NOT_SENDABLE), the number’s health (409 MESSAGING_SENDER_RESTRICTED, 409 NO_SENDER_AVAILABLE), consent and billing (402 or 503 with a BILLING_* code). A refusal that happens later — or that Meta returns — arrives as message.failed.
| Consent refusal (409) | Meaning |
|---|---|
CONSENT_REQUIRED | No opt-in on file for this kind of message. |
CONSENT_MARKETING_REQUIRED | The contact agreed to updates only; a MARKETING template needs marketing: opted_in. |
CONSENT_OPTED_OUT | The contact opted out of WhatsApp (or, for a marketing template, of marketing). |
CONTACT_OPTED_OUT | The contact opted out of all contact, or asked not to be contacted. |
CONTACT_BLOCKED | The contact is blocked. |
MESSAGING_CONSENT_REQUIRED | A consent refusal not classified above (reserved; treat it like CONSENT_REQUIRED). |
Schedule a send
sendAt — an ISO 8601 instant at least a minute and at most 30 days ahead — schedules any message, on any channel (an email with attachments at most 6 days; never with sms.validitySeconds). It is created queued with scheduledAt. Every rule is checked when you send it, and consent, billing and the 24-hour window (for a WhatsApp reply) again when it goes: a window closed by then fails it as WINDOW_EXPIRED. DELETE /v1/messages/{messageId} cancels it while it waits — it ends failed with MESSAGE_CANCELED, message.failed fires, and nothing is sent or charged. Once its time has come it is 409 MESSAGE_NOT_CANCELABLE.
curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: order-1001-reminder' \
-H 'Content-Type: application/json' \
-d '{
"type": "template",
"contactId": "CONTACT_ID",
"template": {
"name": "delivery_reminder",
"language": "en"
},
"variables": {
"var1": "#1001"
},
"sendAt": "2026-11-06T04:30:00.000Z"
}'To hear about one message without a webhook endpoint for every event, send statusCallback: { url, events? } with it: that message’s message.sent, message.delivered, message.read and message.failed (or the ones you name) are also POSTed to url, signed. See per-request status callbacks.
Exactly once
Send an Idempotency-Key on every attempt — one key per message (a job id is ideal). A retry is answered from the stored response (Idempotent-Replayed: true), and because the message itself is keyed on the same key and request, even a retry that runs again after a failed attempt answers the original message instead of sending a second one. See Idempotency.
On Trovacast’s side a message is never submitted twice: a submission WhatsApp did not confirm (a timeout or reset after the request left, a 5xx, an answer without a message id) fails at once as SUBMISSION_UNKNOWN — it may or may not have been delivered. On WhatsApp this resolves itself: every send carries Trovacast’s message id to Meta, and if Meta did accept it, its first status turns the message from failed to sent, delivered or read (followed by the matching event), and it is billed then.
The message
The same object answers the send, GET /v1/messages/{messageId} and every message.* webhook. Outbound status moves queued → sending → sent → delivered → read, or ends failed with failure: { code, reason } — a stable code and a sentence you can show a merchant. Inbound messages are received; a tapped quick reply, reply button or list row carries button: { text, payload }, and the message it answered is context.
{
"object": "message",
"id": "6f1d2c3b-8a4e-4f5a-9b7c-1d2e3f4a5b6c",
"conversationId": "0c9b8a7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
"contactId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
"channel": "whatsapp",
"direction": "outbound",
"type": "template",
"status": "queued",
"template": {
"id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"name": "cod_verification",
"language": "en"
},
"button": null,
"context": null,
"metadata": {
"orderId": "1001"
},
"failure": null,
"email": null,
"sms": null,
"media": null,
"providerMessageId": null,
"createdAt": "2026-11-05T10:00:00.000Z",
"updatedAt": "2026-11-05T10:00:00.000Z",
"sentAt": null,
"deliveredAt": null,
"readAt": null,
"failedAt": null
}What customers send
Inbound type is WhatsApp’s own (text, button, interactive, image, …). Beyond text, taps and files, what a customer sends keeps its content in a block of its own, null on every other message; text holds a one-line summary.
| `type` | Block |
|---|---|
reaction | reaction: { emoji } — emoji is null when the customer removed it; the message reacted to is context. A reaction keeps the window open but is never read as consent, a STOP or a START. |
location | location: { latitude, longitude, name, address, url } |
contacts | contacts: [{ name, phones, emails, organization }] — someone else’s personal data the customer chose to share: handle it under your own privacy rules. |
order | order: { catalogId, text, items: [{ productRetailerId, quantity, itemPrice, currency }] } |
Failure codes
failure.code on a failed message (and its message.failed) comes with a failure.reason sentence. The common ones:
| Code | When |
|---|---|
META_<code> | Meta refused or failed the message: META_131047 window closed, META_131049 frequency cap, META_131050 the customer stopped marketing, META_131026 undeliverable, and others. |
CONSENT_REVOKED | The contact (or the channel) was opted out after the message was queued. |
WINDOW_EXPIRED | The 24-hour window closed before a free-form message went out. |
TEMPLATE_NOT_SENDABLE, TEMPLATE_DELETED, TEMPLATE_MISSING | The template was paused, disabled or deleted after the message was queued. |
CHANNEL_NOT_CONFIGURED, NO_SENDER_AVAILABLE | The account was disconnected, or the number left it, before the send. Nothing was sent. |
RATE_LIMITED, TRANSPORT_UNAVAILABLE, SEND_ABANDONED | Nothing was sent; safe to send again. |
SUBMISSION_UNKNOWN | WhatsApp never confirmed the submission; it may have been delivered and was not sent again (see Exactly once). |
Read receipts
POST /v1/messages/{messageId}/read tells the customer you read their message (WhatsApp’s blue ticks; WhatsApp also marks every earlier message in the chat read) and answers the message. Only an inbound WhatsApp message from the last 30 days qualifies: 409 MESSAGE_NOT_INBOUND, 409 READ_RECEIPT_UNSUPPORTED, 409 READ_RECEIPT_EXPIRED or 409 WHATSAPP_NOT_CONNECTED otherwise. Meta’s own answers are 502 META_<code>, 429 MESSAGING_RATE_LIMITED, 503 MESSAGING_TRANSPORT and 504 MESSAGING_PROVIDER_UNCONFIRMED. A receipt creates nothing, so each is safe to retry with the same Idempotency-Key.
curl -X POST 'https://api.trovacast.com/v1/messages/MESSAGE_ID/read' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"Files customers send
Every media message carries a media block — never a link — with kind, mimeType, fileName, sizeBytes and status: pending (still being fetched from WhatsApp — message.received always shows this), ready, failed or rejected (a type or size not kept), with failureCode on the last two. A received file settles exactly once and says so with message.media.ready or message.media.failed: subscribe to those rather than polling.
GET /v1/messages/{messageId}/media then issues a short-lived download link. The link is a credential while it lives: the answer is never cached, every link issued is audited under your key, and the message resource never embeds one. 404 MEDIA_NOT_FOUND means the message carries no file; 409 MEDIA_NOT_AVAILABLE that it is still being fetched (retry shortly) or never will be.
curl 'https://api.trovacast.com/v1/messages/MESSAGE_ID/media' \
-H "Authorization: Bearer $TROVACAST_API_KEY"Find and reconcile messages
GET /v1/messages filters by channel, contactId, conversationId, direction, status and metadata, newest first. metadata=key:value matches messages whose metadata holds that key with exactly that value (the first : splits; URL-encode the value); repeat it for up to 5 pairs, all of which must match.
curl 'https://api.trovacast.com/v1/messages?metadata=runId%3Arun_42&metadata=step%3A1' \
-H "Authorization: Bearer $TROVACAST_API_KEY"Missed webhooks? GET /v1/messages?updatedAfter=<ISO 8601> returns every message changed at or after that instant, oldest change first. Page until nextCursor is null, remember the largest updatedAt you saw, and next time ask from there, deduplicating by id and updatedAt (the boundary is inclusive on purpose). Changes from the last 2 minutes are held back so the read never skips one that commits late — webhooks remain the real-time path. See Pagination.
Your WhatsApp account
GET /v1/whatsapp/account (whatsapp:read) answers the connection — the same shape whatsapp.account.updated carries. status is not_connected, connected, needs_attention (a token invalid or expiring, a number restricted, or quality RED) or disconnected (access removed by the business or Meta). numbers[] lists each number with its senderId, quality rating, messaging tier and whether it is the default. Connecting is done through a hosted connect session, never by passing a token. POST /v1/whatsapp/account/disconnect (whatsapp:manage) removes the connection and its numbers; it is idempotent.
Endpoints
- POST
/v1/messagesSends a message: a WhatsApp template, text, media file or interactive message (or an email or SMS) - GET
/v1/messages/{messageId}Retrieves a message - GET
/v1/messagesLists messages newest first, or — with updatedAfter — every change since, oldest first - POST
/v1/messages/{messageId}/readSends WhatsApp’s read receipt (blue ticks) for a message the contact sent - GET
/v1/messages/{messageId}/mediaIssues a short-lived download link for a message’s stored media - DELETE
/v1/messages/{messageId}Cancels a scheduled message before it is sent - POST
/v1/mediaUploads a file to send by id on a WhatsApp media message - GET
/v1/media/{mediaId}Retrieves an upload (never its bytes) - DELETE
/v1/media/{mediaId}Deletes an upload now (what was sent with it stays) - GET
/v1/whatsapp/accountThe WhatsApp connection: status, numbers, display-name review, quality, messaging limit and billing currency - POST
/v1/whatsapp/account/disconnectDisconnects the WhatsApp account (idempotent); sending stops until it is connected again
Events
| Event | When it is sent | Key scopes |
|---|---|---|
message.sent | The provider accepted a message you sent. WhatsApp (Meta), Amazon SES or the SMTP relay, or the SMS vendor accepted an outbound message. message.status is sent.data: message | messages:read |
message.delivered | A message reached the contact. The provider reported the message delivered to the contact’s phone or mailbox (for SMS: the vendor’s delivery receipt).data: message | messages:read |
message.read | The contact read a message. Meta reported the WhatsApp message read.data: message | messages:read |
message.failed | A message failed for good. message.failure carries { code, reason }. A scheduled message cancelled before it was sent fails with MESSAGE_CANCELED.data: message | messages:read |
message.received | A contact sent a message or tapped a reply button. An inbound message, with button for a tapped reply and context.messageId for a reply to one of yours. contact is the sender (needs contacts:read too).data: contact, message | messages:readcontacts:read |
message.complained | A recipient reported an email you sent as spam. The message’s status does not change (it was delivered); the address is suppressed and the contact’s email consent opted out, which its own contact.consent.updated reports.data: complaint, message | messages:read |
whatsapp.account.updated | The WhatsApp account changed. WhatsApp was connected or disconnected, or its credential, quality rating, display name, messaging limit or restriction changed.data: account, change | whatsapp:read |
message.media.ready | A file a contact sent is stored. message.media.status is ready: fetch a download link with GET /v1/messages/{messageId}/media. No link rides on the event.data: message | messages:read |
message.media.failed | A file a contact sent could not be stored. message.media.status is failed or rejected, with message.media.failureCode.data: message | messages:read |
Errors
| Code | Status | Meaning and what to do |
|---|---|---|
BILLING_INSUFFICIENT_CREDIT | 402 | The prepaid wallet, after any included plan minutes, cannot cover the messages at your plan's rate — or a call's ceiling: its maxDurationSec in started minutes, beside what your live API calls already in flight can still run to (inFlightMinutes), each at its own rate.What to do: Top up the prepaid balance (POST /v1/balance/top-ups, or Add credit in Settings → Billing), then retry. When the refusal carries maxDurationSecAvailable, a call with a maxDurationSec up to it is placed now; without it no shorter call fits — retry once a call in progress ends. See Limits and billing. |
BILLING_RATE_UNAVAILABLE | 503 | Your plan has no rate for this channel and mode (or message category) — a configuration gap on our side, not a debt.What to do: Retrying will not help until the plan prices it: contact us. GET /v1/pricing shows the rates your plan has. |
BILLING_SUBSCRIPTION_CANCELED | 402 | The subscription was cancelled at a period end.What to do: A project administrator chooses a plan in Settings → Billing, which reactivates the subscription; then retry. |
BILLING_SUBSCRIPTION_PAST_DUE | 402 | The monthly fee is unpaid: it left the wallet negative.What to do: Top up enough to bring the balance back to zero or above (POST /v1/balance/top-ups): the subscription reactivates by itself, then retry. |
BILLING_SUBSCRIPTION_SUSPENDED | 402 | The subscription is blocked by the platform.What to do: Retrying will not help until the hold is lifted: contact us. |
CONSENT_MARKETING_REQUIRED | 409 | A marketing message to a contact who agreed to updates (transactional or utility messages) only: it needs marketing: opted_in on the channel. See Consent.What to do: Send a non-marketing message instead — a utility template, a transactional email, a service SMS — or record the contact's marketing opt-in once they give it (PUT /v1/contacts/{contactId}/consent/{channel}). |
CONSENT_OPTED_OUT | 409 | The contact opted out on this channel — or, for a marketing message, out of marketing — whether you recorded it or they did (STOP, an unsubscribe, a spam report).What to do: Do not retry. After a marketing opt-out a transactional or utility message may still go; only a new opt-in reopens the channel — theirs, if they opted out themselves. See What a send needs. |
CONSENT_REQUIRED | 409 | No opt-in on file for this kind of message on this channel.What to do: Record the contact's consent with PUT /v1/contacts/{contactId}/consent/{channel} once you have collected it (a WhatsApp or email refusal carries the contactId), then send again. See Record a decision. |
CONTACT_BLOCKED | 409 | The contact is blocked, so nothing is sent to them.What to do: Do not retry: nothing reaches a blocked contact, on any channel. |
CONTACT_NOT_FOUND | 404 | The contactId a request named is not a contact of this organization, or was erased. Like every 404, another organization's id reads the same.What to do: Check the id (GET /v1/contacts?phone= finds a contact by number), or send by to.phone or to.email to use or create the contact; an erased contact never comes back. |
CONTACT_OPTED_OUT | 409 | On a send, the contact opted out of all contact or asked not to be contacted — it outranks every channel's consent. On a call, they opted out of calls themselves.What to do: Do not retry, and do not reach them another way. If the contact asks to hear from you again, a project member changes their state in the console. |
CONVERSATION_NOT_FOUND | 404 | The conversationId of a send, or of a conversation read, names no conversation this key can see — another project’s, or one of the other mode: a test thread (the sandbox’s, or a test contact’s) to a live key, a live customer’s to a test key.What to do: Check the id against GET /v1/conversations (or the conversationId of the customer’s message.received) with a key of the same mode, or send by contactId instead. |
ENTITLEMENT_MESSAGING_DISABLED | 403 | Messaging is not enabled for this project (it is calling-only). GET /v1/me shows the project's entitlements.What to do: A project cannot turn messaging on itself: the platform, or the partner that manages the project, enables it. Contact us; retrying will not help until then. |
MEDIA_CONTENT_MISMATCH | 422 | The file’s bytes are not the type the link claims.What to do: Serve the file with the Content-Type its bytes really are, or convert it to the type you declare. |
MEDIA_FETCH_FAILED | 422 | media.url did not answer with a file — no answer, a non-2xx status, a redirect or an empty file (reason; upstreamStatus for a non-2xx).What to do: Make the link answer 2xx with the file itself within 20 seconds — redirects are not followed — or upload it with POST /v1/media and send media.id. |
MEDIA_NOT_AVAILABLE | 409 | The file is still being fetched from WhatsApp (mediaStatus: "PENDING") or never will be (mediaStatus and failureCode say why).What to do: While mediaStatus is PENDING, retry shortly or wait for message.media.ready; otherwise do not retry — the file will not arrive. |
MEDIA_NOT_ENABLED | 503 | This deployment keeps no media, so files can be neither sent nor downloaded.What to do: Retrying will not help: send text or a template instead, or contact us. |
MEDIA_NOT_FOUND | 404 | GET /v1/messages/{messageId}/media on a message that carries no file; or a /v1/media upload id that is unknown, expired, deleted or another mode’s (a test key never sees a live upload).What to do: Check that the message carries a file (media on GET /v1/messages/{messageId}); for an upload, upload the file again with POST /v1/media (an id lasts 7 days) using a key of the same mode. |
MEDIA_TOO_LARGE | 413 | The linked file is over its type’s cap (5 MB for an image, 16 MB otherwise).What to do: Send a smaller or compressed file, under its type’s cap. The same file fails the same way. |
MEDIA_TYPE_UNSUPPORTED | 415 | The link serves a type WhatsApp does not deliver.What to do: Convert the file to a type WhatsApp delivers — see Media — and send it again. |
MEDIA_URL_REFUSED | 400 | media.url is not https on a public host; reason says why.What to do: Link the file over https on a public host, or upload it with POST /v1/media and send it by media.id. See Upload once, send by id. |
MESSAGE_NOT_CANCELABLE | 409 | DELETE /v1/messages/{messageId} on a message that is not a scheduled one still waiting for its sendAt — it is already being sent, sent, failed or canceled.What to do: Read the message (GET /v1/messages/{messageId}) to see where it is; a message on its way cannot be called back. |
MESSAGE_NOT_INBOUND | 409 | Only a message the contact sent can be marked read.What to do: Mark read only messages with direction: "inbound"; do not retry this one. |
MESSAGING_CONSENT_REQUIRED | 409 | A consent refusal not classified under a more specific consent code (reserved). Treat it like CONSENT_REQUIRED.What to do: Record the contact’s opt-in first (PUT /v1/contacts/{contactId}/consent/{channel}, once you have collected it), then send again. |
MESSAGING_PROVIDER_UNCONFIRMED | 504 | Meta timed out or failed (5xx) after a read receipt left.What to do: Send the read receipt again with backoff: a receipt creates nothing, so it is safe to repeat. |
MESSAGING_RATE_LIMITED | 429 | Meta is throttling — on template work or a read receipt.What to do: Retry after the retryAfterMs hint, backing off exponentially if it repeats. |
MESSAGING_SENDER_RESTRICTED | 409 | The sending WhatsApp number is restricted, disabled or quality-flagged; the SMS header is not active; or the email account is switched off in the console.What to do: Send from another sender (senderId; GET /v1/whatsapp/account shows each number’s status and qualityRating, GET /v1/sms/senders each header’s), or switch the email account back on in Settings → Channels → Email. A header becomes usable once the platform activates it. |
MESSAGING_TRANSPORT | 503 | The provider (Meta, the mail service or the SMS service) was never reached, or the SMS settings could not be read: nothing left Trovacast.What to do: Retry with backoff and the same Idempotency-Key: nothing was sent, so the key is released and the retry runs again. See Errors that changed nothing. |
MESSAGING_WINDOW_CLOSED | 409 | A WhatsApp text, media, interactive message or reaction outside the 24-hour customer service window — or the customer never wrote. See WhatsApp.What to do: Send an approved template instead (type: "template"), or wait for the customer to write. To answer a customer who wrote to another of your numbers, send with their conversationId. |
META_UNAVAILABLE | 503 | Meta could not be reached, or did not answer in time, for template work or the WhatsApp account. Nothing changed here, but a submit or an edit may still have reached Meta.What to do: After a submit or an edit, read the template — or run POST /v1/templates/sync — to see whether it reached Meta before trying again with a new Idempotency-Key (the same key replays this error). A delete, a sync or a read is safe to repeat. |
NO_SENDER_AVAILABLE | 409 | There is nothing to send from: no WhatsApp number (or the conversation’s number was removed), no chosen number that can send, or no active SMS header that fits the template’s category.What to do: Connect a WhatsApp number (Settings → Channels → WhatsApp) or choose one that can send; for SMS, register a header of the kind the category needs — numeric for promotional, alphabetic otherwise — and send once the platform has activated it. |
READ_RECEIPT_EXPIRED | 409 | The message is older than WhatsApp’s 30 days for read receipts.What to do: Do not retry: WhatsApp no longer takes a read receipt for it. Mark messages read within 30 days. |
READ_RECEIPT_UNSUPPORTED | 409 | This message cannot be marked read (it is not an inbound WhatsApp message).What to do: Send read receipts for inbound WhatsApp messages only; do not retry this one. |
RECIPIENT_PHONE_REQUIRED | 422 | The contact has no phone number: an SMS, or a WhatsApp authentication template to a contact known only by WhatsApp username. Also a message.failed code.What to do: Reach this contact on WhatsApp with a text or a utility or marketing template instead. If WhatsApp later shares their number, it lands on the contact by itself and the send works. |
REPLY_TARGET_NOT_FOUND | 404 | replyToMessageId or reaction.messageId names no message this key can see — another project’s, or one of the other mode (a test message to a live key; a live one, or any on a live customer’s thread, to a test key).What to do: Pass Trovacast’s message id (the id from GET /v1/messages), not WhatsApp’s, or send without the quote. |
REPLY_TARGET_UNAVAILABLE | 409 | The quoted (or reacted-to) message belongs to another conversation, or WhatsApp has no id for it yet (still queued, or failed). A reaction’s target may also be over 30 days old, or itself a reaction.What to do: Quote or react to a message of the same conversation once it is sent — retry a still-queued target after message.sent — or send without replyToMessageId. |
SENDER_NOT_FOUND | 404 | A send’s senderId names no WhatsApp number, email sender or SMS header of this project.What to do: Use a senderId from GET /v1/whatsapp/account (numbers[].senderId) or GET /v1/sms/senders, or leave it out to send from the default sender. |
STATUS_CALLBACK_SECRET_MISSING | 409 | A send or call carried a statusCallback before the project had a status-callback signing secret for the key’s mode.What to do: Create the secret once with POST /v1/status-callback-secret (scope webhooks:manage) and store it — it is in that response only — then retry. See Per-request status callbacks. |
TEMPLATE_NOT_FOUND | 404 | No template of this channel matches the id, or the name and language, the request named.What to do: Check the id, or the name and language, against GET /v1/templates for the channel you are sending on — a template belongs to one channel. |
TEMPLATE_NOT_SENDABLE | 409 | The template is not approved — pending review, paused, rejected, disabled or deleted, or an SMS template without its DLT id. Also a message.failed code when it changed after the message was queued.What to do: Send an approved template, or wait for Meta’s verdict (template.updated); give an SMS template its dltTemplateId with PATCH /v1/templates/{templateId}. A message that failed with this code was not sent: send it again once the template is approved. |
WHATSAPP_NOT_CONNECTED | 409 | No connected WhatsApp account — needed to submit, edit, delete or sync templates, to send a read receipt, and to create or resume a broadcast.What to do: Connect a WhatsApp account (or reconnect it in Settings → Channels → WhatsApp), then retry. |
META_<code> | 400 or 502 | META_<code>: Meta refused, under its own code — 400 for template work (the reason in message), 502 for a read receipt. On a failed message, failure.code uses the same family (META_131047, META_131026, …).What to do: For template work, change what Meta refused — message carries its reason — before retrying; a read receipt is safe to send again. For a failed message, see Failure codes. |