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

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

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 tgotp - отправка кодов авторизации в мессенджер Telegram Каналы подключаются по согласованию с менеджером
`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 Пример запроса

2.2.1 Viber - SMS

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

{
    "scenario": [
        {
            "channel": "viber",
            "recipient": {
                "type": "MSISDN",
                "value": "79012223344"
            },
            "sender": "myname",
            "text": "Текст сообщения viber",
            "attachments": [
                {
                    "type": "IMAGE",
                    "url": "http://content.url"
                }
            ],
            "buttons": [
                {
                    "caption": "button text",
                    "action": "https://action.url"
                }
            ],
            "failover": {
                "ttl": 600,
                "condition_status": "DELIVERED"
            }
        },
        {
            "channel": "sms",
            "recipient": {
                "type": "MSISDN",
                "value": 79012223344
            },
            "sender": "myname",
            "text": "Текст sms-сообщения"
        }
    ],
    "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.2.2 Whatsapp

{
    "scenario": [
        {
            "channel": "whatsapp",
            "recipient": {
                "type": "MSISDN",
                "value": "79012223344"
            },
            "sender": "myname",
            "text": "Текст сообщения whatsapp",
            "failover": {
                "ttl": 600,
                "condition_status": "DELIVERED"
            }
        }
    ],
    "callback": "https://callback_endpoint.url",
    "clientRequestId": "string",
    "trackData": {
        "customParamWichWillBeReturned": "customParamValue"
    }
}

2.2.3 Telegram

{
    "scenario": [
                         {
            "channel": "tgotp",
            "recipient": {
                "type": "MSISDN",
                "value": "79012223344"
            },
            "sender": "Telegram",
            "text": "123464",
            "failover": {
                "ttl": 3600,
                "condition_status":"DELIVERED"
            }
        }
    ]
}

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"
  }
}

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

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

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

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

POST https://partner.url/callback

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

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

3.1.2 Коды ошибок

Code	Description
`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}

Name	Type	Description
`txId` _required	`string` _uuid	Идентификатор сообщения

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

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

POST https://partner.url/incoming

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

Name	Type	Description
`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 Цитирование сообщений

Name	Type	Description
`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"
}

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

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

2.1 Параметры​

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

2.1.1.1 recipient — получатель сообщения​

2.1.1.2 attachments — медиаконтент сообщения​

2.1.1.3 buttons — кнопка сообщения​

2.1.1.4 failover — стратегия отправки по альтернативному каналу (каскадирование)​

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

2.1.3 schedule — параметры отложенной отправки​

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

2.2.1 Viber - SMS​

2.2.2 Whatsapp​

2.2.3 Telegram​

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

2.3.1 Коды HTTP​

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

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

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

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

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

3.1.2 Коды ошибок​

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

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

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

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

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

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