«Коммуникационная платформа SevenTech» - Руководство по эксплуатации: интеграция по API
- «Коммуникационная платформа SevenTech» - Руководство по эксплуатации: интеграция по API
- 1. Авторизация
- 2. Метод отправки сообщения
- 3. Возврат статуса (callback)
- 4. Передача входящих сообщений (incoming)
1. Авторизация
Есть возможность настроить авторизацию двумя способами:
- Для подключения используется тип авторизации Basic Auth, для организации доступа клиент получает пару логин и пароль и вводит запрашиваемые значения в соответствующие поля:
Authorization: Basic Auth
Username: username
Password: password
- При подключении клиент получает пару логин и пароль, которые требуются для авторизации, для чего необходимо закодировать пару
логин:пароль
алгоритмом Base64 и передать в виде заголовкаAuthorization
HTTP-запроса или через query-параметр
Пример закодированного заголовка HTTP Basic Authentication:
Authorization: Basic YWhhbWlsdG9uQGFwaWdlZS5jb206bXlwYXNzdzByZAo
2. Метод отправки сообщения
POST https://my.seven.tech/messaging/v1/send
2.1 Параметры
Параметры описываются в формате JSON и могут иметь один или несколько базовых элементов scenario.
Name | Type | Description |
---|---|---|
scenario required | scenario | Массив элементов описывающий процесс передачи сообщения (структура описана отдельно) |
callback optional | string | URI для отправки отчета о доставке. |
clientRequestId optional | string | Идентификатор клиентского запроса, максимальная длина 100 симв олов |
urlOptions optional | object | Параметры сокращения ссылок в сообщении. Для включения такой возможности нужно обратиться к вашему менеджеру. |
trackData optional | object | Набор параметров, которые будут возвращены в callback , пример: "trackData": { "tag": "12345678" }, |
2.1.1 scenario — сценарий отправки сообщения
Name | Type | Description |
---|---|---|
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 | string | DeepLink при нажатии на push сообщение, используется только для канала push |
mobilePushTitle optional | string | Title для push сообщения, используется только для канала push |
2.1.1.1 recipient — получатель сообщения
Name | Type | Description |
---|---|---|
type required | enum | Тип получателя. Значения: MSISDN - номер абонента в формате [E.164] (https://en.wikipedia.org/wiki/E.164) |
value required | string maxLength: 200 | Значение адреса получателя |
2.1.1.2 attachments — медиаконтент сообщения
Name | Type | Description |
---|---|---|
type required | enum | Тип контента. Значения: IMAGE — изображение AUDIO — аудио файл VIDEO – видео файл FILE — файл |
url required | string | Ссылка на медиаконтент |
2.1.1.3 buttons — кнопка сообщения
Name | Type | Description |
---|---|---|
caption required | string | Текст кнопки |
action required | string | Ссылка, которая откроется, при нажатии на кнопку |
2.1.1.4 failover — стратегия отправки по альтернативному каналу (каскадирование)
Name | Type | Description |
---|---|---|
ttl optional | integer max:259200 | Время ожидания (в секундах) статуса доставки или прочтения (в зависимости от condition_status ). |
condition_status optional | enum | Тип ожидаемого статуса в период ttl :DELIVERED SEEN |
2.1.2 urlOptions — параметры обработки ссылок
Name | Type | Description |
---|---|---|
shortenUrl required | boolean | Флаг true означает, все ссылки, длина которых более 20 символа, будут заменены на короткие ссылки формата wsl.am/Aa34Zz7. Это позволит сократить длину сообщения и формировать отчеты по переходам по этим ссылкам. |
2.1.3 schedule — параметр ы отложенной отправки
Name | Type | Description |
---|---|---|
sendAfter conditional (обязателен если нет startTime) | string | Дата и время отправки сообщения, в формате формате YYYY-MM-DDTHH:mm:ssZ (RFC 3339), начиная с которых сообщение может быть отправлено. |
startTime conditional (обязателен если нет sendAfter) | string | Время начала отправки сообщений в формате HH:MM:SS |
stopTime conditional (обязателен если есть startTime) | string | Время окончания отправки сообщений в формате HH:MM:SS , если сообщение не успевает отправиться до этого времени, то отправка откладывается на следующий день |
useRecipientTimeZone optional | boolean | Учёт часового пояса абонента. Если null или false , сообщение отправляется по времени UTC, true - система автоматически определяет часовой пояс абонента по MSISDN и время, указанное в параметрах запроса, рассчитывается относительно времени получателя. |
Возможные комбинации параметров:
sendAfter
sendAfter + useRecipientTimeZone
startTime + stopTime
startTime + stopTime + useRecipientTimeZone
sendAfter + useRecipientTimeZone + startTime + stopTime
sendAfter + startTime + stopTime
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
},
"schedule": {
"sendAfter": "2025-03-26T11:20:19.329Z",
"startTime": "10:00:00",
"stopTime": "18:00:00",
"useRecipientTimeZone": true
}
}
2.3 Ответ на запрос
2.3.1 Коды HTTP
Code | Description |
---|---|
200 | Запрос принят и обработан |
400 | О шибка в формате запроса |
401 | Доступ API с указанными реквизитами запрещен. Проверить логин/пароль |
403 | Ошибка авторизации, нет прав для использования API или IP запрещен |
2.3.2 Расширенная информация в теле ответа
Name | Type | Description |
---|---|---|
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"
}
}