Руководство по эксплуатации: интеграция по API

1. Авторизация
2. Метод отправки сообщения
3. Возврат статуса (callback)
- 3.1 Нотификационная схема
- 3.2 Опросная схема
4. Передача входящих сообщений (incoming)
- 4.1 Параметры запроса
  - 4.1.1 Цитирование сообщений
- 4.2 Пример запроса

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

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

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

Authorization: Basic Auth Username: username
Password: password

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

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

Authorization: Basic YWhhbWlsdG9uQGFwaWdlZS5jb206bXlwYXNzdzByZAo

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

POST https://hub.megafon.ru/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" },`
`schedule` _optional	`object`	Объект в API запросе, который используется для настройки отложенной отправки сообщения.

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 — объект в API запросе, который используется для настройки отложенной отправки сообщения

Name	Type	Description
`sendAfter` _{conditional (обязателен если нет startTime)}	`string`	Дата и время отправки сообщения, начиная с которых сообщение может быть отправлено. Учитывается всегда, независимо от значения useRecipientTimeZone. Входящий параметр sendAfter может быть передан в двух форматах: timestamp и datetime. - timestamp соответствует Unix Time (числовой формат), который представляет собой количество секунд с 1 января 1970 года. - datetime соответствует RFC 3339 (строковый формат), который представляет собой дату и время в формате `YYYY-MM-DDTHH:mm:ssZ` (с указанием смещения или в `UTC`). Система поддерживает оба формата для входящего параметра sendAfter, но рекомендуется использовать формат datetime для улучшения совместимости и читаемости данных.
`useRecipientTimeZone` _optional	`boolean`	Флаг, указывающий, учитывать ли часовой пояс абонента при применении временных ограничений startTime и stopTime. Если `null` или `false`, сообщение отправляется по времени `UTC`.
`startTime` _{conditional (обязателен если нет sendAfter)}	`string`	Время начала отправки сообщений в течение суток. Формат: `HH:mm:ss (UTC)`. Указывается только в связке с stopTime.
`stopTime` _{conditional (обязателен если есть startTime)}	`string`	Время окончания отправки сообщений в течение суток. Формат: `HH:mm:ss`

Рекомедуемые комбинации параметров объекта schedule:

startTime / stopTime + useRecipientTimeZone = true
sendAfter
sendAfter + startTime / stopTime + useRecipientTimeZone=true

Примечание: булевое значение useRecipientTimeZone влияет только на startTime / stopTime, но не на sendAfter.

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

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

{
  "scenario": [
    {
      "channel": "viber",
      "recipient": {
        "type": "MSISDN",
        "value": 79012223344
      },
      "sender": "Sender",
      "text": "Текст тестового сообщения",
      "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": "Sender",
      "text": "Текст тестового сообщения"
    }
  ],
  "callback": "https://callback_endpoint.url",
  "trackData": {
        "tag": "0123456789",
        "otherTag": "0987654321"
      }
}

2.2.1 Пример запроса с отложенной отправкой

{
  "scenario": [
    {
      "channel": "viber",
      "recipient": {
        "type": "MSISDN",
        "value": "79012223344"
      },
      "sender": "Sender",
      "text": "Текст тестового сообщения",
      "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": "Sender",
      "text": "Текст тестового сообщения",
      "failover": {
        "ttl": 12000,
        "condition_status": "DELIVERED"
      }
    }
  ],
  "callback": "https://callback_endpoint.url",
  "incomingTxId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "clientRequestId": "string",
  "trackData": {
    "customParamWichWillBeReturned": "customParamValue"
  },
  "meta": {
    "customParam": "customParamValue"
  },
  "urlOptions": {
    "shortenUrl": true
  },
  "schedule": {
    "sendAfter": "2024-10-09T10:00:00+03:00",
    "startTime": "08:00:00",
    "stopTime": "20: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" }`

Пример успешного ответа (http code 200)

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

Пример ответа с ошибкой (http code 200)

{
  "txId": "d0ecfd85-b8d2-4b9a-afe8-13cb236398d8",
  "updatedAt": "2020-11-16T11:10:19.528808",
  "trackData": {
    "tag": "0123456789",
    "otherTag": "0987654321"
  },
  "state": "FAILED",
  "error": {
    "code": 400,
    "message": "Scenario channels not unique"
  }
}

Пример ответа с ошибкой (http code не 200)

{
  "error": {
    "id": "123e4567-e89b-12d3-a456-4266554400012",
    "status": 401,
    "message": "Ошибка реквизитов доступа"
  }
}

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

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

При смене статуса сообщения на URL, указанный в запросе на отправку сообщения в параметре 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 — сообщение не отправлено UNKNOWN — состояние не определено
`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 Коды ошибок

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

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

{
  "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.1.4 Отправка колбэков батчами

[
  {
    "txId": "2f15af7f-2bf0-48b8-8273-c7c3f1bddb57",
    "updatedAt": "2023-10-04T13:46:45.412Z",
    "trackData": {
      "tag": "0123456799",
      "otherTag": "0987654322"
    },
    "channel": "sms",
    "state": "DELIVERED",
    "error": {
      "code": 0,
      "message": "Успешная доставка"
    }
  },
  {
    "txId": "7591a05e-f22b-4548-b824-915b617e2778",
    "updatedAt": "2023-10-04T13:45:45.412Z",
    "state": "DELIVERED",
    "channel": "sms",
    "trackData": {
      "tag": "0123456789",
      "otherTag": "0987654321"
    },
    "error": {
      "code": 0,
      "message": "Успешная доставка"
    }
  }
]

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

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

GET https://hub.megafon.ru/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"
}

Руководство по эксплуатации: интеграция по API

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 — объект в API запросе, который используется для настройки отложенной отправки сообщения​

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

2.2.1 Пример запроса с отложенной отправкой​

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

2.3.1 Коды HTTP​

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

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

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

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

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

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

3.1.4 Отправка колбэков батчами​

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

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

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

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

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