Get started
Send an SMS with DLT
Send a DLT-registered SMS in India: find your header, record the template, check consent by TRAI category, send and follow the delivery report.
In India every commercial SMS is matched against a text registered on DLT, sent under a registered header. Trovacast enforces those rules before an SMS leaves, so a send either goes out compliant or is refused with a code that says why.
1. What you need
- Your DLT principal entity id and a registered header, entered in the console (Settings → Messaging → SMS). The platform activates a header after registering it — until then a send is
409 NO_SENDER_AVAILABLE. - A template registered on DLT: its exact text, its category and the content template id DLT issued.
- A key with
sms:read,templates:write,contacts:write,consent:write,messages:writeandmessages:read— see Authentication and Scopes.
2. Find your header
curl 'https://api.trovacast.com/v1/sms/senders' \
-H "Authorization: Bearer $TROVACAST_API_KEY"Use an active header. Numeric headers carry promotional SMS; alphabetic headers carry the rest — a mismatch is 409 SMS_HEADER_CATEGORY_MISMATCH. Leave senderId out of the send and the default header is used when it fits.
3. Record the DLT template
text is the text exactly as registered on DLT, placeholders included; variables names them in order. With dltTemplateId the template is approved at once — the DLT registration is the approval.
curl -X POST 'https://api.trovacast.com/v1/templates' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: template-order-shipped-en' \
-H 'Content-Type: application/json' \
-d '{
"channel": "sms",
"name": "order_shipped",
"language": "en",
"dltCategory": "service_implicit",
"dltTemplateId": "1107161234567890123",
"text": "Dear {#var#}, your order {#var#} has shipped. -ACME",
"variables": [
"name",
"order"
]
}'4. Check consent for the category
| DLT category | Consent the contact needs |
|---|---|
promotional | SMS marketing: opted_in — and it goes only between 09:00 and 21:00 IST |
service_explicit | SMS marketing or updates opted in |
service_implicit, transactional | None, but an opt-out refuses it |
This guide’s service_implicit template needs no opt-in. For a promotional one, record the customer’s SMS opt-in first:
curl -X PUT 'https://api.trovacast.com/v1/contacts/CONTACT_ID/consent/sms' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: customer-1001-sms-consent' \
-H 'Content-Type: application/json' \
-d '{
"source": "WEB_FORM",
"marketing": "opted_in",
"textShown": "Text me offers from Acme"
}'5. Send the SMS
SMS is template-only (type: "text" is 400 SMS_TEMPLATE_REQUIRED). Each variable value is one line of at most 30 characters, fitting its placeholder’s type. Sending by to.phone creates the contact if it does not exist, which is why the key needs contacts:write.
curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: order-1001-shipped-sms' \
-H 'Content-Type: application/json' \
-d '{
"channel": "sms",
"type": "template",
"to": {
"phone": "+919876543210"
},
"template": {
"name": "order_shipped",
"language": "en"
},
"variables": {
"name": "Aarav",
"order": "#1001"
},
"senderId": "SMS_SENDER_ID",
"metadata": {
"orderId": "1001"
}
}'{
"object": "message",
"channel": "sms",
"type": "template",
"status": "queued",
"text": "Dear Aarav, your order #1001 has shipped. -ACME",
"sms": {
"header": "ACMEIN",
"segments": 1,
"encoding": "gsm7",
"country": "IN",
"sendAfter": null,
"expiresAt": null,
"price": null
},
"metadata": {
"orderId": "1001"
}
}6. Follow the delivery report
queued → sending → sent → delivered, or failed — SMS has no read. Expect delivered about 60–90 seconds after sent when the carrier reports promptly; some carriers report late or never, leaving the SMS sent. Subscribe to message.sent, message.delivered and message.failed, or read the message back with GET /v1/messages/{messageId}. You are billed per segment, and a carrier failure after acceptance is refunded.