Messaging
Templates
Submit WhatsApp templates to Meta for review, record DLT-registered SMS templates and create email templates — then send any of them by name.
/v1/templates covers the project’s WhatsApp templates and, with channel=sms or channel=email, its SMS and email ones. Every template carries channel, a lower-case status (draft, pending, approved, rejected, paused, disabled, deleted, in_appeal), its category, and variables — the names POST /v1/messages must fill. Reading needs templates:read; creating, editing, deleting and syncing need templates:write.
WhatsApp templates
POST /v1/templates with { name, language, category, components, parameterFormat? } is checked against Meta’s template rules (a 400 naming the broken rule), then submitted to Meta for review: the template comes back pending (201), and Meta’s verdict arrives as a template.updated event. name is lowercase letters, digits and underscores; category is MARKETING, UTILITY or AUTHENTICATION; every variable needs an example. A template with this name and language that already exists is 409 CONFLICT.
curl -X POST 'https://api.trovacast.com/v1/templates' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: template-order-confirmation-en' \
-H 'Content-Type: application/json' \
-d '{
"name": "order_confirmation",
"language": "en",
"category": "UTILITY",
"components": [
{
"type": "BODY",
"text": "Hi {{1}}, your order {{2}} is confirmed.",
"example": {
"body_text": [
[
"Aarav",
"#1001"
]
]
}
}
]
}'category is Meta’s current one: when Meta re-categorizes a template, previousCategory keeps what it was. Submitting, editing, deleting and syncing need a connected WhatsApp account (409 WHATSAPP_NOT_CONNECTED). Meta’s refusals come back as 400 META_<code> (its reason in message), its throttling as 429 MESSAGING_RATE_LIMITED, and 503 META_UNAVAILABLE when Meta could not be reached — a submission or edit may still have reached Meta, so sync before repeating it.
Edit a WhatsApp template
PATCH /v1/templates/{templateId} changes components — the whole new set, because Meta replaces every component with the ones sent — and/or category. Meta’s rules apply:
- Only an approved, rejected or paused template can be edited; anything else is
409 TEMPLATE_NOT_EDITABLE, with the template’sstatus. - An approved template’s category never changes (
400). - An approved template can be edited at most once in 24 hours and 10 times in 30 days; Meta counts that, and its refusal comes back as
400 META_<code>. - An edit sends the template back to review: it answers
pendingand is not sendable until Meta’s verdict (409 TEMPLATE_NOT_SENDABLE). - A template that changed while the edit ran is
409 CONFLICT: read it again.
DELETE /v1/templates/{templateId} deletes a WhatsApp template at Meta (this language only) and keeps it as deleted, so messages keep their reference. POST /v1/templates/sync re-reads every template from Meta and reconciles them.
SMS templates
With channel: "sms", POST /v1/templates records a DLT registration. text is the text exactly as registered on DLT, placeholders included: {#var#}, or typed {#numeric#}, {#alphanumeric#}, {#url#}, {#urlott#}, {#cbn#}, {#email#}. variables names the placeholders in order (omitted: var1…varN).
curl -X POST 'https://api.trovacast.com/v1/templates' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: template-login-code-en' \
-H 'Content-Type: application/json' \
-d '{
"channel": "sms",
"name": "login_code",
"language": "en",
"dltCategory": "transactional",
"dltTemplateId": "1107161234567890123",
"text": "Your login code is {#numeric#}. Valid for 10 minutes. -ACME",
"variables": [
"code"
]
}'- With
dltTemplateIdthe template isapproved— the DLT registration is the approval. Without it, it is adraftand cannot be sent until the id is added. categoryfollowsdltCategory:promotional→MARKETING,service_implicitandservice_explicit→UTILITY,transactional→AUTHENTICATION. It is the category the SMS is consent-checked and billed as.- Another template with this name and language, or with this
dltTemplateId, is409 CONFLICT.category,componentsandparameterFormatare WhatsApp’s and a400here. PATCHchangestext,variables,dltCategory,dltTemplateId(nullclears it) andstatus(draft,approved,paused,disabled). An approved template’s text or category changes only with the new registration’s id (or back todraft).DELETEremoves an SMS template outright; messages keep their text.
Email templates
With channel: "email": { name, language, email: { subject, text?, html?, category } } — a one-line subject, a plain-text and/or HTML body (up to 256 KB, sanitized when saved), and category transactional or marketing. {{name}} placeholders (a letter, then letters, digits or underscores; at most 50) anywhere in the subject, text or HTML become its variables. An email template is approved at once. It cannot be edited through the API (409 TEMPLATE_NOT_EDITABLE; edit it in the console), and DELETE removes it outright.
curl -X POST 'https://api.trovacast.com/v1/templates' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: template-order-confirmed-email-en' \
-H 'Content-Type: application/json' \
-d '{
"channel": "email",
"name": "order_confirmed",
"language": "en",
"email": {
"subject": "Your order {{order}} is confirmed",
"text": "Hi {{first_name}}, your order {{order}} is confirmed.",
"category": "transactional"
}
}'Find templates
GET /v1/templates filters exactly by channel, status, name and language, newest first.
curl 'https://api.trovacast.com/v1/templates?status=approved&language=en' \
-H "Authorization: Bearer $TROVACAST_API_KEY"Endpoints
- GET
/v1/templatesLists WhatsApp templates (or SMS / email templates, with channel=sms / channel=email), newest first - POST
/v1/templatesSubmits a WhatsApp template to Meta for review (pending until Meta decides), records an SMS template’s DLT registration, or creates an email template (approved at once) - GET
/v1/templates/{templateId}Retrieves a template - PATCH
/v1/templates/{templateId}Edits a template: a WhatsApp template’s components (or a rejected or paused one’s category), back to Meta for review; or an SMS template’s DLT registration - DELETE
/v1/templates/{templateId}Deletes the template at Meta and retires it (status `deleted`); idempotent. An SMS or email template is deleted outright and answered as it was, with status `deleted`. - POST
/v1/templates/syncRe-reads every template from Meta and reconciles local copies
Events
| Event | When it is sent | Key scopes |
|---|---|---|
template.updated | Meta reviewed a template or changed its category or quality. change says which facet moved; template is as GET /v1/templates/{templateId} reads it.data: change, template | templates:read |
Errors
| Code | Status | Meaning and what to do |
|---|---|---|
CONFLICT | 409 | The resource's state does not allow this, there is a uniqueness clash, or it changed concurrently.What to do: Read the resource again, then decide: retry against its current state (with its new version where it has one), or choose another value for a uniqueness clash. |
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. |
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. |
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. |
SERVICE_UNAVAILABLE | 503 | Temporarily unavailable.What to do: Retry with backoff — with the same Idempotency-Key on a write — until an answer is replayed. If it persists, contact us with the requestId. |
TEMPLATE_NOT_EDITABLE | 409 | PATCH /v1/templates/{templateId} on a WhatsApp template Meta will not edit now (anything but approved, rejected or paused — its status is in the body), one never submitted to Meta, an email template, or a test key’s template. See Templates.What to do: Wait until the WhatsApp template is approved, rejected or paused; submit one never submitted with POST /v1/templates; edit an email template in the console; delete a test template and create it again. |
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. |
VALIDATION_FAILED | 400 | The request is malformed; message lists each problem. Also a bulk webhook resend whose until is not after since.What to do: Correct every problem message lists, then send the request again; the same body fails the same way. The API reference has each endpoint's fields. |
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. |