Teleos API
Teleos sends and receives SMS through Android phones linked to your account. The v2 API is REST + JSON. Base URL:
https://teleos.in/sms-login/v2
Every response is {"success": true, "data": …} or {"success": false, "error": {"code", "type", "message"}}. Timestamps are ISO-8601 UTC.
Authentication
Create an account, then copy your API key from the dashboard (API or Teleos Pro → Developer API v2). Send it as a Bearer token:
Authorization: Bearer YOUR_API_KEY
Keep the key secret — anyone with it can send from your phones. Regenerating it in the dashboard revokes the old key immediately.
Errors & limits
| HTTP | type | Meaning |
|---|---|---|
| 400 | invalid_request | Missing/invalid field (message explains which) |
| 401 | unauthorized | Missing or wrong API key |
| 402 | insufficient_credits / subscription_expired | Top up or renew your plan |
| 403 | forbidden | Limit reached (e.g. webhooks per account) |
| 404 | not_found | Unknown endpoint or ID |
| 429 | rate_limited | Too many requests — default 300/min per account; OTP has extra per-number caps |
Each SIM sends roughly one SMS per second and your operator may cap daily SMS per SIM; add phones and use round-robin routing for more throughput.
GET/me
Account, credits (null = unlimited), plan expiry, device count and routing preferences.
curl https://teleos.in/sms-login/v2/me -H "Authorization: Bearer YOUR_API_KEY"
GET/devices
Phones on your account (owned and shared) with online (seen in the last 10 minutes), app version and SIMs (slot, name, number).
POST/messages
| Field | Type | |
|---|---|---|
| to | string | string[] | Required. Number(s) with country code; comma-separated string or array (max 1000). |
| message | string | Required. Up to 2000 characters. Supports spintax {Hi|Hello} and %random-4%. |
| device_id | int | Optional phone from /devices. Default: your routing setting (primary / round-robin / random). |
| sim | int | Optional SIM slot on that phone. |
| schedule_at | ISO time | unix | Optional future send time. |
| priority | bool | Optional; jump the phone's queue. |
curl -X POST https://teleos.in/sms-login/v2/messages \
-H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"to":["+919876543210","+919812345678"],"message":"Sale ends tonight!"}'
201 → {"success":true,"data":{"queued":2,"messages":[{"id":694701,"status":"Pending",…}]}}Status lifecycle: Scheduled → Pending → Queued → Sent → Delivered (or Failed). Delivery reports depend on the operator and the "report delivery" setting.
GET/messages
Filters: status, direction (inbound|outbound), number, since_id (ascending, for polling), before_id (paging back), limit (≤200). GET/messages/{id} returns one message with its live status.
GET/inbox
Received SMS only. Poll with since_id = last ID you stored, or better, use the message.received webhook.
OTP
POST/otp/send
| Field | Default | |
|---|---|---|
| phone | — | Required, with country code. |
| length | 6 | 4–8 digits. |
| expires_in | 300 | Seconds, 60–900. |
| max_attempts | 5 | Wrong tries allowed per code, 1–10. |
| cooldown | 60 | Seconds before another code can be sent to the same number, 30–600. |
| purpose | default | Label so login/signup/payment codes don't clash. |
| template | platform default | Your SMS text; must contain {code}. {minutes} and {app} are also replaced. |
| device_id, sim | routing | Optional phone/SIM. |
The code is never returned. A number can receive at most 5 codes per 24 hours (per account).
POST/otp/verify
Body: phone, code, purpose. Returns {"verified":true} or {"verified":false,"reason":"mismatch|expired|too_many_attempts|already_used|no_otp","attempts_left":3}. A verified code cannot be reused.
import requests
H = {'Authorization': 'Bearer YOUR_API_KEY'}
requests.post('https://teleos.in/sms-login/v2/otp/send', headers=H, json={'phone': '+919876543210', 'purpose': 'signup'})
ok = requests.post('https://teleos.in/sms-login/v2/otp/verify', headers=H,
json={'phone': '+919876543210', 'code': user_code, 'purpose': 'signup'}).json()['data']['verified']
Webhooks
GET/webhooks · POST/webhooks {"url":"https://…","events":["message.received","message.status","otp.verified"]} · DELETE/webhooks/{id}. Also manageable in the dashboard (Teleos Pro → Webhooks). URLs must be public HTTPS.
Each delivery is a JSON POST with headers X-Teleos-Event, X-Teleos-Timestamp and X-Teleos-Signature: sha256=<hex>, where the signature is HMAC-SHA256 of timestamp + "." + raw_body using the secret returned when you created the webhook.
{
"id": "67da80ca20b10c7f",
"event": "message.received",
"created_at": "2026-11-13T17:12:58Z",
"data": {"id": 694666, "number": "+919000000001", "message": "Hi, I want a demo",
"status": "Received", "direction": "inbound", "device_id": 385, "sim": 0}
}// PHP verification
$body = file_get_contents('php://input');
$sig = 'sha256=' . hash_hmac('sha256', $_SERVER['HTTP_X_TELEOS_TIMESTAMP'] . '.' . $body, $secret);
if (!hash_equals($sig, $_SERVER['HTTP_X_TELEOS_SIGNATURE'] ?? '')) { http_response_code(401); exit; }Answer with any 2xx within 10 seconds. Failed deliveries retry after 1m, 3m, 10m, 30m, 2h, 6h, 12h and then daily — 10 attempts in total. message.status events include previous_status.
MCP server for AI agents
Endpoint https://teleos.in/mcp (Streamable HTTP), authenticated with your API key.
# Claude Code
claude mcp add --transport http teleos https://teleos.in/mcp \
--header "Authorization: Bearer YOUR_API_KEY"
# Cursor (~/.cursor/mcp.json) / other clients
{"mcpServers":{"teleos":{"type":"http","url":"https://teleos.in/mcp",
"headers":{"Authorization":"Bearer YOUR_API_KEY"}}}}
# Claude Desktop (via mcp-remote, needs Node.js)
{"mcpServers":{"teleos":{"command":"npx","args":["-y","mcp-remote","https://teleos.in/mcp",
"--header","Authorization: Bearer YOUR_API_KEY"]}}}| Tool | What it does |
|---|---|
| setup_teleos | Validates the key; shows account, balance and phones |
| send_sms | to, message, optional device_id, sim |
| send_otp / verify_otp | Same rules as the OTP API |
| wait_for_otp | Waits up to 50 s for an incoming SMS containing a 4–8 digit code and returns it (timeout_seconds, from, since_minutes) |
| get_messages | History with filters, or one message by id |
| list_devices / get_balance | Phones, SIMs, online state / credits and expiry |
| create_webhook | Registers a signed HTTPS callback |
Integrations
- WordPress / WooCommerce / Contact Form 7 — download the plugin from Teleos Pro → Integrations. Order SMS, owner alerts and the
[teleos_otp_form]shortcode. - Shopify — Settings → Notifications → Webhooks → Order creation (JSON) → your automation URL with
&source=shopify. - Zapier, Make, n8n, Pabbly — send with an HTTP/Webhook action to your automation URL (
{"to","message"}, no headers needed); receive with webhooks. - Google Sheets — Apps Script for bulk SMS from rows and an auto-filled Inbox sheet.
Classic API
The original endpoints under /sms-login/services/*.php (send.php, get-messages.php, get-devices.php…) remain available and unchanged, so existing integrations keep working. Their reference is on the API page inside the dashboard.