Trovacast

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.

Submit a utility template
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’s status.
  • 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 pending and 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).

Record a DLT-registered template
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 dltTemplateId the template is approved — the DLT registration is the approval. Without it, it is a draft and cannot be sent until the id is added.
  • category follows dltCategory: promotional → MARKETING, service_implicit and service_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, is 409 CONFLICT. category, components and parameterFormat are WhatsApp’s and a 400 here.
  • PATCH changes text, variables, dltCategory, dltTemplateId (null clears it) and status (draft, approved, paused, disabled). An approved template’s text or category changes only with the new registration’s id (or back to draft).
  • DELETE removes 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.

Create an email template
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.

Approved WhatsApp templates in English
curl 'https://api.trovacast.com/v1/templates?status=approved&language=en' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"

Endpoints

Events

EventWhen it is sentKey scopes
template.updatedMeta 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, templatetemplates:read

Errors

CodeStatusMeaning and what to do
CONFLICT409The 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_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.
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.
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.
SERVICE_UNAVAILABLE503Temporarily 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_EDITABLE409PATCH /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_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.
VALIDATION_FAILED400The 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_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.