Документація SMS API для надсилання з вашого власного коду

Аутентифікація

Надсилайте ваш ключ у заголовку Authorization: Authorization: Bearer sso_live_.... Ключі мають 49 символів і починаються з sso_live_. До 5 ключів на рахунок; скасуйте один у робочому просторі, і він перестане працювати негайно. Прайс-лист є публічним і не потребує ключа.

Помилки

Помилки використовують HTTP статусні коди та JSON тіло зі стабільним кодом і реченням, яке можна показати людині. Нічого не стягується, якщо запит завершується помилкою.

HTTP/1.1 402 Payment Required
{ "error": { "code": "insufficient_credit", "message": "Short by $3.20. Add funds to send.", "total": "8.62480", "credit": "5.42000" } }

Обмеження

• 240 запитів за хвилину на ключ, відображається в X-RateLimit-Limit, X-RateLimit-Remaining та X-RateLimit-Reset (unix секунди).
• 5,000 номерів на запит, 2,000 символів у тексті, 10 сегментів у повідомленні.
• Повідомлення надсилаються зі швидкістю до 300 на хвилину для одного акаунта.
• send_at від 10 хвилин до 30 днів наперед.

Ціни

GET/api/v1/prices

GET/api/v1/prices/{country}

Ціна за повідомлення (один сегмент) для кожної країни, у USD з 5 знаками після коми. Ключ не потрібен.

{ "price": { "country": "GB", "name": "United Kingdom", "dial_code": "+44", "price_usd": "0.00868" }, "updated": "2026-11-07" }

Баланс рахунку

GET/api/v1/account

{ "account": "SO8K2M4Q7X9TBA", "credit_usd": "41.27660", "currency": "USD" }

Оцінити вартість

POST/api/v1/costs

Приймає ті самі дані, що й надсилання, і повертає вартість без фактичного відправлення чи списання коштів. Власний об’єднаний текст кожного отримувача визначає кількість сегментів, тому сума точна.

{
  "recipients": 2, "segments_min": 1, "segments_max": 1, "encoding": "gsm7", "messages_billed": 2,
  "total_usd": "0.01426", "credit_usd": "41.27660", "enough_credit": true,
  "countries": [ { "country": "GB", "recipients": 1, "price_usd": "0.00868", "subtotal_usd": "0.00868" },
                 { "country": "US", "recipients": 1, "price_usd": "0.00558", "subtotal_usd": "0.00558" } ],
  "dropped": [], "too_long": null
}

Створити розсилку

POST/api/v1/sends

Один текст для одного або багатьох номерів. Кошти за все надсилання списуються при його прийнятті; невдалі повідомлення повертаються по одному.

HTTP/1.1 201 Created
{
  "send": { "id": "CA7Q29XMAB4DFK", "status": "queued", "source": "api", "recipients": 2, "segments_max": 1,
            "encoding": "gsm7", "cost_usd": "0.01426", "refunded_usd": "0.00000", "client_ref": "bookings-1107",
            "send_at": null, "created_at": "2026-11-07T10:12:03.120Z", "started_at": null, "finished_at": null },
  "dropped": [ { "value": "+4412", "code": "too_short", "message": "Too short" } ]
}

Номери, які не можна надіслати, перелічені в dropped і ніколи не списуються. Коди: no_country_code, too_short, too_long, not_a_number, wrong_length, not_covered, duplicate та suppressed (у вашому списку не надсилання).

Отримати або переглянути розсилки

GET/api/v1/sends/{id}

GET/api/v1/sends?limit=25&before={id}

Одне надсилання включає counts для кожного статусу повідомлення. Списки відсортовані від новіших до старіших; передайте next_before як before для наступної сторінки. Надсилання з робочого простору також відображаються тут, з source: "web".

Повідомлення

GET/api/v1/sends/{id}/messages?status=failed&limit=100

GET/api/v1/messages/{id}

{ "message": { "id": "MS3D8RW0K2QJ7N", "send_id": "CA7Q29XMAB4DFK", "to": "+447700900461", "country": "GB",
  "segments": 1, "price_usd": "0.00868", "status": "delivered", "reason": null, "reason_text": null,
  "created_at": "2026-11-07T10:12:03.120Z", "sent_at": "2026-11-07T10:12:04.010Z", "done_at": "2026-11-07T10:12:09.400Z" } }

Скасувати розсилку

POST/api/v1/sends/{id}/cancel

Скасувати можна лише заплановані надсилання, які ще не розпочалися. Повна сума повертається на ваш баланс, а відповідь містить refunded_usd.

Вебхуки

Встановіть HTTPS-URL у робочому просторі (API та вебхуки). Ми надсилаємо POST-запит з подією, коли повідомлення доставлено або не вдалося, для надсилань як через API, так і з робочого простору. Відповідайте будь-яким статусом 2xx протягом 10 секунд. Невдалі спроби доставки повторюються до 7 разів: відразу, потім через 1 хвилину, 5 хвилин, 30 хвилин, 1 годину, 2 години та 3 години. Робочий простір відображає кожну спробу з її статусом та відповіддю.

POST https://your-server.example/sms-events
X-SSO-Event: message.delivered
X-SSO-Delivery: evt_5a0c9e31d2b7f4a68c
X-SSO-Timestamp: 1794132729
X-SSO-Signature: sha256=8f1c...e42a

{ "id": "evt_5a0c9e31d2b7f4a68c", "event": "message.delivered", "created": "2026-11-07T10:12:09.000Z",
  "data": { "message": { "id": "MS3D8RW0K2QJ7N", "send_id": "CA7Q29XMAB4DFK", "to": "+447700900461", "country": "GB",
  "segments": 1, "price_usd": "0.00868", "status": "delivered", "reason": null, "reason_text": null,
  "client_ref": "bookings-1107", "created_at": "...", "sent_at": "...", "done_at": "..." } } }

Підпис є HMAC-SHA256 від timestamp + "." + raw body з вашим секретним ключем (він починається з sso_whk_). Перевіряйте його на необробленому тілі перед аналізом, відхиляйте часові мітки старші 5 хвилин і використовуйте ідентифікатор доставки, щоб ігнорувати повторення.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a string), before JSON.parse
export function verify(rawBody, headers, secret) {
  const ts = headers["x-sso-timestamp"];
  const sig = headers["x-sso-signature"] || "";
  const want = "sha256=" + crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && sig.length === want.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want));
}

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    ts = headers.get("X-SSO-Timestamp", "")
    sig = headers.get("X-SSO-Signature", "")
    mac = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256)
    want = "sha256=" + mac.hexdigest()
    fresh = ts.isdigit() and abs(time.time() - int(ts)) < 300
    return fresh and hmac.compare_digest(sig, want)

<?php
function verify(string $rawBody, string $ts, string $sig, string $secret): bool {
  $want = "sha256=" . hash_hmac("sha256", $ts . "." . $rawBody, $secret);
  return ctype_digit($ts) && abs(time() - (int)$ts) < 300 && hash_equals($want, $sig);
}

Події: message.delivered, message.failed та test з кнопки Надіслати тестову подію.

Статуси та причини

Причини невдачі (поле reason):