Inbound SMS
Rent a dedicated phone number from Agile Telecom and receive every SMS sent to it — perfect for two-way customer support, opt-in/opt-out flows, appointment confirmations and lightweight chatbots.
For the full API contract, see the Inbound SMS API reference.
Delivery Methods
You choose how incoming messages reach you when you rent the number:
| Method | Best for | Latency |
|---|---|---|
| Webhook (HTTP POST) | Automation, databases, real-time chatbots. | Seconds |
| Low-volume use cases, manual workflows, audit trails. | Email-typical |
You can change the delivery method at any time from Numbers → Inbound in the wholesale portal.
Webhook Flow (Recommended)
The platform sends a form-encoded POST to your URL with the message data, and expects exactly +OK in the response body within 30 seconds.
Inbound POST parameters
| Parameter | Description | Example |
|---|---|---|
originator | Sender phone number (international) | +393351234567 |
destination | Your rented SIM number | +393331234333 |
date_time | Reception timestamp YYYYMMDDHHMMSS | 20260514102301 |
text | SMS body | News ON |
Mandatory response
+OK
If your server does not reply with +OK within 30 seconds, the delivery is treated as failed and retried after 15 minutes. After 3 failed attempts the message is discarded.
Keep your webhook fast: parse, queue, respond +OK. Heavy work (NLP, DB writes, calls to other services) belongs in a background worker.
Email Flow
Inbound messages arrive from smsin@agiletelecom.com with subject Agile Telecom -- SMS received and a structured body containing the same fields as the webhook payload (From / To / Date/Time / Body). Useful when:
- You don't have a public HTTPS endpoint.
- Volume is low and human review is acceptable.
- You want an audit trail of inbound traffic in your mailbox.
Common Patterns
Opt-out keywords — Implement STOP / UNSUBSCRIBE handling on your webhook. Mark the originator as opted-out in your database and stop sending campaigns to that number. Regulators in most countries require it.
Two-factor codes — Accept reply codes for confirmation flows; the webhook is the most reliable channel.
Automated answers — Trigger an outbound send from the webhook handler to confirm receipt or guide the user.
Security Checklist
- HTTPS only. Reject any inbound webhook traffic on plain HTTP.
- Allowlist Agile Telecom source IPs if your firewall supports it. Get the current list from support.
- Validate
destination— Make sure the SIM number matches one you own; ignore spoofed traffic. - Rate-limit your responder to avoid being weaponised as an outbound spammer.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Messages keep being retried | Server returned something other than +OK (or timed out) | Reduce work in the handler, queue async |
| Duplicate processing | Same message retried after a slow +OK | Use originator + date_time + text as dedup key |
| Missing inbound traffic | Number not bound to the right delivery method | Check the routing in the wholesale portal |
Next Steps
- Inbound SMS API reference — Full request/response contract.
- Best Practices — Opt-out compliance, rate limiting.
- Error Handling — Recovery patterns.