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. 1. Create an account and sign in to the portal.
  2. 2. Request a sender ID (the name people see) under Sender IDs. It is approved before you can use it.
  3. 3. Under Connect your app, create an API key. It is shown once: store it as a secret.
  4. 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."}'
FieldTypeDescription
tostringPhone number with country code, e.g. +96170123456.
fromstring, optionalAn approved sender ID. Omit it to use your default sender.
textstringMessage text, up to 1600 characters. Use either text or templateId.
templateIduuidSend an approved template instead of free text.
variablesobjectValues for the template’s {{placeholders}} (up to 10).
referencestring, optionalYour 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. 1. POST /v1/verify/start: sends the code. Keep the returned id.
  2. 2. Ask the user for the code.
  3. 3. POST /v1/verify/check: returns valid: true when 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 fieldDescription
toPhone number with country code.
fromApproved sender ID (optional if you have a default).
brandName in the message: “My Shop: your verification code is 482913…”. Defaults to your account name.
lengthCode length, 4 to 8 digits. Default 6.
ttlSeconds the code stays valid, 60 to 900. Default 300.
localeen (default) or ar for an Arabic message.
textYour own wording. It must contain {{code}} ({{brand}} and {{minutes}} are filled in too).
templateIdAn 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
StatusMeaning
PENDINGWaiting for the right code.
APPROVEDConfirmed. A code works once.
EXPIREDThe time ran out. Start a new one.
LOCKEDFive wrong guesses. Start a new one.
CANCELEDA 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.

HTTPCodeWhat to do
401UNAUTHORIZEDThe key is missing, wrong or revoked.
402INSUFFICIENT_BALANCEVerification calls only: add funds to your wallet. For plain SMS a low balance shows up later as a REJECTED message.
429TOO_MANY_REQUESTSToo many codes were sent to one number in 10 minutes (verification).
422INVALID_RECIPIENT, INVALID_SENDERCheck the number (with country code) and the sender ID format.
422NO_SENDER, SENDER_NOT_APPROVED, SENDER_NOT_ALLOWEDUse an approved sender ID, approved for that country.
422UNKNOWN_TEMPLATE, TEMPLATE_NOT_APPROVED, TEMPLATE_VARIABLES_MISSINGUse an approved template and give every variable.
422EMPTY_TEXT, TOO_LONG, TEXT_OR_TEMPLATESend text or a template (not both); at most 10 parts.
422COUNTRY_DISABLED, COUNTRY_NOT_ALLOWED, DESTINATION_BLOCKEDWe cannot send to that destination from your account.
422SENDER_BLOCKED, CONTENT_BLOCKEDThe sender or the wording is not allowed.
422RECIPIENT_LIMITToo many messages to that number this hour.
422DEMO_LIMIT_REACHEDA demo account has used all of its test messages. Ask us to activate it.
429RATE_LIMITEDOver your speed limit. Wait for the Retry-After seconds.
503QUEUE_UNAVAILABLETemporary 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

LimitValue
SpeedStandard accounts: 20 messages per second. Pro: 100. Enterprise: 500. Ask us to raise yours.
Text lengthUp to 1600 characters, at most 10 parts.
Standard (GSM-7) text160 characters in one part; 153 per part when split.
Unicode text (Arabic, emoji…)70 characters in one part; 67 per part when split.
Phone numbersInternational format with country code. Spaces and dashes are tolerated.
Webhook retries6 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.

Download for Postman