Відправка SMS (JSON API)

SMS надсилається синхронно через /api/json.php (негайна відповідь шлюзу з msg_id для кожного повідомлення).

Асинхронне надсилання доступне за адресою /v1/json (запит ставиться в чергу).

---

Синхронне надсилання

Приклад запиту для відправки SMS-повідомлення на вказаний номер.

URI: https://alphasms.ua/api/json.php

Усі запити до API надсилаються у форматі JSON за допомогою методу POST.

Параметри заголовків

У запитах обов'язково має бути заголовок Content-Type: application/json, інакше запит буде вважатися некоректним навіть при валідному JSON у ньому.

Параметри запиту

authstringобов'язковий Ваш API-ключ, який можна отримати в особистому кабінеті

datalist[object]обов'язковий Список об'єктів з параметрами запиту typestringобов'язковий Тип запиту idnumberобов'язковий Унікальний ідентифікатор повідомлення в системі клієнта phonenumberобов'язковий Номер телефону одержувача повідомлення sms_signaturestringобов'язковий Підпис у повідомленні sms_messagestringобов'язковий Текст повідомлення для відправки через SMS sms_lifetimenumber Час життя SMS-повідомлення в секундах Мін. значення: 1 година (3600 секунд) Макс. значення: 3 дні (259200 секунд) За замовчуванням: 2 дні (172800 секунд) short_linkboolean Короткі та відстежувані посилання (згідно з тарифом) unsubscribe_linkboolean Клієнти можуть відписатися, натиснувши на посилання (згідно з тарифом) hookstring URL-адреса скрипта, куди буде відправлено статус доставки повідомлення

Приклад запиту

Sync

JSON

{
    "auth": "bb56a4369eb19***cfec6d1776bd25",
    "data": [
        {
            "type": "sms",
            "id": 100500,
            "phone": 380971234567,
            "sms_signature": "SMSTest",
            "sms_message": "Текст повідомлення для відправки через SMS",
            "sms_lifetime": 172800,
            "short_link": true,
            "unsubscribe_link": true,
            "hook": "https://example.org/webhook/url.php"
        }
    ]
}

cURL

curl -X POST 'https://alphasms.ua/api/json.php' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "auth": "bb56a4369eb19***cfec6d1776bd25",
  "data": [
    {
      "type": "sms",
      "id": 100500,
      "phone": 380971234567,
      "sms_signature": "SMSTest",
      "sms_message": "Текст повідомлення для відправки через SMS",
      "sms_lifetime": 172800,
      "short_link": true,
      "unsubscribe_link": true,
      "hook": "https://example.org/webhook/url.php"
    }
  ]
}'

PHP

<?php

$payload = json_encode([
    'auth' => 'bb56a4369eb19***cfec6d1776bd25',
    'data' => [
        [
            'type' => 'sms',
            'id' => 100500,
            'phone' => 380971234567,
            'sms_signature' => 'SMSTest',
            'sms_message' => 'Текст повідомлення для відправки через SMS',
            'sms_lifetime' => 172800,
            'short_link' => true,
            'unsubscribe_link' => true,
            'hook' => 'https://example.org/webhook/url.php',
        ],
    ],
], JSON_UNESCAPED_UNICODE);

$ch = curl_init('https://alphasms.ua/api/json.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Python

import requests

payload = {
    "auth": "bb56a4369eb19***cfec6d1776bd25",
    "data": [
        {
            "type": "sms",
            "id": 100500,
            "phone": 380971234567,
            "sms_signature": "SMSTest",
            "sms_message": "Текст повідомлення для відправки через SMS",
            "sms_lifetime": 172800,
            "short_link": True,
            "unsubscribe_link": True,
            "hook": "https://example.org/webhook/url.php",
        },
    ],
}

response = requests.post(
    "https://alphasms.ua/api/json.php",
    json=payload,
    timeout=30,
)

print(response.json())

Node.js

const payload = {
  "auth": "bb56a4369eb19***cfec6d1776bd25",
  "data": [
    {
      "type": "sms",
      "id": 100500,
      "phone": 380971234567,
      "sms_signature": "SMSTest",
      "sms_message": "Текст повідомлення для відправки через SMS",
      "sms_lifetime": 172800,
      "short_link": true,
      "unsubscribe_link": true,
      "hook": "https://example.org/webhook/url.php"
    }
  ]
};

const response = await fetch("https://alphasms.ua/api/json.php", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

console.log(await response.json());

Async

JSON

{
    "auth": "bb56a4369eb19***cfec6d1776bd25",
    "data": [
        {
            "type": "sms",
            "id": 100500,
            "phone": 380971234567,
            "sms_signature": "SMSTest",
            "sms_message": "Текст повідомлення для відправки через SMS",
            "sms_lifetime": 172800,
            "short_link": true,
            "unsubscribe_link": true,
            "hook": "https://example.org/webhook/url.php"
        }
    ]
}

cURL

curl -X POST 'https://api-async.alphasms.ua/v1/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "auth": "bb56a4369eb19***cfec6d1776bd25",
  "data": [
    {
      "type": "sms",
      "id": 100500,
      "phone": 380971234567,
      "sms_signature": "SMSTest",
      "sms_message": "Текст повідомлення для відправки через SMS",
      "sms_lifetime": 172800,
      "short_link": true,
      "unsubscribe_link": true,
      "hook": "https://example.org/webhook/url.php"
    }
  ]
}'

PHP

<?php

$payload = json_encode([
    'auth' => 'bb56a4369eb19***cfec6d1776bd25',
    'data' => [
        [
            'type' => 'sms',
            'id' => 100500,
            'phone' => 380971234567,
            'sms_signature' => 'SMSTest',
            'sms_message' => 'Текст повідомлення для відправки через SMS',
            'sms_lifetime' => 172800,
            'short_link' => true,
            'unsubscribe_link' => true,
            'hook' => 'https://example.org/webhook/url.php',
        ],
    ],
], JSON_UNESCAPED_UNICODE);

$ch = curl_init('https://api-async.alphasms.ua/v1/json');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => $payload,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Python

import requests

payload = {
    "auth": "bb56a4369eb19***cfec6d1776bd25",
    "data": [
        {
            "type": "sms",
            "id": 100500,
            "phone": 380971234567,
            "sms_signature": "SMSTest",
            "sms_message": "Текст повідомлення для відправки через SMS",
            "sms_lifetime": 172800,
            "short_link": True,
            "unsubscribe_link": True,
            "hook": "https://example.org/webhook/url.php",
        },
    ],
}

response = requests.post(
    "https://api-async.alphasms.ua/v1/json",
    json=payload,
    timeout=30,
)

print(response.json())

Node.js

const payload = {
  "auth": "bb56a4369eb19***cfec6d1776bd25",
  "data": [
    {
      "type": "sms",
      "id": 100500,
      "phone": 380971234567,
      "sms_signature": "SMSTest",
      "sms_message": "Текст повідомлення для відправки через SMS",
      "sms_lifetime": 172800,
      "short_link": true,
      "unsubscribe_link": true,
      "hook": "https://example.org/webhook/url.php"
    }
  ]
};

const response = await fetch("https://api-async.alphasms.ua/v1/json", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

console.log(await response.json());

Параметри відповіді

successinteger Результат виконання запиту

errorstring Текст помилки, що повертається, якщо success=false

datalist[object] Список об'єктів з результатами виконання запиту successboolean Результат виконання запиту повернутий у пакеті даних errorstring Текст помилки, що повертається, якщо data.success=false dataobject Результат виконання запиту idnumber Унікальний ідентифікатор повідомлення в системі клієнта msg_idnumber Ідентифікатор повідомлення, присвоєний шлюзом partsnumber Кількість повідомлень, використаних для надсилання вказаного тексту

Приклади відповіді

Успішний

HTTP Status Code: 200
Content Type: JSON application/json

{
    "success": true,
    "data": [
        {
            "success": true,
            "data": {
                "id": 100500,
                "msg_id": 123456789,
                "parts": 1
            }
        }
    ]
}

Доступ заборонено

HTTP Status Code: 200
Content Type: JSON application/json

{
    "success": false,
    "error": "Access denied"
}

Помилка в Альфа-імені

HTTP Status Code: 200
Content Type: JSON application/json

{
    "success": true,
    "data": [
        {
            "success": false,
            "error": "Error in Alpha-name",
            "data": {
                "id": 100500
            }
        }
    ]
}

---

Асинхронна відправка

Для масової або неблокуючої відправки використовуйте async JSON API. Формат тіла запиту такий самий, як при синхронній відправці: auth і непустий масив data з об'єктами type: "sms".

URI: https://api-async.alphasms.ua/v1/json

Приклад відповіді при успіху:

{
  "request_id": "cf-ray-1234567890-ABC",
  "success": true
}

Ідентифікатори msg_id по кожному повідомленню у відповіді не повертаються. Використовуйте request_id, webhook через hook в запиті або message status для результатів доставки.

Коди помилок HTTP:

Code	Опис
400	Недійсний JSON або порожній/недійсний data масив
401	Відсутній або порожній auth
405	Метод, відмінний від POST
413	Тіло запиту занадто велике
415	Відсутній або недійсний Content-Type (має бути application/json)
503	Черга недоступна