Введение

Все ответы возвращаются в формате JSON.
У успешных запросов HTTP код состояния 2XX.
У всех неуспешных запросов HTTP код 4XX/5XX.

https:///v1

Подпись запроса

Для запросов к API используется Basic HTTP аутентификация. Т.е. необходимо передать следующий HTTP-заголовок:

Authorization: Basic <BASE64_ENCODED_ACCESS_KEY>


Получить API ключ доступа можно в личном кабинете.

curl -XPOST https:///v1/sms \ -u "1efc292194c04e9b530:b0b6c43e9a75c51f" \ -d "number=+18800000000"

Типы ошибок

В случае ошибки запроса будет возвращен ответ с полями errorCode и errorReason, которые помогут определить причину ошибки.

Список ошибок
  • 1 HTTP 401
    Authentication required
    Неверный заголовок атворизации. Проверьте API ключ.
  • 2 HTTP 400
    Inactive account
    Ваш аккаунт неактивен. Пожалуйста, свяжитесь с поддержкой.
  • 4 HTTP 429
    Too many requests
    Вы сделали слишком много запросов за короткий промежуток времени. Максимально разрешенное количество запросов в секунду - 30.
  • 5 HTTP 401
    Inactive token
    Ваш токен более не действителен.
  • 6 HTTP 403
    Insufficient funds
    Средств на вашем аккаунте недостаточно для обработки запроса.
  • 10 HTTP 400
    Invalid request
    Ваш запрос был неправильно сформирован. Пожалуйста, изучите документацию.
  • 11 HTTP 400
    Invalid number
    Номер телефона недействителен или введен в неверном формате. Номер должен быть передан в международном формате (E.164, например 79110000000).
  • 16 HTTP 400
    Sender not allowed
    Данное имя отправителя не доступно.
{
"errorCode" : 1,
"errorReason" : "Authentication required"
}

Информация о запросе

Получайте информацию о запросе по requestId

ОПИСАНИЕ ПОЛЕЙ
  • mccmnc строка
    Идентификатор мобильной сети, полученный по префиксу телефонного номера.
  • country строка
    ISO-код страны, полученный по префиксу телефонного номера.
  • status строка
    Статус доставки (например: SENT (отправлен), DELIVERED (доставлен), REJECTED (отклонен), ...).
  • payload ключ-значение
    Исходные http параметры запроса.
curl https:///v1/requests/xxxxxxxxxxxxxx \-u "1efc292194c04e9b530:b0b6c43e9a75c51f"

{
  "id": "xxxxxxxxxxxxxx",
  "product": "verify.sms",
  "number": "+91638651000",
  "mccmnc": "405871",
  "network": "Jio",
  "country": "IN",
  "status": "DELIVERED",
  "createdAt": 1551007102495,
  "payload": {
    "number": "+916386535610",
    "method": "sms",
  }
}

Обновление информации о запросе

Метод позволяет задать цели, которые были достигнуты данным запросом.
Полученные данные могут быть использованы в дальнейшем для подсчета конверсий.

ОПИСАНИЕ ПОЛЕЙ
  • goal строка
    Название цели (например: NUMBER_VERIFIED, LINK_OPENED).
curl -XPOST https:///v1/requests/xxxxxxxxxxxxxx \ -u "1efc292194c04e9b530:b0b6c43e9a75c51f" \ -d "goal=NUMBER_VERIFIED"

Обратный вызов (webhooks)

Если в запросе передан параметр callbackUrl, вы получите на этот URL обратный вызов (HTTP POST) с данными в формате json/application.
Там будет передан статус обработки запроса.

Основные статусы
  • SENT
    Сообщение было отправлено провайдеру без ошибок.
  • DELIVERED
    Сообщение было успешно отправлено и доставлено.
  • UNDELIVERED
    Сообщение/Запрос был отправлен провайдеру, но не был доставлен.
  • REJECTED
    Невозможно выполнить запрос. Пожалуйста, свяжитесь с поддержкой для получения информации.
{
  "requestId": "wp9RPWDGZkskBrVeTc4lgNCc4e79fc65",
  "number": "37200911211",
  "status": "DELIVERED",
  "timestamp": 1551007102495
}

Авторизация по номеру

Процесс авторизации состоит из двух этапов (двух запросов к API). Первым этапом осуществляется запрос на доставку проверочного кода на указанный пользователем номер телефона. Код можно доставить тремя способами (в зависимости от переданного параметра method). В ответ будет возвращен requestId, который необходимо использовать на втором шаге для передачи введенного пользователем кода (PIN).

POST https:///v1/verify

Отправка проверочного PIN-кода

Доступно три способа проверки номера:

call - на телефон пользователя поступает вызов. В этом случае кодом авторизации будут последние 4 цифры телефонного номера, с которого идет вызов.

sms - на телефон пользователя будет отправлено SMS сообщение с PIN-кодом.

voice - на телефон пользователя поступает звонок, во время которого наш робот диктует PIN-код.

Параметры
  • number строка, ОБЯЗАТЕЛЬНО
    Телефонный номер пользователя в формате E.164, который надо авторизовать.
  • method строка, ОБЯЗАТЕЛЬНО
    Один из следующих методов, который будет использован для авторизации: sms, voice, call.
  • from строка, необязательно
    Буквенно-цифровая строка с именем отправителя (SenderID) для СМС. Ваше имя отправителя должно быть заранее одобрено нашей техподдержкой.
  • language строка, необязательно
    Язык по умолчанию - английский en (поддерживаемые языки: en, de, fa, es, fr, it, pt, ja, ru, sv).
  • codeLength число, необязательно
    Длина генерируемого одноразового кода (4, 5 или 6 цифр). Значение по умолчанию - 4.
  • ip сетевой адрес, необязательно
    По желанию вы можете также передавать нам IP адрес пользователя для более точного предотвращения мошенничесих действий.
curl -XPOST https:///v1/verify \ -u 1efc292194c04e9b530:b0b6c43e9a75c51f \ -d number="+18800000000" \ -d method=sms

{
"requestId" : "wp9RPWDGZkskBrVeTc4lgNCc4e79fc65"
}

Проверка кода авторизации

Авторизуйте номер пользователя с помощью кода авторизации

Параметры
  • requestId строка
    Идентификатор запроса, который надо проверить. Это requestId, который вы получили в ответе /verify.
  • code строка
    PIN-код, который был передан на телефон пользователя в виде SMS или звонка.
# Check the phone number$ curl	-X POST https:///v1/verify/check \		-u "1efc292194c04e9b530:b0b6c43e9a75c51f" \		-d "requestId=XXXXXXXXXXXXXX"

Получение информации о номере

API предоставляет информацию о мобильной сети (MCC, MNC), действительности и доступности номера.

Это API позволяет вам актуализировать вашу базу номеров, фильровать ненастоящие мобильные номера, бороться с мошенническими действиями.

curl https:///v1/insight/hlr \ -u 1efc292194c04e9b530:b0b6c43e9a75c51f \ -d number="+47463562200" 

{
  "id": "A82f588e12b54ba1b6bd9a5969d51522",
  "product": "insight.hlr",
  "number": "+47463562200",
  "mccmnc": "242005",
  "network": "Mobile Norway",
  "country": "NO",
  "status": "DELIVERED",
  "createdAt": 1550975149131
}

SMS API

Отправка SMS сообщений.

Параметры
  • number строка
    Номер в формате E.164, на который надо отправить сообщение.
  • text строка
    Текст исходящего сообщения
  • from строка (необязательно)
    Имя отправителя, с которого будет отправлено сообщение. Буквенно-цифровое имя отправителя должно быть заранее одобрено нашей поддержкой.
  • callbackUrl строка, необязательно
    Ваш URL, на который будет отправлена информация о статусе доставки.
POST https:///v1/sms

curl -XPOST https:///v1/sms \ -u 1efc292194c04e9b530:b0b6c43e9a75c51f \ -d number="+18800000000"\ -d text="Ваш заказ #29211 доставлен"

Входящие SMS

Вы можете арендовать один или несколько виртуальных номеров. При отправке SMS на эти номера вы сможете получать уведомления по HTTP на ваш URL (webhook).

POST https://yourdomain.com/webhook/inbound-sms

{
  "from": "447700900001",
  "to": "447700900000",
  "messageId": "fffeee-qqdqqq-gfrgrgr-vvvvvvv",
  "text": "Hello world",
  "timestamp": 1578787200,
  "parts": 1,
}

Отправка сообщений в мессенджеры/каналы

Вы можете отправлять сообщения вашим пользователям в различные каналы

POST https:///v1/messaging/{CHANNEL}

Отправить Push уведомление

Для Android (FCM) и iOS приложений. Не забудьте интегрировать SDK в ваше приложение.

Параметры
  • number строка
    Номер в формате E.164, на который будет отправлено сообщение
  • text строка
    Тело отправляемого сообщения
  • title строка, необязательно
    Заголовок для push уведомления
  • callbackUrl строка, необязательно
    Конечная точка webhook, на которую отправляется подтверждение доставки для этого сообщения.
curl -XPOST https:///v1/messaging/push \ -u 1efc292194c04e9b530:b0b6c43e9a75c51f \ -d number="+18800000000"\ -d text="Ваш заказ #29211 доставлен" -d title="Здравствуйте!"

Отправить Viber сообщение

Отправить личное сообщение в Viber мессенджер.

Параметры
  • number строка
    Номер в формате E.164, на который будет отправлено сообщение
  • text строка
    Тело отправляемого сообщения
  • from строка, необязательно
    Имя отправителя для Viber сообщения
  • callbackUrl строка, необязательно
    Конечная точка webhook, на которую отправляется подтверждение доставки для этого сообщения.
  • buttonCaption строка, необязательно
    Заголовок кнопки в Viber сообщении
  • buttonActionUrl строка, необязательно
    Действие для кнопки
  • imageUrl строка, необязательно
    Ссылка для изображения
curl -XPOST https:///v1/messaging/viber \ -u 1efc292194c04e9b530:b0b6c43e9a75c51f \ -d number="+18800000000"\ -d text="Ваш заказ #29211 доставлен"

Отправить RCS сообщение

Отправить личное сообщение на устройство с функцией RCS.

Параметры
  • number строка
    Номер в формате E.164, на который будет отправлено сообщение
  • text строка
    Тело отправляемого сообщения
  • callbackUrl строка, необязательно
    Webhook url, на который отправляется подтверждение доставки для этого сообщения.
curl -XPOST https:///v1/messaging/rcs \ -u 1efc292194c04e9b530:b0b6c43e9a75c51f \ -d number="+18800000000"\ -d text="Ваш заказ #29211 доставлен"

Каскадная переотправка

Цепочка сообщений (Push > Viber/Whatsapp/и т.д. > SMS).
Если телефонный номер авторизован в приложении, мы отправим Push уведомление (это бесплатно). Если номер не авторизован в приложении или приложение удалено, мы отправим сообщение через один из мессенджеров или СМС.

curl -XPOST https:///v1/messaging/failover \ -u 1efc292194c04e9b530:b0b6c43e9a75c51f \ -d '{
    "number": "+18800000000",
    "flow": [
        {
            "type": "push",
            "message": {
                "title": "Квантек",
                "text": "Ваш заказ #29211 доставлен"
            },
            "failover": {
                "wait": 30,
                "condition": "delivered"
            }
        },
        {
              "type": "viber",
              "message": {
                "from": "Квантек",
                "text": "Ваш заказ #29211 доставлен"
              },
              "failover": {
                "wait": 120,
                "condition": "read"
              }
            },
        {
            "type": "sms",
            "message": {
                "from": "Quantek",
                "text": "Ваш заказ #29211 доставлен"
            }
        }
    ]
}'

API для звонков

С помощью этого API можно легко звонить. Используя REST API, вы можете делать исходящие программируемые звонки и собирать метаданные о звонках.

POST https:///v1/calls/{CALL_TYPE}

Звонок без длительности

Этот метод совершает звонок на указанный номер. Звонок завершается автоматически после тайм-аута или ответа пользователя. Т.е, звонок не имеет длительности.

Параметры
  • number string, REQUIRED
    Телефонный номер пользователя в формате E.164.
  • from string, optional
    Номер, с которого будет выполнен звонок. Этот номер должен быть предварительно одобрен техподдержкой.
    По умолчанию звонок совершается со случайного номера, который будет возвращен в ответе API (последние 6 цифр номера генерируются случайно).
  • callbackUrl string, optional
    Webhook url, на который отправляется обновление SIP статуса звонка
curl -XPOST https:///v1/calls/flash \ -u "1efc292194c04e9b530:b0b6c43e9a75c51f" \ -d "number=+18800000000"

{
"requestId" : "wp9RPWDGZkskBrVeTc4lgNCc4e79fc65 "from" : "37282329823"
}

Сделать P2S-звонок с синтезом речи

Робот совершает звонок проговаривая переданный ПИН-код голосом.

Параметры
  • number строка, ОБЯЗАТЕЛЬНО
    Телефонный номер пользователя в формате E.164.
  • code строка, ОБЯЗАТЕЛЬНО
    4-6 значный ПИН-код для голосового сообщения
  • from строка, необязательно
    Конечный номер, с которого вы звоните. Этот номер должен быть предварительно одобрен.
  • language строка, необязательно
    Этот голосовой параметр позволяет вам выбрать язык, который будет использоваться для речевого воспроизведения вашего сообщения. Язык по умолчанию - en.
  • callbackUrl строка, необязательно
    Webhook url, на который отправляется обновление SIP-статуса звонка





curl -XPOST https:///v1/calls/p2s \ -u "1efc292194c04e9b530:b0b6c43e9a75c51f" \ -d "number=+18800000000" -d "code=1234"