> ## Documentation Index
> Fetch the complete documentation index at: https://agents.docs.timepay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS

> Send SMS messages through DLT-compliant PE-TM chain linking for Indian businesses, or connect your existing SMS provider.

## Overview

timepay.ai supports SMS messaging as part of your campaign workflows. Send payment reminders, OTPs, confirmations, and follow-up messages to your customers.

<CardGroup cols={3}>
  <Card title="DLT Compliant" icon="shield-check">
    Full PE-TM chain linking support for Indian regulations
  </Card>

  <Card title="High Deliverability" icon="check-double">
    Direct carrier routes for maximum delivery rates
  </Card>

  <Card title="Real-Time Tracking" icon="signal-stream">
    Delivery reports and analytics in your dashboard
  </Card>
</CardGroup>

***

## India: DLT Compliance (PE-TM Linking)

If you're sending SMS to Indian numbers, you must comply with TRAI's Distributed Ledger Technology (DLT) regulations.

### What is PE-TM Chain Linking?

| Term              | Full Form         | Description                                                     |
| ----------------- | ----------------- | --------------------------------------------------------------- |
| **PE**            | Principal Entity  | Your business (the brand sending messages)                      |
| **TM**            | Telemarketer      | The SMS service provider (aggregator)                           |
| **Chain Linking** | PE-TM Association | Linking your PE account with a TM to authorize message delivery |

<Note>
  **Why is this required?** TRAI mandates DLT registration to reduce spam and ensure only authorized businesses send commercial SMS in India.
</Note>

### Prerequisites

Before enabling SMS, ensure you have:

<Checklist>
  * [ ] DLT registration as Principal Entity (PE)
  * [ ] Registered Sender ID (Header)
  * [ ] Approved SMS templates on DLT portal
  * [ ] PE ID / Entity ID from your DLT operator
</Checklist>

### DLT Registration

If you haven't registered yet:

<Steps>
  <Step title="Choose a DLT Operator">
    Register on any TRAI-approved DLT platform:

    * [Jio TruConnect](https://trueconnect.jio.com/)
    * [Vodafone Idea Vilpower](https://vilpower.in/)
    * [Airtel DLT](https://www.airtel.in/business/b2b/dlt)
    * [BSNL DLT](https://www.ucc-bsnl.co.in/)
    * [Videocon Connect](https://smartping.live/)
  </Step>

  <Step title="Register as Principal Entity">
    Submit:

    * Business PAN card
    * GST certificate
    * Certificate of Incorporation
    * Authorized signatory details
    * Letter of Authorization
  </Step>

  <Step title="Create Sender IDs (Headers)">
    Register your SMS sender IDs:

    * **Promotional:** 6 numeric digits (e.g., `567890`)
    * **Transactional:** 6 alphabetic characters (e.g., `TMPPAY`)
    * **Service Implicit:** 6 alphanumeric (e.g., `TPYSVC`)
  </Step>

  <Step title="Register Templates">
    Submit and get approval for your SMS templates. Include:

    * Template content with variables
    * Template category (Transactional, Promotional, Service)
    * Associated Sender ID
  </Step>

  <Step title="Complete PE-TM Linking">
    Link your PE account with timepay.ai's Telemarketer (TM) account. We'll provide our TM ID for linking.
  </Step>
</Steps>

### PE-TM Linking Process

<Steps>
  <Step title="Get timepay.ai TM ID">
    Contact **[support@timepay.ai](mailto:support@timepay.ai)** to get our Telemarketer ID for your DLT operator.

    ```
        timepay.ai TM IDs:
        - Jio TruConnect: [Contact for ID]
        - Vodafone Vilpower: [Contact for ID]
        - Airtel DLT: [Contact for ID]
    ```
  </Step>

  <Step title="Initiate Linking">
    Log in to your DLT portal and navigate to **Telemarketer Linking** or **Consent Management**.
  </Step>

  <Step title="Add Telemarketer">
    Enter timepay.ai's TM ID and submit the linking request.
  </Step>

  <Step title="Share Headers & Templates">
    Link your registered Sender IDs and Templates to the TM account.
  </Step>

  <Step title="Confirm in timepay.ai">
    Once linked, provide us with:

    * Your PE ID / Entity ID
    * Linked Sender IDs
    * Approved Template IDs
  </Step>
</Steps>

<Warning>
  **Important:** Messages will fail if PE-TM linking is not complete or templates are not approved. Ensure all templates are in "Approved" status on the DLT portal.
</Warning>

***

## Connecting SMS to timepay.ai

### Option 1: Use timepay.ai SMS (Recommended)

We provide DLT-compliant SMS delivery through our integrated telemarketer setup.

<Steps>
  <Step title="Complete DLT Setup">
    Follow the PE-TM linking process above.
  </Step>

  <Step title="Add Details in Dashboard">
    Go to **Settings → Integrations → SMS** and enter:

    * PE ID / Entity ID
    * DLT Operator
    * Sender IDs (comma-separated if multiple)
  </Step>

  <Step title="Import Templates">
    Click **Import Templates** to fetch your approved templates from the DLT portal (or manually add Template IDs).
  </Step>

  <Step title="Test SMS">
    Send a test message to verify the setup.
  </Step>
</Steps>

### Option 2: Connect Your SMS Provider

Already have an SMS provider? Connect it to timepay.ai.

**Supported Providers:**

| Provider  | Integration Type |
| --------- | ---------------- |
| MSG91     | API Integration  |
| Gupshup   | API Integration  |
| Twilio    | API Integration  |
| Kaleyra   | API Integration  |
| Textlocal | API Integration  |
| Custom    | Webhook / API    |

<Steps>
  <Step title="Select Provider">
    Go to **Settings → Integrations → SMS → Add Provider**
  </Step>

  <Step title="Enter Credentials">
    Provide:

    * API Key / Auth Token
    * Sender ID
    * DLT Entity ID (for India)
    * DLT Template IDs
  </Step>

  <Step title="Configure Webhook">
    Set up delivery report webhook:

    ```
        https://api.agents.timepay.ai/webhooks/sms/delivery
    ```
  </Step>

  <Step title="Test & Activate">
    Send a test message and activate the integration.
  </Step>
</Steps>

### Option 3: Custom / In-House Provider

Have an in-house SMS gateway or using a provider not listed above?

**Contact Support** at **[support@timepay.ai](mailto:support@timepay.ai)** with:

* Provider name / Gateway details
* API documentation
* Authentication method
* Sample request/response format
* DLT integration details

Our team will configure a custom connector for your setup.

<Note>
  **Timeline:** Custom integrations typically take 3-5 business days.
</Note>

***

## SMS Templates

### DLT Template Format

DLT templates use `{#var#}` for variables:

```
Dear {#var#}, your EMI of Rs.{#var#} for Loan {#var#} is due on {#var#}. 
Pay now to avoid late fees. - TMPPAY
```

### Template in timepay.ai

When using templates in workflows, map variables:

| DLT Variable    | Maps To         |
| --------------- | --------------- |
| `{#var#}` (1st) | `customer_name` |
| `{#var#}` (2nd) | `emi_amount`    |
| `{#var#}` (3rd) | `loan_id`       |
| `{#var#}` (4th) | `due_date`      |

### Template Categories (DLT)

| Category             | Use Case                      | Consent Required | Timing      |
| -------------------- | ----------------------------- | ---------------- | ----------- |
| **Transactional**    | OTPs, alerts, confirmations   | Implicit         | 24/7        |
| **Service Implicit** | Account updates, reminders    | Implicit         | 24/7        |
| **Service Explicit** | Service info (opted-in users) | Explicit         | 9 AM - 9 PM |
| **Promotional**      | Offers, marketing             | Explicit         | 9 AM - 9 PM |

<Warning>
  **Promotional SMS** can only be sent between 9 AM and 9 PM. timepay.ai will automatically queue messages outside these hours.
</Warning>

***

## Delivery Reports & Analytics

### SMS Delivery Statuses

| Status        | Description                       |
| ------------- | --------------------------------- |
| **Submitted** | Sent to SMS gateway               |
| **Delivered** | Successfully delivered to handset |
| **Failed**    | Delivery failed — see error code  |
| **Pending**   | Awaiting delivery confirmation    |
| **Rejected**  | Rejected by DLT / carrier         |

### Common Error Codes

| Code                     | Meaning                          | Resolution                      |
| ------------------------ | -------------------------------- | ------------------------------- |
| `DLT_TEMPLATE_NOT_FOUND` | Template not registered/approved | Register template on DLT portal |
| `DLT_ENTITY_NOT_FOUND`   | PE ID invalid                    | Verify Entity ID                |
| `DLT_TM_NOT_LINKED`      | PE-TM linking incomplete         | Complete linking process        |
| `INVALID_SENDER`         | Sender ID not approved           | Register Sender ID on DLT       |
| `BLACKLISTED`            | Number in DND registry           | Remove from campaign            |
| `INVALID_NUMBER`         | Phone number format incorrect    | Verify number format            |

### Analytics

Track SMS performance in the campaign dashboard:

| Metric                | Description            |
| --------------------- | ---------------------- |
| **Total Sent**        | SMS messages sent      |
| **Delivered**         | Successfully delivered |
| **Failed**            | Delivery failures      |
| **Delivery Rate**     | % successful delivery  |
| **Avg Delivery Time** | Time to deliver        |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Keep Messages Concise" icon="text-size">
    * SMS has 160 character limit per segment
    * Multi-part SMS cost more and may have delivery issues
    * Get to the point quickly
  </Accordion>

  <Accordion title="Use Clear Sender IDs" icon="id-badge">
    * Use recognizable brand names (e.g., `HDFC`, `AMAZON`)
    * Avoid generic headers that look like spam
    * Match sender ID to your brand
  </Accordion>

  <Accordion title="Include Call-to-Action" icon="mouse-pointer">
    * Clear next steps (Pay now, Call us, Visit link)
    * Short URLs if possible
    * Make action easy to complete
  </Accordion>

  <Accordion title="Respect Timing" icon="clock">
    * Don't send late night or early morning
    * Promotional: Only 9 AM - 9 PM
    * Consider customer timezone
  </Accordion>

  <Accordion title="Monitor Delivery Rates" icon="chart-line">
    * Track delivery rates regularly
    * Investigate failures promptly
    * Clean invalid numbers from lists
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="SMS not being sent" icon="circle-exclamation">
    **Possible causes:**

    * PE-TM linking not complete
    * Template not approved on DLT
    * Sender ID not registered
    * API credentials invalid

    **Fix:** Verify DLT setup. Check error in campaign logs.
  </Accordion>

  <Accordion title="Template mismatch error" icon="file-excel">
    **Possible causes:**

    * Content doesn't match DLT-registered template exactly
    * Variable count mismatch
    * Extra spaces or characters

    **Fix:** Ensure template content matches DLT registration character-by-character.
  </Accordion>

  <Accordion title="Low delivery rates" icon="chart-line-down">
    **Possible causes:**

    * Invalid/inactive phone numbers
    * Numbers on DND registry
    * Carrier issues
    * Template flagged as spam

    **Fix:** Clean your contact list. Check template quality.
  </Accordion>

  <Accordion title="Messages going to spam" icon="shield-exclamation">
    **Possible causes:**

    * Using promotional content in transactional template
    * Generic sender ID
    * Aggressive language

    **Fix:** Review template content. Use appropriate category.
  </Accordion>
</AccordionGroup>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Do I need DLT registration for all SMS?" icon="circle-question">
    **Yes**, for sending SMS to Indian numbers, DLT registration is mandatory as per TRAI regulations. This applies to all commercial and transactional messages.
  </Accordion>

  <Accordion title="How long does DLT registration take?" icon="clock">
    Typically 3-7 business days, depending on the DLT operator and document verification.
  </Accordion>

  <Accordion title="Can I use multiple sender IDs?" icon="layer-group">
    Yes, you can register multiple sender IDs and use different ones for different campaigns or message types.
  </Accordion>

  <Accordion title="What happens if PE-TM linking expires?" icon="calendar-xmark">
    You'll need to renew the linking on your DLT portal. Messages will fail until linking is restored.
  </Accordion>

  <Accordion title="Do you support international SMS?" icon="globe">
    Yes, contact support for international SMS setup. DLT requirements vary by country.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Create a Campaign" icon="bullhorn" href="/campaigns">
    Build a campaign with SMS follow-ups
  </Card>

  <Card title="WhatsApp Integration" icon="whatsapp" href="/integrations/whatsapp">
    Add WhatsApp to your channels
  </Card>

  <Card title="Workflow Builder" icon="diagram-project" href="/workflows/overview">
    Design multi-channel workflows
  </Card>

  <Card title="Contact Support" icon="headset" href="mailto:support@timepay.ai">
    Get help with DLT setup or custom providers
  </Card>
</CardGroup>