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.