Відправка OTP коду (WhatsApp)

Приклад запиту для відправки одноразового пароля (OTP) через WhatsApp.

warning

WhatsApp не є окремим типом повідомлення. Запит із type: whatsapp відхиляється з помилкою Invalid message type.

WhatsApp існує лише як етап пайплайну: ви надсилаєте запит із type: pipeline і перелічуєте whatsapp серед його етапів. Усе інше — адреса, ключ, формат відповіді — таке саме, як у будь-якого іншого методу JSON API.

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

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

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

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

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

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

datalist[object]обов'язковий Список об'єктів з параметрами запиту typestringобов'язковий Тип запиту. Для WhatsApp це завжди pipeline pipelinelist[string]обов'язковий Канали в тому порядку, в якому вони пробуються. Тільки WhatsApp — ["whatsapp"] Значення не повинні повторюватися idnumber Унікальний ідентифікатор повідомлення в системі клієнта phonenumberобов'язковий Номер телефону отримувача повідомлення Тільки цифри, без + whatsappobjectобов'язковий Параметри етапу WhatsApp signaturestringобов'язковий Зареєстроване ім'я відправника messagestringобов'язковий Повідомлення з одноразовим паролем

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

Sync

JSON

{
    "auth": "bb56a4369eb19***cfec6d1776bd25",
    "data": [
        {
            "type": "pipeline",
            "pipeline": [
                "whatsapp"
            ],
            "id": 100500,
            "phone": 380971234567,
            "whatsapp": {
                "signature": "SenderID",
                "message": "Ваш код 1234"
            }
        }
    ]
}

cURL

curl -X POST 'https://alphasms.ua/api/json.php' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "auth": "bb56a4369eb19***cfec6d1776bd25",
  "data": [
    {
      "type": "pipeline",
      "pipeline": [
        "whatsapp"
      ],
      "id": 100500,
      "phone": 380971234567,
      "whatsapp": {
        "signature": "SenderID",
        "message": "Ваш код 1234"
      }
    }
  ]
}'

PHP

<?php

$payload = json_encode([
    'auth' => 'bb56a4369eb19***cfec6d1776bd25',
    'data' => [
        [
            'type' => 'pipeline',
            'pipeline' => [
                'whatsapp',
            ],
            'id' => 100500,
            'phone' => 380971234567,
            'whatsapp' => [
                'signature' => 'SenderID',
                'message' => 'Ваш код 1234',
            ],
        ],
    ],
], 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": "pipeline",
            "pipeline": [
                "whatsapp",
            ],
            "id": 100500,
            "phone": 380971234567,
            "whatsapp": {
                "signature": "SenderID",
                "message": "Ваш код 1234",
            },
        },
    ],
}

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": "pipeline",
      "pipeline": [
        "whatsapp"
      ],
      "id": 100500,
      "phone": 380971234567,
      "whatsapp": {
        "signature": "SenderID",
        "message": "Ваш код 1234"
      }
    }
  ]
};

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": "pipeline",
            "pipeline": [
                "whatsapp"
            ],
            "id": 100500,
            "phone": 380971234567,
            "whatsapp": {
                "signature": "SenderID",
                "message": "Ваш код 1234"
            }
        }
    ]
}

cURL

curl -X POST 'https://api-async.alphasms.ua/v1/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "auth": "bb56a4369eb19***cfec6d1776bd25",
  "data": [
    {
      "type": "pipeline",
      "pipeline": [
        "whatsapp"
      ],
      "id": 100500,
      "phone": 380971234567,
      "whatsapp": {
        "signature": "SenderID",
        "message": "Ваш код 1234"
      }
    }
  ]
}'

PHP

<?php

$payload = json_encode([
    'auth' => 'bb56a4369eb19***cfec6d1776bd25',
    'data' => [
        [
            'type' => 'pipeline',
            'pipeline' => [
                'whatsapp',
            ],
            'id' => 100500,
            'phone' => 380971234567,
            'whatsapp' => [
                'signature' => 'SenderID',
                'message' => 'Ваш код 1234',
            ],
        ],
    ],
], 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": "pipeline",
            "pipeline": [
                "whatsapp",
            ],
            "id": 100500,
            "phone": 380971234567,
            "whatsapp": {
                "signature": "SenderID",
                "message": "Ваш код 1234",
            },
        },
    ],
}

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": "pipeline",
      "pipeline": [
        "whatsapp"
      ],
      "id": 100500,
      "phone": 380971234567,
      "whatsapp": {
        "signature": "SenderID",
        "message": "Ваш код 1234"
      }
    }
  ]
};

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());

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

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

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

datalist[object] Список об'єктів з результатами виконання запиту successboolean Результат виконання запиту, що повертається в пакеті даних errorstring Текст помилки, повертається якщо data.success=false dataobject Результат виконання запиту msg_idnumber Ідентифікатор повідомлення, присвоєний шлюзом ⚠️ Запит pipeline відповідає лише msg_id — надісланий вами id у відповіді не повертається

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

Успішно

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

{
    "success": true,
    "data": [
        {
            "success": true,
            "data": {
                "msg_id": 123456789
            }
        }
    ]
}

Немає маршруту

WhatsApp не увімкнено у вашому маршруті або для оператора цього номера маршруту немає.

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

{
    "success": true,
    "data": [
        {
            "success": false,
            "error": "No route"
        }
    ]
}

Невірний тип

Відповідь на type: whatsapp. WhatsApp — етап пайплайну, а не тип повідомлення.

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

{
    "success": false,
    "error": "Invalid message type"
}

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

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

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

примітка

Перехід на запасний канал. Перелічіть канали в тому порядку, в якому їх треба пробувати, і додайте параметри кожного етапу. Шлюз резервує вартість найдорожчого етапу, а різницю повертає після фактичної доставки.

{
    "type": "pipeline",
    "pipeline": ["whatsapp", "sms"],
    "id": 100500,
    "phone": 380971234567,
    "whatsapp": { "signature": "SenderID", "message": "Ваш код 1234" },
    "sms": { "signature": "SenderID", "message": "Ваш код 1234" }
}

Повний перелік етапів та їх параметрів — на сторінці Багатоканальна доставка повідомлень.

warning

WhatsApp має бути увімкнений у вашому маршруті — шлюз і ціну призначає ваш менеджер. Без них будь-який пайплайн із whatsapp відповідає No route.

Етап whatsapp API не перевіряє. Якщо signature або message не передати, запит усе одно буде прийнято й оплачено, а повідомлення піде порожнім. Перевіряйте обидва поля на своєму боці до відправлення.

Статус доставки запиту pipeline іде на адресу сповіщень із налаштувань API — див. Звіт про доставку на URL: hook шлюз для цього типу не зберігає.

примітка

У асинхронного API адреса з hook все ж використовується в одному випадку: відмова у прийомі повідомлення (No route, нестача коштів, помилка валідації) приходить туди окремим вебхуком зі status: REJECTED.