Messaging
SMS
Send DLT-registered SMS templates in India under your registered headers, and free text abroad under the sender each country accepts — consent checked by category, the promotional window enforced.
SMS is India DLT first: every SMS to India is one of the project’s registered DLT templates, sent under one of its registered headers, carrying its DLT entity and template ids. To other countries the platform texts, free text is allowed and the sender follows the country’s rules (Outside India). It goes out through the same POST /v1/messages as WhatsApp, with channel: "sms", and comes back as the same message resource and message.* events.
Setting up
- In the console, enter the project’s DLT principal entity id and register a header. The platform activates the header after registering it.
- Record each DLT template you registered:
POST /v1/templateswithchannel: "sms"(see Templates). - Record SMS consent with
PUT /v1/contacts/{contactId}/consent/sms(see Consent).
Until then a send is 409 CHANNEL_NOT_CONFIGURED (no SMS settings, or no SMS on this deployment) or 409 NO_SENDER_AVAILABLE / 409 MESSAGING_SENDER_RESTRICTED (no active header). Changing the entity id in the console sends the active headers back to pending_verification until the platform re-activates them.
Headers
GET /v1/sms/senders (sms:read) lists the project’s DLT headers in one page. id is what a send’s senderId takes; header is what the customer’s phone shows. kind decides categories: numeric headers carry promotional SMS, alphabetic headers the rest. Only active headers send. Registering and removing headers happens in the console.
{
"data": [
{
"object": "sms_sender",
"id": "4b7e2a1c-9d8f-4e6a-b5c4-3d2e1f0a9b8c",
"header": "ACMEIN",
"label": "Order updates",
"kind": "alphabetic",
"status": "active",
"categories": [
"TRANSACTIONAL",
"SERVICE_IMPLICIT",
"SERVICE_EXPLICIT"
],
"isDefault": true,
"createdAt": "2026-10-28T09:00:00.000Z",
"updatedAt": "2026-10-28T09:00:00.000Z"
}
],
"nextCursor": null
}Send an SMS
curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: login-la_42-code' \
-H 'Content-Type: application/json' \
-d '{
"channel": "sms",
"type": "template",
"to": {
"phone": "+919876543210"
},
"template": {
"name": "login_code",
"language": "en"
},
"variables": {
"code": "482913"
},
"sms": {
"validitySeconds": 600
},
"metadata": {
"loginAttempt": "la_42"
}
}'- Template only in India.
type: "text"to an Indian number is400 SMS_TEMPLATE_REQUIRED: DLT has carriers match every SMS against a registered text.quickReplies,email,mediaandinteractiveare a400. Free text abroad: see Outside India. - Recipient: exactly one of
contactIdorto.phone(international format; a number without a country code is read as Indian). The contact needs a phone number (422 RECIPIENT_PHONE_REQUIRED) in a country the project texts — the platform’s destination list, India first (422 SMS_DESTINATION_NOT_ALLOWED, withcountry). - Template: an
approvedSMS template with its DLT id (409 TEMPLATE_NOT_SENDABLEotherwise), by{ id }or{ name, language }. - Variables: exactly the template’s names; each value non-blank, one line, at most 30 characters (DLT’s limit), and fitting its placeholder’s type — a number for
{#numeric#}, an http(s) link for{#url#}. A link in an untyped{#var#}is refused. Over 10 segments is a400. - Header:
senderIdnames a header fromGET /v1/sms/senders; omitted, the default header is used if it fits the template’s category and is active, else the oldest active header that does. A numeric header for a non-promotional template, or the reverse, is409 SMS_HEADER_CATEGORY_MISMATCH.
{
"object": "message",
"channel": "sms",
"type": "template",
"status": "queued",
"text": "Your login code is 482913. Valid for 10 minutes. -ACME",
"sms": {
"header": "ACMEIN",
"segments": 1,
"encoding": "gsm7",
"country": "IN",
"sendAfter": null,
"expiresAt": "2026-11-05T10:10:00.000Z",
"price": null
},
"providerMessageId": null
}Consent by TRAI category
| Template category | Needs | Refused with |
|---|---|---|
promotional | marketing: opted_in | CONSENT_REQUIRED, or CONSENT_MARKETING_REQUIRED with updates only |
service_explicit | marketing or updates opted in | CONSENT_REQUIRED |
service_implicit, transactional | Nothing, but an opt-out refuses | CONSENT_OPTED_OUT |
A contact-level opt-out, do-not-call or block outranks all of them (CONTACT_OPTED_OUT, CONTACT_BLOCKED). The template’s DLT category is also what it is billed as: promotional counts as MARKETING, service_implicit and service_explicit as UTILITY, transactional as AUTHENTICATION.
The promotional window
A promotional SMS goes only between 09:00 and 21:00 IST, narrowed by the project’s own window if it set one — 409 SMS_OUTSIDE_SEND_WINDOW otherwise, with opensAt in the body. Or let it wait: with "sms": { "deferUntilWindow": true } the SMS is accepted (202, queued) and held until the window opens — sms.sendAfter says when — then sent with every rule checked again. A held SMS goes out within 24 hours of the request or fails as SMS_OUTSIDE_SEND_WINDOW. The flag is ignored on other categories, which are not window-bound.
curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: festive-offer-CONTACT_ID' \
-H 'Content-Type: application/json' \
-d '{
"channel": "sms",
"type": "template",
"contactId": "CONTACT_ID",
"template": {
"name": "festive_offer",
"language": "en"
},
"variables": {
"offer": "20% off"
},
"senderId": "PROMOTIONAL_HEADER_ID",
"sms": {
"deferUntilWindow": true
}
}'Outside India
DLT is India’s scheme, so its rules — a registered template with its DLT ids, the entity id, the header that fits the category, the promotional hours — apply to +91 numbers only. The platform keeps a rule set per country (Great Britain, the UAE, the United States, Canada, Singapore, Australia and Germany are described; each is texted once the operator turns it on and prices it). To those countries:
- Free text is allowed:
type: "text"withtextandsms.category—transactional,service_implicit,service_explicitorpromotional. The category decides consent exactly as a template’s does and the price (promotional as marketing, transactional as authentication, service as utility). Templates send abroad too; their DLT ids are simply not sent. - The sender follows the country: an alphanumeric sender ID (one of your active headers with a letter in it) where the country accepts one; one of your SMS-capable numbers, registered as a sender and activated by the platform (
kind: "number"onGET /v1/sms/senders); or, where the country allows it, the platform vendor’s own sender (sms.header: null). With nosenderId, the first that fits is used: your default sender, your number in the destination’s numbering plan, your alphanumeric ID, any of your numbers, the vendor default. - The United States and Canada take registered numbers only: anything else is
409 SMS_SENDER_REGISTRATION_REQUIREDuntil one of your numbers there is registered and activated. A sender a country does not accept is409 SMS_SENDER_NOT_ALLOWED; both carrycountry. - A promotional SMS gains the country’s opt-out line (
Reply STOP to opt outin Great Britain) when its text has no “STOP” — counted in its segments, so what is billed is what is sent. - No promotional window:
sms.deferUntilWindowis India’s only.
curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: order-1001-out-for-delivery-sms' \
-H 'Content-Type: application/json' \
-d '{
"channel": "sms",
"type": "text",
"to": {
"phone": "+447700900123"
},
"text": "Your Acme order #1001 is out for delivery today.",
"sms": {
"category": "service_implicit"
}
}'One-time codes
"sms": { "validitySeconds": 30–86400 } on an authentication SMS (a transactional template) stamps sms.expiresAt: if the SMS is still queued then (a throttle, an outage) it fails as EXPIRED_BEFORE_SEND, unsent and uncharged. A validity on any other category is a 400.
Replies and keywords
A text to one of your SMS-capable numbers arrives as message.received on the contact's SMS conversation (direction: inbound, text, sms.country the sender's), and in the console Inbox. sms.keyword names a keyword: stop (STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPT OUT, REVOKE) opts the contact out of SMS; start (START, UNSTOP, SUBSCRIBE, OPT IN) lifts their own opt-out for service and transactional SMS — promotional consent is never inferred from a text; help (HELP, INFO) changes nothing and sends nothing: answering it is yours. A sender who is not a contact is dropped unless SMS auto-create is on for the project. Inbound SMS is not billed.
Statuses and delivery
queued → sending → sent → delivered, or failed; SMS has no read. sent means the SMS provider accepted it. Expect delivered about 60–90 seconds after sent when the carrier reports promptly — later when it does not, and some carriers never report, leaving the SMS sent. Once the delivery log arrives, sms.price carries what the provider reported the SMS cost, for information only: you are billed your plan’s per-segment price. A carrier failure after acceptance is refunded.
- Billing: per segment —
sms.segments× your plan’s SMS rate for the category and the destination country;402/503 BILLING_*before anything is queued. - Throughput: each project’s SMS go out at up to the platform’s per-project rate (10 a second by default); a burst beyond it waits its turn, never refused for it.
- Exactly once: the same
Idempotency-Keycontract as WhatsApp. A submission the provider never confirmed fails asSUBMISSION_UNKNOWNand is never sent again — a second SMS would be a second text and a second charge. - Every rule runs again when the SMS is actually sent. One that fails then — the header disabled, consent withdrawn, the window closed while it waited, an expired one-time code, the number on the provider’s opt-out list — arrives as
message.failed, uncharged. The text and DLT ids are sent as they were when the SMS was accepted.
MMS to the US and Canada
Send a picture with type: "mms": one JPEG or PNG (at most 5 MB) as media.url or media.id (an upload), optional text, and sms.category as for free text. MMS goes to US and Canadian numbers only, from one of your registered numbers there, and is priced once per message on your plan’s MMS rate — never per segment. Anywhere else (India’s DLT routes carry no picture messages) is SMS_MMS_UNSUPPORTED, before anything is created. For documents or video, or to India, use WhatsApp — or send a link in the SMS.
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 - GET
/v1/sms/sendersLists the organization’s SMS senders (DLT headers, sender IDs, numbers) with their status and the template categories each fits - 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/templatesLists WhatsApp templates (or SMS / email templates, with channel=sms / channel=email), newest first
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.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 |
contact.consent.updated | A contact’s consent on a channel changed. WhatsApp, email or SMS consent moved — a STOP, an unsubscribe, a spam report, a reply, Meta’s own preference, or a write through the API or the console. consent.object names the channel.data: consent, livemode, source | contacts: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. |
CHANNEL_NOT_CONFIGURED | 409 | The project has not set the channel up — email: no email account of its own (the platform’s mail never sends for it); SMS: no SMS settings or DLT entity id — or the deployment does not carry it. On a call, the provider is not a channel this deployment runs or the organization has set up. Also a message.failed code when the account was disconnected after the message was queued; nothing was sent.What to do: Set the channel up in Settings → Channels (WhatsApp, Email or SMS) — for a call in Settings → Calling, or leave provider out — then retry. A message that failed with this code was never sent: send it again once the account is connected. |
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_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. |
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_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. |
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. |
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. |
SMS_DESTINATION_NOT_ALLOWED | 422 | The number is in a country this project does not text: the platform’s destination list (India, plus the countries the operator has enabled) and the project’s own choice decide. country is in the body (null for a number in no country).What to do: Retrying unchanged cannot succeed. If you should text that country, check the project’s own list in Settings → Channels → SMS, or contact us to have it enabled. |
SMS_HEADER_CATEGORY_MISMATCH | 409 | The header does not fit the template’s category: promotional SMS go from a numeric header, every other category from an alphabetic one.What to do: Pass the senderId of a header of the right kind (GET /v1/sms/senders), or send a template whose category fits the header. |
SMS_OUTSIDE_SEND_WINDOW | 409 | A promotional SMS outside 09:00–21:00 IST (or the project’s narrower window); opensAt says when it could go. See SMS.What to do: Send again at opensAt, or send with "sms": { "deferUntilWindow": true } to have it held until the window opens. |
SMS_SENDER_NOT_ALLOWED | 409 | The sender cannot carry an SMS to that country: an alphanumeric ID where the country allows none, a number from another country, or the vendor’s default where the country wants your own. country is in the body. See SMS.What to do: Pass a senderId the country accepts (GET /v1/sms/senders) — often one of your numbers there, made an SMS sender with POST /v1/numbers/{numberId}/sms-sender — or leave senderId out so the first sender that fits is used. |
SMS_SENDER_REGISTRATION_REQUIRED | 409 | The country (the United States and Canada, for example) takes SMS only from a registered number, and the project has none for it. country is in the body.What to do: Register one of your numbers in that country with the carrier (10DLC or toll-free verification), make it an SMS sender (POST /v1/numbers/{numberId}/sms-sender), and send from it once it is active. |
SMS_TEMPLATE_REQUIRED | 400 | An SMS to an Indian number sent as type: "text": SMS to India are template-only, because DLT has carriers match every SMS against a registered text. Free text goes to numbers outside India. Also a message.failed code for a free-text SMS whose number turned out to be Indian.What to do: Send an approved SMS template with its DLT id (type: "template"). See SMS templates. |
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. |