Trovacast

Messaging

WhatsApp

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
templateAny time, subject to consent. An approved template and its variables.
textOnly inside the window (1–4,000 characters). Outside it, or when the customer never wrote: 409 MESSAGING_WINDOW_CLOSED.
mediaOnly inside the window: an image, video, audio file or document by https link, or by the id of a file you uploaded.
interactiveOnly inside the window: reply buttons, a list, a link button (cta_url) or a WhatsApp Flow.
locationOnly inside the window: a pin on the map.
contactsOnly inside the window: 1–20 contact cards.
reactionOnly inside the window: one emoji on a message of the conversation.

Choose the recipient

  • Give exactly one of contactId, to: { phone } (international format) or conversationId. 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_MISSING otherwise.
  • **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.
A refusal names the contact (json)
{
  "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.

Send a template with quick replies
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 https link.

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.

Reply with text, quoting the customer’s message
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. fileName is 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, and 503 MEDIA_NOT_ENABLED on a deployment that keeps no media.
Send an invoice
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.

Upload a file (multipart) (text)
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"))
Send an uploaded file
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.

FieldLimit
body1,024 characters
header, footer60 characters, one line
Button id / title256 / 20 characters; ids unique, titles unique
List button20 characters
Section title24 characters
Row id / title / description200 / 24 / 72 characters
Ask with reply buttons
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 } }: displayText up to 20 characters, url an https link (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? } }: id is the Flow’s, cta the button (up to 20 characters), token (up to 200) comes back with the customer’s answers; action is navigate (the default: opens screen, with data up to 4 KB of JSON) or data_exchange (asks the Flow’s endpoint); mode: "draft" tests an unpublished Flow.
Open a WhatsApp 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.

Share the store’s location
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.

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_REQUIREDNo opt-in on file for this kind of message.
CONSENT_MARKETING_REQUIREDThe contact agreed to updates only; a MARKETING template needs marketing: opted_in.
CONSENT_OPTED_OUTThe contact opted out of WhatsApp (or, for a marketing template, of marketing).
CONTACT_OPTED_OUTThe contact opted out of all contact, or asked not to be contacted.
CONTACT_BLOCKEDThe contact is blocked.
MESSAGING_CONSENT_REQUIREDA 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.

Remind the customer tomorrow morning
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.

202 Accepted — the message, queued (json)
{
  "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
reactionreaction: { 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.
locationlocation: { latitude, longitude, name, address, url }
contactscontacts: [{ name, phones, emails, organization }] — someone else’s personal data the customer chose to share: handle it under your own privacy rules.
orderorder: { 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:

CodeWhen
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_REVOKEDThe contact (or the channel) was opted out after the message was queued.
WINDOW_EXPIREDThe 24-hour window closed before a free-form message went out.
TEMPLATE_NOT_SENDABLE, TEMPLATE_DELETED, TEMPLATE_MISSINGThe template was paused, disabled or deleted after the message was queued.
CHANNEL_NOT_CONFIGURED, NO_SENDER_AVAILABLEThe account was disconnected, or the number left it, before the send. Nothing was sent.
RATE_LIMITED, TRANSPORT_UNAVAILABLE, SEND_ABANDONEDNothing was sent; safe to send again.
SUBMISSION_UNKNOWNWhatsApp 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.

Mark a message read
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.

Get a download link for a received file
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.

Messages of one run
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

Events

EventWhen it is sentKey scopes
message.sentThe 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: messagemessages:read
message.deliveredA 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: messagemessages:read
message.readThe contact read a message. Meta reported the WhatsApp message read.data: messagemessages:read
message.failedA message failed for good. message.failure carries { code, reason }. A scheduled message cancelled before it was sent fails with MESSAGE_CANCELED.data: messagemessages:read
message.receivedA 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, messagemessages:readcontacts:read
message.complainedA 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, messagemessages:read
whatsapp.account.updatedThe WhatsApp account changed. WhatsApp was connected or disconnected, or its credential, quality rating, display name, messaging limit or restriction changed.data: account, changewhatsapp:read
message.media.readyA 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: messagemessages:read
message.media.failedA file a contact sent could not be stored. message.media.status is failed or rejected, with message.media.failureCode.data: messagemessages:read

Errors

CodeStatusMeaning and what to do
BILLING_INSUFFICIENT_CREDIT402The 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_UNAVAILABLE503Your 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_CANCELED402The 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_DUE402The 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_SUSPENDED402The subscription is blocked by the platform.What to do: Retrying will not help until the hold is lifted: contact us.
CONTACT_BLOCKED409The 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_FOUND404The 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_OUT409On 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_FOUND404The 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_DISABLED403Messaging 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_MISMATCH422The 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_FAILED422media.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_AVAILABLE409The 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_ENABLED503This 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_FOUND404GET /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_LARGE413The 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_UNSUPPORTED415The 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_REFUSED400media.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_CANCELABLE409DELETE /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_INBOUND409Only 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_PROVIDER_UNCONFIRMED504Meta 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_LIMITED429Meta 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_RESTRICTED409The 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_TRANSPORT503The 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_CLOSED409A 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_UNAVAILABLE503Meta 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_AVAILABLE409There 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_EXPIRED409The 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_UNSUPPORTED409This 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_REQUIRED422The 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_FOUND404replyToMessageId 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_UNAVAILABLE409The 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_FOUND404A 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_MISSING409A 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_FOUND404No 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_SENDABLE409The 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_CONNECTED409No 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 502META_<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.