Developer documentation
Send SMS and one-time codes from your own software with a simple JSON API. Every example below works as written once you put in your key.
Getting started
- 1. Create an account and sign in to the portal.
- 2. Request a sender ID (the name people see) under Sender IDs. It is approved before you can use it.
- 3. Under Connect your app, create an API key. It is shown once: store it as a secret.
- 4. Add balance, then call the API.
Base URL: https://telecom.hostbotics.net/api. All requests and responses are JSON over HTTPS.
Authentication
Send your API key in the x-api-key header on every request. Authorization: Bearer YOUR_API_KEY also works. Keys are tied to your account and can be revoked at any time from the portal. Never put a key in a web page or a mobile app: call the API from your server.
Send an SMS
POST /v1/sms/send accepts the message and returns straight away. Delivery happens afterwards: follow it with the status endpoint or a webhook.
curl -X POST https://telecom.hostbotics.net/api/v1/sms/send \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{"to":"+96170123456","from":"MYSHOP","text":"Your order #4821 has shipped."}'| Field | Type | Description |
|---|---|---|
to | string | Phone number with country code, e.g. +96170123456. |
from | string, optional | An approved sender ID. Omit it to use your default sender. |
text | string | Message text, up to 1600 characters. Use either text or templateId. |
templateId | uuid | Send an approved template instead of free text. |
variables | object | Values for the template’s {{placeholders}} (up to 10). |
reference | string, optional | Your own id (up to 64 characters). It comes back in the status and the webhook. |
202 Accepted
{
"id": "3f0c7b3e-0d1e-4a52-9c7e-0b9d9c4c1a11",
"status": "QUEUED",
"to": "+96170123456",
"from": "MYSHOP",
"parts": 1,
"encoding": "GSM7",
"countryCode": "961",
"mccMnc": "41501"
}Message status
GET /v1/sms/{id} returns where a message is. Statuses move QUEUED → SENT → DELIVRD. The others are final failures: UNDELIV (the phone or network did not accept it), EXPIRED, FAILED and REJECTED (refused before sending, nothing charged). A message that fails is refunded.
curl https://telecom.hostbotics.net/api/v1/sms/MESSAGE_ID -H "x-api-key: YOUR_API_KEY"200 OK
{
"id": "3f0c7b3e-0d1e-4a52-9c7e-0b9d9c4c1a11",
"status": "DELIVRD",
"to": "+96170123456", "from": "MYSHOP", "parts": 1,
"price": "0.030000", "errorCode": null, "reference": "order-4821",
"createdAt": "2026-11-16T09:00:00.000Z", "sentAt": "2026-11-16T09:00:01.000Z", "deliveredAt": "2026-11-16T09:00:03.000Z"
}Delivery webhooks
Instead of polling, give us a URL (portal → Connect your app → Delivery webhooks). When a message reaches a final state we POST a signed event to it. Your endpoint should answer with any 2xx within 8 seconds; otherwise we retry up to 6 times with growing delays.
POST https://your-server.example/hooks/sms
x-hostbotics-event: message.status
x-hostbotics-signature: t=1700000000,v1=3f5a…
{
"id": "evt_3f0c7b3e-…_DELIVRD",
"type": "message.status",
"createdAt": "2026-11-16T09:00:03.120Z",
"data": {
"id": "3f0c7b3e-…", "to": "+96170123456", "from": "MYSHOP",
"status": "DELIVRD", "state": "delivered", "parts": 1, "price": "0.030000",
"error": null, "reference": "order-4821", "batchId": null,
"createdAt": "…", "sentAt": "…", "deliveredAt": "…"
}
}Always verify the signature. It is an HMAC-SHA256 of <t>.<raw body> using your webhook secret (shown once when you create it). Reject events older than five minutes, and treat the event id as the key to ignore duplicates.
# The signature is HMAC-SHA256 over "<t>.<raw body>", hex encoded.
# Header: X-HostBotics-Signature: t=1700000000,v1=3f5a...Verification codes (OTP)
Confirm that someone owns a phone number, or add a second step to sign-in, with two calls. We generate the code, send it by SMS, and check what your user types. The code is never returned by the API and is stored only as a hash.
- 1.
POST /v1/verify/start: sends the code. Keep the returnedid. - 2. Ask the user for the code.
- 3.
POST /v1/verify/check: returnsvalid: truewhen it matches.
curl -X POST https://telecom.hostbotics.net/api/v1/verify/start \
-H "x-api-key: YOUR_API_KEY" -H "content-type: application/json" \
-d '{"to":"+96170123456","from":"MYSHOP","brand":"My Shop"}'| Start field | Description |
|---|---|
to | Phone number with country code. |
from | Approved sender ID (optional if you have a default). |
brand | Name in the message: “My Shop: your verification code is 482913…”. Defaults to your account name. |
length | Code length, 4 to 8 digits. Default 6. |
ttl | Seconds the code stays valid, 60 to 900. Default 300. |
locale | en (default) or ar for an Arabic message. |
text | Your own wording. It must contain {{code}} ({{brand}} and {{minutes}} are filled in too). |
templateId | An approved template whose body contains {{code}}, instead of text. |
201 Created
{ "id": "6a1f…", "status": "PENDING", "to": "+96170123456", "expiresAt": "2026-11-16T09:05:00.000Z",
"attemptsLeft": 5, "from": "MYSHOP", "messageId": "3f0c…", "parts": 1, "length": 6 }curl -X POST https://telecom.hostbotics.net/api/v1/verify/check \
-H "x-api-key: YOUR_API_KEY" -H "content-type: application/json" \
-d '{"id":"VERIFICATION_ID","code":"482913"}'200 OK
{ "valid": true, "id": "6a1f…", "status": "APPROVED", "attemptsLeft": 4, … }
{ "valid": false, "id": "6a1f…", "status": "PENDING", "attemptsLeft": 3, … } // wrong code| Status | Meaning |
|---|---|
PENDING | Waiting for the right code. |
APPROVED | Confirmed. A code works once. |
EXPIRED | The time ran out. Start a new one. |
LOCKED | Five wrong guesses. Start a new one. |
CANCELED | A newer code was sent to the same number, which replaces this one. |
You can also confirm with the phone number instead of the id: send {"to": "+96170123456", "code": "482913"}. GET /v1/verify/{id} returns the current status. At most 5 codes can be sent to one number per 10 minutes. Direct accounts pay a small fee for each confirmed code on top of the SMS price (see Pricing); wrong or unused codes cost nothing extra.
Errors
Errors are JSON: { "error": { "code": "SENDER_NOT_APPROVED", "message": "…" } }. Nothing is charged for a refused request.
| HTTP | Code | What to do |
|---|---|---|
| 401 | UNAUTHORIZED | The key is missing, wrong or revoked. |
| 402 | INSUFFICIENT_BALANCE | Verification calls only: add funds to your wallet. For plain SMS a low balance shows up later as a REJECTED message. |
| 429 | TOO_MANY_REQUESTS | Too many codes were sent to one number in 10 minutes (verification). |
| 422 | INVALID_RECIPIENT, INVALID_SENDER | Check the number (with country code) and the sender ID format. |
| 422 | NO_SENDER, SENDER_NOT_APPROVED, SENDER_NOT_ALLOWED | Use an approved sender ID, approved for that country. |
| 422 | UNKNOWN_TEMPLATE, TEMPLATE_NOT_APPROVED, TEMPLATE_VARIABLES_MISSING | Use an approved template and give every variable. |
| 422 | EMPTY_TEXT, TOO_LONG, TEXT_OR_TEMPLATE | Send text or a template (not both); at most 10 parts. |
| 422 | COUNTRY_DISABLED, COUNTRY_NOT_ALLOWED, DESTINATION_BLOCKED | We cannot send to that destination from your account. |
| 422 | SENDER_BLOCKED, CONTENT_BLOCKED | The sender or the wording is not allowed. |
| 422 | RECIPIENT_LIMIT | Too many messages to that number this hour. |
| 422 | DEMO_LIMIT_REACHED | A demo account has used all of its test messages. Ask us to activate it. |
| 429 | RATE_LIMITED | Over your speed limit. Wait for the Retry-After seconds. |
| 503 | QUEUE_UNAVAILABLE | Temporary problem: retry. |
A message accepted with 202 can still end up REJECTED or FAILED later (for example INSUFFICIENT_BALANCE or DAILY_LIMIT, your account’s daily spending limit). The status endpoint and the webhook tell you which, and a refused message is never charged.
Limits and message size
| Limit | Value |
|---|---|
| Speed | Standard accounts: 20 messages per second. Pro: 100. Enterprise: 500. Ask us to raise yours. |
| Text length | Up to 1600 characters, at most 10 parts. |
| Standard (GSM-7) text | 160 characters in one part; 153 per part when split. |
| Unicode text (Arabic, emoji…) | 70 characters in one part; 67 per part when split. |
| Phone numbers | International format with country code. Spaces and dashes are tolerated. |
| Webhook retries | 6 attempts, 8 second timeout each. |
Each part is priced separately. Use the calculator on the Pricing page to see how a message is split.
SMPP
For high-volume traffic we also support SMPP v3.4 (transceiver, receiver and transmitter binds, with delivery receipts). SMPP is set up per account with an IP allow-list. Contact us for the host, port and credentials.
Postman collection
Import the collection, set apiKey to your key, and try every endpoint above. It stores the last message and verification id for you, so you can run the requests in order.
