Webhook

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

Про повідомлення, яке шлюз відмовився прийняти, повідомляє той самий вебхук зі status: REJECTED і причиною в error. Окремого payload для помилок немає.

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

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

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

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

X-Signature

Заголовок X-Signature передається шляхом конкатенації JSON рядка та API ключа.
Приклад: X-Signature: sha256(json_body + api_key)

Доставка

До трьох спроб доставки: перший повтор через 10 секунд після невдачі, другий — ще через 60. Повтор буває лише при обриві зв'язку, таймауті або відповіді 5xx чи 429 — будь-яка інша відповідь, включно з 4xx, вважається остаточною. Успіхом вважається строго код 200, тіло відповіді ігнорується. Таймаут на з'єднання — 5 секунд, сумарний таймаут — 5 секунд.
Обробник робіть ідемпотентним: один і той самий статус може прийти повторно.

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

idstring Унікальний ідентифікатор повідомлення в системі клієнта ⚠️ Відсутній, якщо в асинхронному пакеті жоден елемент не мав id

msg_idstring Ідентифікатор повідомлення, присвоєний шлюзом ⚠️ Відсутній, якщо повідомлення відхилено до його створення

typestring Тип повідомлення: sms, viber, voice, rcs ⚠️ Відсутній, якщо відхилено запит, який сам повідомлення не створює (наприклад balance або hlr)

statusstring Статус повідомлення. Список значень — Статуси повідомлень Повідомлення, відхилене при прийомі, отримує статус REJECTED

successbooleanобов'язковий true, якщо повідомлення доставлено (DELIVERED, READ, REPLIED, PARTIALLY DELIVERED). false для будь-якого іншого статусу, включно з REJECTED при прийомі

errorstring Причина, з якої повідомлення відхилено ⚠️ Присутній тільки разом зі status: REJECTED, коли повідомлення відхилено при прийомі

updatedstring Дата і час зміни статусу Формат: YYYY-MM-DDThh:mm:ss±hh:mm

replystring Цифра, введена отримувачем (DTMF) ⚠️ Присутній тільки при type: voice, якщо запитувався dtmf

durationnumber Тривалість дзвінка в секундах ⚠️ Присутній тільки при type: voice

request_idstring Ідентифікатор асинхронного запиту. Збігається з request_id з відповіді шлюзу при відправці через /v1/json ⚠️ Присутній лише для повідомлень, надісланих через асинхронний API. Якщо в пакеті немає id жодного повідомлення, надсилається один вебхук з request_id

replieslist[object] Список відповідей на повідомлення ⚠️ Присутній тільки у Viber 2 Way datetimestring Дата і час отримання відповіді Формат: YYYY-MM-DDThh:mm:ss±hh:mm messagestring Текст повідомлення mediaobject Об'єкт, що містить інформацію про медіафайл, прикріплений до повідомлення urlstring Посилання на медіафайл filenamestring Ім'я медіафайлу filesizenumber Розмір медіафайлу

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

Default

{
    "id": "100500",
    "msg_id": "123456789",
    "type": "viber",
    "status": "READ",
    "success": true,
    "updated": "2024-01-31T12:34:00+02:00"
}

Viber 2 Way

{
    "id": "100500",
    "msg_id": "123456789",
    "type": "viber",
    "status": "READ",
    "success": true,
    "updated": "2024-01-31T12:34:00+02:00",
    "replies": [
        {
            "datetime": "2024-01-31T12:34:00+02:00",
            "message": "Please wait"
        },
        {
            "datetime": "2024-01-31T12:34:01+02:00",
            "media": {
                "url": "https://url.com/home/vibermedia/",
                "filename": "invoice.pdf",
                "filesize": 67983
            }
        },
        {
            "datetime": "2024-01-31T12:34:02+02:00",
            "message": "Correct invoice",
            "media": {
                "url": "https://url.com/home/vibermedia/",
                "filename": "invoice.pdf",
                "filesize": 68934
            }
        }
    ]
}

Voice

{
    "id": "100500",
    "msg_id": "123456789",
    "type": "voice",
    "status": "DELIVERED",
    "success": true,
    "updated": "2024-01-31T12:34:00+02:00",
    "reply": "7",
    "duration": 23
}

Async

{
    "id": "100500",
    "msg_id": "123456789",
    "request_id": "cf-ray-1234567890-ABC",
    "type": "viber",
    "status": "READ",
    "success": true,
    "updated": "2024-01-31T12:34:00+02:00"
}

Відхилено

Повідомлення відхилено при прийомі, тому в нього немає msg_id. Причина — в error.

{
    "id": "100500",
    "type": "sms",
    "status": "REJECTED",
    "success": false,
    "error": "Not enough money",
    "updated": "2024-01-31T12:34:00+02:00",
    "request_id": "a1436d496bf11a59"
}

Відхилено (без id)

У асинхронному пакеті жоден елемент не мав id. Надсилається один вебхук з request_id.

{
    "request_id": "a1436d496bf11a59",
    "status": "REJECTED",
    "success": false,
    "error": "Access denied",
    "updated": "2024-01-31T12:34:00+02:00"
}

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

У відповіді буде отримано код 200.

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

Успішний

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

примітка

Якщо відхилено весь запит — наприклад з Access denied — вебхук надсилається по кожному унікальному id. Якщо в пакеті немає id жодного повідомлення, надсилається один вебхук з request_id на перший hook.