DLT-India onboarding for A2P SMS

India’s TRAI DLT registration is a multi-step workflow spread across an operator portal and your Orbit workspace. This guide walks it end-to-end: what to register, on which portal, what to gather first, the one order that works, and a worked example registering one transactional and one promotional template. The concept page covers the same endpoints field-by-field; this guide covers the flow.

Why registration is mandatory

Under India’s TRAI DLT regime, telecom operators (Jio, Airtel, Vi, BSNL) only deliver A2P SMS from registered senders. A message whose Sender ID, template, or sender identity is not registered and consistent is rejected by the operator before it reaches the handset: no delivery receipt, no retry, no partial pass-through. Four artifacts must be registered and mutually consistent:

Principal Entity (PE): your business identity (one PE under which everything else hangs).
Headers (Sender IDs): the 3–11 character sender labels your messages carry, each tied to your PE and a category.
Content templates: every message body, with variable parts marked as {#var#} placeholders.
Consent templates: the consent wording that backs your opt-ins, required for promotional sends.

You complete the underlying registration on a registrar’s DLT portal. Orbit then mirrors the artifacts: it records the registrar-issued IDs, tracks each artifact’s status (starting at pending, with optional rejection_reason once a registrar responds), and nudges you when a DLT-related rejection shows up on your India traffic. Orbit does not approve anything: the registrar and operators do.

Pick an operator portal

You register on a DLT portal run by (or operated for) one of the Indian operators. Common registrars and their portal brands:

Registrar (use this value in API calls)	Portal / operator
`vilpower`	Vodafone Idea (Vi)
`trueconnect`	Airtel
`tanla`	Airtel (alternative integrator)
`jio`	Jio
`videocon`	Videocon
`bsnl`	BSNL

Pick one: most senders choose the operator that carries the majority of their traffic. Your verifier on the registrar is only one of several; what matters in Orbit is that every artifact you record carries the same registrar value and the same PE ID so the four layers stay consistent. The four artifact types map to Orbit endpoints one-to-one:

Artifact	Orbit endpoint (under `/api/v1/compliance/dlt-india`)
Principal Entity	`principal-entities`
Headers	`headers`
Content templates	`content-templates`
Consent templates	`consent-templates`

Gather the documents first

Have these in hand before you start on the portal: the registrar asks for them in one sitting, and Orbit asks for the resulting IDs:

PE/KYC: your registrar-assigned PE ID (8–20 characters), your legal name exactly as registered, and your PAN or GSTN.
Headers: the exact 3–11 character Sender IDs you want (uppercase letters/digits), each with a category.
Per content template: a sample message body with variable parts written as {#var#}, a template name, its category, and its type (text, unicode, unicode_text, or otp).
Per consent template: the exact opt-in wording and a name.

Orbit enforces the same discipline the registrars do: template bodies up to 2000 characters, up to 20 named variables, and category one of promotional, transactional, service_implicit, or service_explicit. A body whose variable markers don’t match what the registrar approved is rejected downstream: keep one canonical copy of each template.

Peeking ahead while you gather: the GET list endpoints and the /nudge endpoints are always open, so you can check current state even before registration writes are enabled.

The exact order

Register in dependency order: each artifact references the one above, and a registrar will reject a Header or template whose parent PE is not on file.

1. Principal Entity

Complete the PE application on the registrar portal and receive your PE ID. Record it in Orbit:

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/dlt-india/principal-entities \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "registrar": "vilpower",
    "pe_id": "1101234567890123",
    "legal_name": "Acme Retail Pvt Ltd",
    "pan_or_gstn": "AAACA1234A",
    "entity_type": "private_limited"
  }'

The response body’s data.id is the Orbit-side ID every later artifact references as principal_id.

2. Headers

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/dlt-india/headers \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_id": "pe_internal_id",
    "header": "ACMERT",
    "category": "transactional"
  }'

3. Content templates

Register every message body on the portal under a Header, then record it (omit template_id until the registrar issues one: the draft is stored either way):

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/dlt-india/content-templates \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_id": "pe_internal_id",
    "header_id": "hdr_internal_id",
    "template_name": "Order shipped",
    "category": "transactional",
    "template_type": "text",
    "content": "Hi {#var#}, your order {#var#} has shipped.",
    "variables": ["name", "order_id"]
  }'

4. Consent templates

For promotional traffic, register the consent wording that backs your opt-ins:

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/dlt-india/consent-templates \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_id": "pe_internal_id",
    "consent_name": "Marketing opt-in",
    "consent_text": "I agree to receive promotional messages from Acme Retail."
  }'

Every POST sits at pending until the registrar clears it; read status any time with the matching GET list endpoint. Poll the list, or watch the nudge (below) for follow-up.

Delivery nudges

If Orbit’s DLR pipeline sees a DLT-related rejection on your India traffic, it records a nudge for your tenant. GET /api/v1/compliance/dlt-india/nudge returns the current state (failure_count, last_seen_at, dismissed_at); POST /api/v1/compliance/dlt-india/nudge/dismiss acknowledges it (a new failure re-raises the banner). The nudge is observational: it tells you a registration gap exists; it does not call the registrar.

The 503 FEATURE_DISABLED gate

Registration writes are off by default. The four POST endpoints above return 503 FEATURE_DISABLED until the deployment enables DLT registration (DEVOTEL_DLT_REGISTRATION_ENABLED=true plus the registrar credential pair). Reads: all GET list endpoints and both nudge endpoints: stay open regardless, so existing rows remain visible and delivery nudges still surface. What to do when a write returns 503:

Record your registrar-side progress on the portal as usual: the portal flow is unaffected.
Contact support to have DLT registration enabled for your deployment, then replay the POST calls exactly as above.
While gated, use the GET endpoints to verify which artifacts are already on file before re-submitting.

The gate stays closed only while the registrar integration is parked; previously recorded rows are never hidden.

Worked example: one transactional, one promotional

Register ACMER1 (transactional) and ACMER2 (promotional) under one PE, each with a template. Step 1: PE. Complete the PE application on the VILPOWER portal and receive PE ID 1101234567890123. Record it, and capture the returned data.id as PE_ID:

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/dlt-india/principal-entities \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "registrar": "vilpower",
    "pe_id": "1101234567890123",
    "legal_name": "Acme Retail Pvt Ltd",
    "pan_or_gstn": "AAACA1234A",
    "entity_type": "private_limited"
  }'

Step 2: Headers. Register both Sender IDs on the portal, then record them. Capture each data.id:

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/dlt-india/headers \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_id": "'"$PE_ID"'",
    "header": "ACMER1",
    "category": "transactional"
  }'

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/dlt-india/headers \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_id": "'"$PE_ID"'",
    "header": "ACMER2",
    "category": "promotional"
  }'

Step 3: Content templates. Register one transactional and one promotional template, each under its Header. Attach the registrar-issued template_id once the portal issues it (running the same call with the ID updates the row):

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/dlt-india/content-templates \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_id": "'"$PE_ID"'",
    "header_id": "'"$TX_HDR_ID"'",
    "template_name": "Order shipped",
    "category": "transactional",
    "template_type": "text",
    "content": "Hi {#var#}, your order {#var#} has shipped.",
    "variables": ["name", "order_id"]
  }'

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/dlt-india/content-templates \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_id": "'"$PE_ID"'",
    "header_id": "'"$PROMO_HDR_ID"'",
    "template_name": "Weekend offer",
    "category": "promotional",
    "template_type": "text",
    "content": "Hi {#var#}, get {#var#}% off this weekend at Acme Retail.",
    "variables": ["name", "discount"]
  }'

Step 4: Consent template (required for the promotional Header):

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/dlt-india/consent-templates \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_id": "'"$PE_ID"'",
    "consent_name": "Marketing opt-in",
    "consent_text": "I agree to receive promotional messages from Acme Retail."
  }'

Step 5: Verify. List all four kinds until every row shows approved, and watch the nudge until your first India sends pass:

curl -s https://api.orbit.devotel.io/api/v1/compliance/dlt-india/principal-entities \
  -H "Authorization: Bearer $ORBIT_API_KEY"

curl -s https://api.orbit.devotel.io/api/v1/compliance/dlt-india/nudge \
  -H "Authorization: Bearer $ORBIT_API_KEY"

Once the artifacts are approved and consistent, India traffic from the ACMER1 / ACMER2 Headers stops being rejected at the operator.

If it gets rejected

PE rejected: the registrar’s rejection_reason lands on the PE row; fix the legal name/PAN mismatch on the portal and re-record.
Header rejected: most often the category is wrong for the sender pattern (a promotional-looking Header filed as transactional), or the string breaches the 3–11 character rule.
Template rejected: the body or variable markers deviate from the registrar’s canonical form; re-submit one canonical copy.
Delivery still failing after approval: the template text you send must match the approved template exactly except inside {#var#} placeholders; the nudge count on /nudge tells you whether rejections are still being seen.

See DLT gates troubleshooting for the rejection side.

DLT-India concept reference: field-by-field endpoint sketch.
10DLC registration: the US counterpart process.
Consent Management: DPDP consent receipts alongside DLT.
Go-live checklist: the broader launch sweep registration fits into.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

DLT-India onboarding for A2P SMS

DLT-India onboarding for A2P SMS

Why registration is mandatory

Pick an operator portal

Gather the documents first

The exact order

Delivery nudges

The 503 FEATURE_DISABLED gate

Worked example: one transactional, one promotional

If it gets rejected

​DLT-India onboarding for A2P SMS

​Why registration is mandatory

​Pick an operator portal

​Gather the documents first

​The exact order

​Delivery nudges

​The 503 FEATURE_DISABLED gate

​Worked example: one transactional, one promotional

​If it gets rejected

​Related guides

DLT-India onboarding for A2P SMS

Why registration is mandatory

Pick an operator portal

Gather the documents first

The exact order

Delivery nudges

The 503 FEATURE_DISABLED gate

Worked example: one transactional, one promotional

If it gets rejected

Related guides