SMS & SMPP

Msghub supports SMS messaging via two protocols: HTTP API (for standard messaging) and SMPP (for high-volume, time-sensitive messaging). Choose the right protocol based on your use case.

SMS via HTTP API

HTTP API is the standard way to send SMS. It's simple, reliable, and suitable for most use cases.

Sending an SMS

curl -X POST \
  https://your-msghub.com/api/v1/messages/send \
  -H "X-API-Key: mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+919876543210",
    "body": "Hi Rahul, your order ORD-4821 has shipped!"
  }'

Response

{
  "messageId": "msg_abc123",
  "channel": "sms",
  "to": "+919876543210",
  "status": "queued",
  "createdAt": "2024-04-08T10:30:00Z"
}

Message Parameters

Parameter	Type	Required	Description
`channel`	string	Yes	Must be `"sms"`
`to`	string	Yes	Recipient phone number (E.164 format, e.g., +919876543210)
`body`	string	Yes	Message text (up to 160 characters for single SMS, 1000+ with concatenation)
`senderId`	string	No	Sender ID (if supported by your SMS gateway)
`scheduleAt`	ISO 8601	No	Schedule message for future delivery
`tags`	array	No	Tags for tracking (e.g., ["order_confirmation", "vip"])

Character Limits

Single SMS: 160 characters (GSM-7 encoding) or 70 characters (Unicode)
Concatenated SMS: Multiple SMS concatenated automatically. Each segment is 153 characters (GSM-7) or 67 characters (Unicode)

Example: A 300-character message will be sent as 2 SMS (153 + 147 characters).

Delivery Status

After sending, you'll receive webhook events for delivery status:

{
  "event": "message.delivered",
  "messageId": "msg_abc123",
  "channel": "sms",
  "status": "delivered",
  "deliveredAt": "2024-04-08T10:30:05Z",
  "dlr": {
    "operator": "Airtel",
    "code": "DELIVRD"
  }
}

Possible statuses:

delivered — Message successfully delivered to recipient
failed — Message delivery failed
bounced — Invalid phone number or carrier rejection
read — Message read (if supported by carrier)

SMS via SMPP

SMPP (Short Message Peer-to-Peer) is a telecom-grade protocol used by carriers internally. Use SMPP for high-volume, time-sensitive messaging.

Why Use SMPP?

Metric	HTTP API	SMPP
Throughput	30-50 messages/second	1,000+ messages/second
Latency	5-30 seconds	Under 3 seconds
Best for	Standard campaigns	OTPs, flash sales, alerts
Setup	Simple	Requires SMPP credentials

SMPP Setup

Go to Settings → Channels → SMS
Select SMPP
Enter your SMPP gateway credentials:
- Host — SMPP server hostname or IP
- Port — SMPP port (usually 2775)
- Username — SMPP username
- Password — SMPP password
- System ID — Optional system identifier
Click Test Connection
Once verified, click Save

Sending via SMPP

The API is identical to HTTP API. Msghub automatically routes to SMPP if configured:

curl -X POST \
  https://your-msghub.com/api/v1/messages/send \
  -H "X-API-Key: mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+919876543210",
    "body": "Your OTP is 482910. Expires in 5 minutes."
  }'

Msghub will automatically use SMPP if:

SMPP is configured in Settings
The message is marked as high-priority (OTP, alert)
Or you explicitly request SMPP routing

SMPP Delivery Reports (DLR)

SMPP provides real-time delivery reports per contact, per operator, per second:

{
  "event": "message.delivered",
  "messageId": "msg_abc123",
  "channel": "sms",
  "status": "delivered",
  "deliveredAt": "2024-04-08T10:30:02Z",
  "dlr": {
    "operator": "Jio",
    "code": "DELIVRD",
    "timestamp": "2024-04-08T10:30:02Z"
  }
}

SMPP Throughput Example

Sending 50,000 SMS via SMPP:

# Using n8n or your automation tool
for i in {1..50000}; do
  curl -X POST https://your-msghub.com/api/v1/messages/send \
    -H "X-API-Key: mk_live_..." \
    -d "{\"channel\": \"sms\", \"to\": \"+91${phone[$i]}\", \"body\": \"Flash sale! 50% off. Ends tonight.\"}"
done

Result: 50,000 messages delivered in ~50 seconds (1,000 TPS).

Bulk SMS Campaigns

Send SMS to multiple contacts at once using the Campaigns API.

Create a Campaign

curl -X POST \
  https://your-msghub.com/api/v1/campaigns \
  -H "X-API-Key: mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Flash Sale",
    "channel": "sms",
    "message": "Flash sale! 50% off everything. Shop now: https://example.com/sale",
    "recipients": {
      "segment": "vip_customers"
    },
    "sendAt": "2024-04-08T18:00:00Z"
  }'

Response

{
  "campaignId": "camp_xyz789",
  "name": "Flash Sale",
  "channel": "sms",
  "status": "scheduled",
  "recipientCount": 50000,
  "scheduledAt": "2024-04-08T18:00:00Z"
}

Monitor Campaign

curl -X GET \
  https://your-msghub.com/api/v1/campaigns/camp_xyz789 \
  -H "X-API-Key: mk_live_..."

Response

{
  "campaignId": "camp_xyz789",
  "name": "Flash Sale",
  "status": "sent",
  "totalRecipients": 50000,
  "delivered": 49500,
  "failed": 500,
  "deliveryRate": 99.0,
  "sentAt": "2024-04-08T18:00:05Z"
}

DLT Compliance

DLT (Distributed Ledger Technology) compliance is mandatory in India (TRAI) and other regions. Msghub handles DLT compliance automatically.

What is DLT?

DLT is a registry of approved SMS templates and sender IDs. Before sending SMS, you must:

Register your sender ID
Register your message templates
Get approval from the telecom authority

DLT Setup in Msghub

Go to Settings → Compliance → DLT
Enter your DLT credentials:
- Entity ID — Your registered entity ID
- Sender ID — Your registered sender ID
Add your approved templates:
- Template ID — DLT template ID
- Template Text — The approved message text
Click Save

Sending DLT-Compliant SMS

When you send an SMS, Msghub automatically:

Matches your message to an approved template
Includes the template ID in the SMPP request
Validates the sender ID

curl -X POST \
  https://your-msghub.com/api/v1/messages/send \
  -H "X-API-Key: mk_live_..." \
  -d '{
    "channel": "sms",
    "to": "+919876543210",
    "templateId": "1007161234567890123",
    "parameters": {
      "orderId": "ORD-4821"
    }
  }'

DLT Template Variables

Templates can include variables (placeholders) that are filled at send time:

Template (registered with DLT):

Hi {name}, your order {orderId} has shipped. Track it here: {trackingUrl}

Send request:

{
  "channel": "sms",
  "to": "+919876543210",
  "templateId": "1007161234567890123",
  "parameters": {
    "name": "Rahul",
    "orderId": "ORD-4821",
    "trackingUrl": "https://track.example.com/ORD-4821"
  }
}

DND (Do Not Disturb) Handling

DND compliance is mandatory. Msghub automatically:

Checks if a number is on the DND list
Blocks messages to DND numbers
Logs DND violations for compliance

DND Status

When you send to a DND number, you'll receive:

{
  "event": "message.failed",
  "messageId": "msg_abc123",
  "status": "failed",
  "reason": "dnd_violation",
  "message": "Number is on DND list"
}

Opt-In/Opt-Out Management

Msghub tracks customer consent:

# Mark a contact as opted-in
curl -X POST \
  https://your-msghub.com/api/v1/contacts/contact_123/consent \
  -H "X-API-Key: mk_live_..." \
  -d '{
    "channel": "sms",
    "status": "opted_in",
    "timestamp": "2024-04-08T10:00:00Z"
  }'

# Mark a contact as opted-out
curl -X POST \
  https://your-msghub.com/api/v1/contacts/contact_123/consent \
  -H "X-API-Key: mk_live_..." \
  -d '{
    "channel": "sms",
    "status": "opted_out",
    "timestamp": "2024-04-08T10:00:00Z"
  }'

Bring Your Own SMS Gateway

Connect your existing SMS gateway (MSG91, Kaleyra, Gupshup, etc.) to Msghub.

Supported Gateways

MSG91 — HTTP API
Kaleyra — SMPP
Gupshup — HTTP API
Twilio — HTTP API
Any SMPP provider — Raw SMPP protocol

Setup

Go to Settings → Channels → SMS
Select Custom Gateway
Choose your gateway type (HTTP or SMPP)
Enter your credentials:
- API Endpoint (for HTTP)
- SMPP Host/Port/Username/Password (for SMPP)
Click Test Connection
Click Save

Cost

You pay your SMS gateway directly. Msghub doesn't mark up the cost—you only pay for the platform subscription and the actual messages sent.

Best Practices

Message Content

Keep it short — Aim for under 160 characters to avoid concatenation
Include a call-to-action — "Click here", "Reply YES", "Call 1800-XXXX"
Personalize — Use customer name and order details
Avoid spam words — Don't use ALL CAPS, excessive punctuation, or spam triggers

Timing

Send during business hours — 9 AM - 9 PM for best engagement
Avoid weekends — Unless it's a time-sensitive alert
Consider time zones — Schedule for recipient's local time

Compliance

Always get consent — Before sending promotional SMS
Include opt-out — "Reply STOP to unsubscribe"
Respect DND — Never send to DND numbers
Keep records — Log all consent and opt-outs

Troubleshooting

Messages not delivering

Check phone number format — Must be E.164 format (+919876543210)
Check DND status — Is the number on the DND list?
Check DLT compliance — Is the template approved?
Check gateway status — Is your SMS gateway connected?

High failure rate

Check message content — Does it match an approved DLT template?
Check sender ID — Is it registered and approved?
Check gateway logs — Contact your SMS gateway for error details

Slow delivery

Use SMPP — HTTP API is slower than SMPP
Check gateway load — Is your gateway overloaded?
Check network — Is there a connectivity issue?

SMS via HTTP API

Sending an SMS

Response

Message Parameters

Character Limits

Delivery Status

SMS via SMPP

Why Use SMPP?

SMPP Setup

Sending via SMPP

SMPP Delivery Reports (DLR)

SMPP Throughput Example

Bulk SMS Campaigns

Create a Campaign

Response

Monitor Campaign

Response

DLT Compliance

What is DLT?

DLT Setup in Msghub

Sending DLT-Compliant SMS

DLT Template Variables

DND (Do Not Disturb) Handling

DND Status

Opt-In/Opt-Out Management

Bring Your Own SMS Gateway

Supported Gateways

Setup

Cost

Best Practices

Message Content

Timing

Compliance

Troubleshooting

Messages not delivering

High failure rate

Slow delivery

See Also