Перейти к основному содержимому

«Коммуникационная платформа SevenTech» - Руководство по эксплуатации: интеграция по API

1. Авторизация

Есть возможность настроить авторизацию двумя способами:

  1. Для подключения используется тип авторизации Basic Auth, для организации доступа клиент получает пару логин и пароль и вводит запрашиваемые значения в соответствующие поля:

Authorization: Basic Auth Username: username
Password: password

  1. При подключении клиент получает пару логин и пароль, которые требуются для авторизации, для чего необходимо закодировать пару логин:пароль алгоритмом Base64 и передать в виде заголовка Authorization HTTP-запроса или через query-параметр

Пример закодированного заголовка HTTP Basic Authentication:

Authorization: Basic YWhhbWlsdG9uQGFwaWdlZS5jb206bXlwYXNzdzByZAo

2. Метод отправки сообщения

POST https://my.seven.tech/messaging/v1/send

2.1 Параметры

Параметры описываются в формате JSON и могут иметь один или несколько базовых элементов scenario.

NameTypeDescription
scenario
required
scenarioМассив элементов описывающий процесс передачи сообщения (структура описана отдельно)
callback
optional
stringURI для отправки отчета о доставке.
clientRequestId
optional
stringИдентификатор клиентского запроса, максимальная длина 100 символов
urlOptions
optional
objectПараметры сокращения ссылок в сообщении. Для включения такой возможности нужно обратиться к вашему менеджеру.
trackData
optional
objectНабор параметров, которые будут возвращены в callback, пример: "trackData": { "tag": "12345678" },

2.1.1 scenario — сценарий отправки сообщения

NameTypeDescription
channel
required
enumКанал отправки. Значения:
sms - отправка сообщения посредством SMS
viber - отправка сообщения в месссенджер Viber
vkok - отправка сообщения через соцсети VK и OK (в зависимости от активности абонента в той или иной соцсети)
push - отправка сообщения посредством Push нотификации на iOS/Android
whatsapp - отправка сообщения в месссенджер WhatsApp
Каналы подключаются по согласованию с менеджером
recipient
required
recipientПолучатель сообщения (структура описана отдельно)
sender
required
stringИмя отправителя. Для канала sms максимальная длина 11 символов, для других каналов - 21.
text
optional
stringТекст сообщения. Максимальная длина ограничена 39015 байтами (255 частей), что соответствует 39015 символам ASCII, 19507 символам не ASCII. Наличие emoji в тексте сокращает это значение, так как emoji занимает от 2 до 4 байт
failover
optional
objectСтратегия отправки сообщения по альтернативному каналу (структура описана отдельно)
attachments
optional
attachmentsВложения сообщения (структура описана отдельно)
buttons
optional
buttonsКнопка сообщения (структура описана отдельно)
mobilePushAction
optional
stringDeepLink при нажатии на push сообщение, используется только для канала push
mobilePushTitle
optional
stringTitle для push сообщения, используется только для канала push
2.1.1.1 recipient — получатель сообщения
NameTypeDescription
type
required
enumТип получателя. Значения:
MSISDN - номер абонента в формате [E.164]
(https://en.wikipedia.org/wiki/E.164)
value
required
string
maxLength: 200
Значение адреса получателя
2.1.1.2 attachments — медиаконтент сообщения
NameTypeDescription
type
required
enumТип контента. Значения:
IMAGE — изображение
AUDIO — аудио файл
VIDEO – видео файл
FILE — файл
url
required
stringСсылка на медиаконтент
2.1.1.3 buttons — кнопка сообщения
NameTypeDescription
caption
required
stringТекст кнопки
action
required
stringСсылка, которая откроется, при нажатии на кнопку
2.1.1.4 failover — стратегия отправки по альтернативному каналу (каскадирование)
NameTypeDescription
ttl
optional
integer
max:259200
Время ожидания (в секундах) статуса доставки или прочтения (в зависимости от condition_status).
condition_status
optional
enumТип ожидаемого статуса в период ttl:
DELIVERED
SEEN

2.1.2 urlOptions — параметры обработки ссылок

NameTypeDescription
shortenUrl
required
booleanФлаг true означает, все ссылки, длина которых более 20 символа, будут заменены на короткие ссылки формата wsl.am/Aa34Zz7. Это позволит сократить длину сообщения и формировать отчеты по переходам по этим ссылкам.

2.2 Пример запроса

Отправка сообщения в канал Viber с каскадированием в канал SMS, в случае неполучения статуса DELIVERED в течении 10 минут.

{
"scenario": [
{
"channel": "string",
"recipient": {
"type": "MSISDN",
"value": "79012223344"
},
"sender": "myname",
"text": "Текст сообщения",
"failover": {
"ttl": 600,
"condition_status": "DELIVERED"
},
"attachments": [
{
"type": "IMAGE",
"url": "http://content.url"
}
],
"buttons": [
{
"caption": "button text",
"action": "https://action.url"
}
],
"mobilePushAction": "string",
"mobilePushTitle": "string"
}
],
"callback": "https://callback_endpoint.url",
"clientRequestId": "string",
"trackData": {
"customParamWichWillBeReturned": "customParamValue"
},
"urlOptions": {
"shortenUrl": true
}
}

2.3 Ответ на запрос

2.3.1 Коды HTTP

CodeDescription
200Запрос принят и обработан
400Ошибка в формате запроса
401Доступ API с указанными реквизитами запрещен. Проверить логин/пароль
403Ошибка авторизации, нет прав для использования API или IP запрещен

2.3.2 Расширенная информация в теле ответа

NameTypeDescription
txId
required
string
uuid
Идентификатор сообщения в uuid
updatedAt
required
string
datetime
Дата и время обновления состояния сообщения в UTC (ISO 8601 RFC 3339)
state
required
enumСостояние сообщения. Возможные значения:
ACCEPTED — сообщение принято
FAILED – ошибка при обработке запроса
trackData
optional
jsonНабор пользовательских параметров, которые будут возвращены в callback, пример: "trackData": { "ptag": "12345678" }
error
optional
jsonНабор параметров, которые будут возвращены в error, пример: "error": { "code": 400, "message": "Scenario channels not unique" }

2.3.3 Примеры ответов

Запрос принят и обработан

HTTP/200
{
"txId": "7591a05e-f22b-4548-b824-915b617e2778",
"updatedAt": "2020-11-16T10:01:29.981Z",
"trackData": {
"tag": "0123456789",
"otherTag": "0987654321"
},
"state": "ACCEPTED"
}

Ошибка в формате запроса

HTTP/400
{
"error": {
"id": "d0ecfd85-b8d2-4b9a-afe8-13cb236398d8",
"status": 400,
"message": "Scenario channels is empty"
}
}

Доступ API с указанными реквизитами запрещен

HTTP/401
{
"error": {
"id": "56b78325-acc8-4af9-97eb-7e90cdfc3593",
"status": 401,
"message": "invalid verification token"
}
}

Ошибка авторизации, нет прав для использования API или IP запрещен

HTTP/403
{
"error": {
"id": "1c302be7-045d-44e2-83e4-8f25e8884b6d",
"status": 403,
"message": "Principal doesn't have required permissions"
}
}

3. Возврат статуса (callback)

3.1. Нотификационная схема

В этом разделе описывается механизм обратных вызовов (callback), который коммуникационная платформа отправляет в сторону клиента. Обратные вызовы позволяют отправлять уведомления клиенту о смене статуса сообщения. Это позволяет клиенту получать актуальную информацию в реальном времени без необходимости опрашивать сервер.

URL для для возврата callback, указывется в запросе на отправку сообщения в параметре callback. Опционально можно задать статичный callback URL, для этого необходимо сообщить адрес службе поддержки или аккаунт-менеджеру.

POST https://partner.url/callback

3.1.1 Параметры запроса

NameTypeDescription
txId
required
string
uuid
Идентификатор сообщения
updatedAt
required
string
datetime
Дата и время обновления состояния сообщения
state
required
enumСостояние сообщения. Возможные значения:
DELIVERED — сообщение успешно доставлено
NOT_DELIVERED – сообщение не доставлено
SEEN — сообщение просмотрено
EXPIRED — статус сообщения не получен в течении указанного TTL
FAILED — сообщение не отправлено.
channel
optional
enumКанал доставки. Значения:
sms - СМС-сообщения
whatsapp — мессенджер Viber
viber - мессенджер Viber
push - пуш-уведомления из мобильного приложения
Параметр может отсутствовать если state FAILED или EXPIRED
trackData
optional
jsonНабор пользовательских параметров, которые будут возвращены в callback, пример:
"trackData": { "ptag": "12345678" }
error
optional
errorКод и описание статуса в формате JSON. Расшифровка доступна в разделе Коды ошибок, пример:
"error": { "code": 6, "message": "Абонент недоступен. Например, из-за уровня сигнала, выключения мобильного устройства" }

3.1.2 Коды ошибок

CodeDescription
0Успешная доставка
1Неизвестная причина недоставки сообщения
4Номер абонента (msisdn) не существует.
6Абонент недоступен. Например, мобильное устройство выключено или низкий уровня сигнала сети
8Номер абонента не обслуживается, не распознан оператором, абонент не зарегистрирован в сети оператора и т.п.
11Сервис СМС не предоставляется. Например, услуга СМС не подключена или временно заблокирована
12Ошибка в мобильном устройстве абонента
13У абонента включен запрет на прием сообщений или абонент временно заблокирован оператором (например, в связи с отрицательным балансом)
245Время ожидания статуса доставки истекло
252Заблокировано спам-фильтром: запрещена отправка сообщений на данный номер абонента.
253Заблокировано спам-фильтром: текст сообщения содержит запрещенные слова.
254Заблокировано спам-фильтром: запрещена отправка сообщений с данного имени отправителя.
255Внутренняя ошибка оператора. Например, ошибка маршрутизации, ошибка коммутатора (внутренняя ошибка передачи данных) и т.п.
300Время ожидания статуса доставки истекло
400Ошибка в параметрах запроса на отправку
401Ошибка в реквизитах доступа: логин/пароль
402Превышен лимит сообщений
403Доступ к HTTP API с указанными реквизитами запрещен (не настроено подключение)
406Невалидный формат адреса получателя
408Превышена максимально разрешенная скорость отправки сообщений
409Отправка сообщения-дубликата запрещена
414Превышена максимальная длина текста сообщения
423Отправка сообщения запрещена за фрод
500Абонент заблокировал имя отправителя (для месенджеров)
501У абонента отсутствует приложение для получения сообщения (для мессенджеров и push)

3.1.3 Пример вызова

Ниже приведен пример callback-вызова, демонстрирующий сигнатуру запроса коммуникационной платформы в сторону клиента.

{
"txId": "7591a05e-f22b-4548-b824-915b617e2778",
"updatedAt": "2020-11-16T10:27:46.595Z",
"state": "DELIVERED",
"channel": "sms",
"trackData": {
"tag": "0123456789",
"otherTag": "0987654321"
},
"error": {
"code": 0,
"message": "Успешная доставка"
}
}

3.2. Опросная схема

Для получения статуса сервер клиента отправляет GET-запрос, передавая идентификатор сообщения, который был получен им при отправке по HTTP. Статус хранится двое суток, забрать статус можно несколько раз, при этом он может изменяться.

GET https://my.seven.tech/messaging/v1/check-status/{txId}

NameTypeDescription
txId
required
string
uuid
Идентификатор сообщения

Параметры запроса и Коды ошибок такие же, как при нотификационной схеме.

4. Передача входящих сообщений (incoming)

POST https://partner.url/incoming

4.1 Параметры запроса

NameTypeDescription
txId
required
string
uuid
Идентификатор сообщения
channel
required
enumКанал доставки. Значения:
sms - СМС-сообщения
whatsapp — мессенджер Viber
viber - мессенджер Viber
recipient
required
recipientПолучатель сообщения (абонент, отправивший сообщение) (структура описана отдельно)
sender
required
string
maxLength: 21
Имя отправителя, на которое отправили сообщение
text
optional
string
maxLength: 2000
Текст сообщения
attachments
optional
attachmentsВложения сообщения (структура описана отдельно)
acceptedAt
optional
string
datetime
Дата и время получения сообщения
outgoingTxId
optional
string
uuid
txId сообщения на которое ответил абонент

4.1.1 Цитирование сообщений

NameTypeDescription
replyOn
optional
objectПризнак цитирования
txId
required
string
uuid
Идентификатор сообщения, которое процитировали в ответе
type
required
enumТип сообщения, которое процитировали в ответе: OUTGOING, INCOMING
"replyOn": {
"txId": "7591a05e-f22b-4548-b824-915b617e2778",
"type": "OUTGOING"
}

4.2 Пример запроса

Пример входящего запроса

{
"txId": "7591a05e-f22b-4548-b824-915b617e2778",
"channel": "sms",
"recipient": {
"type": "MSISDN",
"value": "79012223344"
},
"sender": "Sender",
"text": "Текст тестового сообщения",
"acceptedAt": "2021-10-12T13:45:54.487Z"
}

Пример входящего сообщения из мессенджеров

{
"txId": "7591a05e-f22b-4548-b824-915b617e2778",
"channel": "whatsapp",
"recipient": {
"type": "MSISDN",
"value": "79012223344"
},
"sender": "Sender",
"text": "Текст тестового сообщения",
"attachments": [
{
"type": "IMAGE",
"url": "http://content.url"
}
],
"acceptedAt": "2021-10-12T13:45:54.487Z",
"outgoingTxId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}