Trovacast

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

  1. In the console, enter the project’s DLT principal entity id and register a header. The platform activates the header after registering it.
  2. Record each DLT template you registered: POST /v1/templates with channel: "sms" (see Templates).
  3. 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.

200 OK (json)
{
  "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

Send a one-time code, valid for 10 minutes
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 is 400 SMS_TEMPLATE_REQUIRED: DLT has carriers match every SMS against a registered text. quickReplies, email, media and interactive are a 400. Free text abroad: see Outside India.
  • Recipient: exactly one of contactId or to.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, with country).
  • Template: an approved SMS template with its DLT id (409 TEMPLATE_NOT_SENDABLE otherwise), 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 a 400.
  • Header: senderId names a header from GET /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, is 409 SMS_HEADER_CATEGORY_MISMATCH.
202 Accepted (json)
{
  "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
}
Template categoryNeedsRefused with
promotionalmarketing: opted_inCONSENT_REQUIRED, or CONSENT_MARKETING_REQUIRED with updates only
service_explicitmarketing or updates opted inCONSENT_REQUIRED
service_implicit, transactionalNothing, but an opt-out refusesCONSENT_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.

A promotional SMS that waits for the window
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" with text and sms.category — transactional, service_implicit, service_explicit or promotional. 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" on GET /v1/sms/senders); or, where the country allows it, the platform vendor’s own sender (sms.header: null). With no senderId, 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_REQUIRED until one of your numbers there is registered and activated. A sender a country does not accept is 409 SMS_SENDER_NOT_ALLOWED; both carry country.
  • A promotional SMS gains the country’s opt-out line (Reply STOP to opt out in Great Britain) when its text has no “STOP” — counted in its segments, so what is billed is what is sent.
  • No promotional window: sms.deferUntilWindow is India’s only.
Free text to Great Britain
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-Key contract as WhatsApp. A submission the provider never confirmed fails as SUBMISSION_UNKNOWN and 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

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.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

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.
CHANNEL_NOT_CONFIGURED409The 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.
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_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.
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.
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.
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.
SMS_DESTINATION_NOT_ALLOWED422The 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_MISMATCH409The 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_WINDOW409A 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_ALLOWED409The 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_REQUIRED409The 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_REQUIRED400An 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_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.