Форматы payload по каналам

Коротко: поле payload в запросе OMNI API имеет свой формат для каждого канала. Здесь собраны все форматы с примерами JSON.

Кому подходит

Роль: Разработчик, Интегратор
Уровень: Опытный

Что это

Общая структура запроса одинаковая для всех каналов. Отличается только поле payload — его формат зависит от канала, указанного в поле channel.

SMS (channel: 1)

Поле	Тип	Обязательно	Что указать
text	string	Да	Текст сообщения

Пример:

{
  "payload": {
    "text": "Тестовое сообщение"
  }
}

RCS (channel: 2)

RCS использует объект RCSMessage. Можно отправить один из типов:

Поле	Тип	Что означает
textMessage	string	Текстовое сообщение
fileMessage	object	Файл
audioMessage	object	Аудиосообщение
geolocationPushMessage	object	Геолокация
richcardMessage	object	Ричкарта
suggestedChipList	object	Кнопки ответа/действий
isTyping	string	Индикатор набора текста (`active` или `idle`)

Пример простого текста:

{
  "payload": {
    "RCSMessage": {
      "textMessage": "Это простое текстовое сообщение"
    }
  }
}

Пример ричкарты:

{
  "payload": {
    "RCSMessage": {
      "richcardMessage": {
        "layout": {
          "cardOrientation": "VERTICAL",
          "titleFontStyle": ["bold"],
          "descriptionFontStyle": ["italic"]
        },
        "content": {
          "media": {
            "height": "SHORT_HEIGHT",
            "mediaUrl": "https://<домен>/files/pepsi.png",
            "thumbnailUrl": "https://<домен>/files/thumb",
            "mediaContentType": "image/png",
            "mediaFileSize": 791264,
            "thumbnailContentType": "image/png",
            "thumbnailFileSize": 4013
          },
          "title": "Заголовок карточки",
          "description": "Текст описания",
          "suggestions": [
            { "reply": { "displayText": "Первый ответ" } },
            { "reply": { "displayText": "Второй ответ" } }
          ]
        }
      }
    }
  }
}

Пример файла:

{
  "payload": {
    "RCSMessage": {
      "fileMessage": {
        "fileUrl": "https://<домен>/files/document.pdf",
        "fileMIMEType": "application/pdf",
        "fileSize": 12345,
        "fileName": "document.pdf"
      }
    }
  }
}

Пример геолокации:

{
  "payload": {
    "RCSMessage": {
      "geolocationPushMessage": {
        "pos": "59.94 30.31",
        "label": "Эрмитаж",
        "radius": 100
      }
    }
  }
}

Viber (channel: 3)

Поле	Тип	Обязательно	Что указать
text	string	Да	Текст сообщения
imageUrl	string	Нет	URL изображения
buttonUrl	string	Нет	URL кнопки
buttonCaption	string	Нет	Текст кнопки

Пример:

{
  "payload": {
    "text": "У нас акция. Подробнее: https://example.com",
    "imageUrl": "https://<домен>/files/promo.jpg",
    "buttonUrl": "https://example.com/order",
    "buttonCaption": "Заказать"
  }
}

WhatsApp (channel: 4)

WhatsApp использует поле type для выбора типа сообщения. Возможные значения: template, text, image, video, audio, document, location, contacts, sticker, interactive.

Текстовое сообщение

{
  "payload": {
    "recipient_type": "individual",
    "type": "text",
    "preview_url": true,
    "text": {
      "body": "Текст сообщения"
    }
  }
}

Шаблон

{
  "payload": {
    "recipient_type": "individual",
    "type": "template",
    "template": {
      "namespace": "<namespace>",
      "name": "<template_name>",
      "language": {
        "code": "en",
        "policy": "deterministic"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Alex" },
            { "type": "text", "text": "1234" }
          ]
        }
      ]
    }
  }
}

Медиафайл

{
  "payload": {
    "type": "image",
    "image": {
      "link": "https://<домен>/files/image.png",
      "caption": "Подпись к изображению"
    }
  }
}

Возможные типы медиа: image, video, audio, document, sticker. Для каждого — свои поля (link, caption, filename).

Геолокация

{
  "payload": {
    "type": "location",
    "location": {
      "latitude": 59.94,
      "longitude": 30.31,
      "name": "Эрмитаж",
      "address": "Санкт-Петербург"
    }
  }
}

WeChat (channel: 6)

Тип	Что указать
Только текст	Текст сообщения (до 2000 символов)
Файл	Изображение (jpg, jpeg, png, gif, до 10 МБ)

Пример текста:

{
  "payload": {
    "type": "text",
    "text": "Текст сообщения"
  }
}

Email (channel: 7)

Поле	Тип	Обязательно	Что указать
subject	string	Нет	Тема письма
subtitle	string	Нет	Подзаголовок (сейчас не влияет)
body.rendered	array	Да	Массив тел письма

Поля элемента rendered:

Поле	Тип	Что указать
contentType	string	`html`, `mjml` или `plainText`
content	string	Тело письма

Пример:

{
  "payload": {
    "subject": "Тема письма",
    "subtitle": "Подзаголовок",
    "body": {
      "rendered": [
        {
          "contentType": "html",
          "content": "<html>Текст письма</html>"
        }
      ]
    }
  }
}

Telegram Gateway (channel: 8)

Поле	Тип	Обязательно	Что указать
code	integer	Да*	Готовый код (4–8 цифр)
code_length	integer	Да*	Длина кода для генерации (4–8). Игнорируется, если указан `code`
ttl	integer	Нет	Время жизни кода в секундах (30–3600)

*- нужен либо code, либо code_length.

Пример:

{
  "channel": 8,
  "contact": "905518709790",
  "senderId": "transit",
  "isOtp": true,
  "payload": {
    "code_length": 5,
    "ttl": 300
  }
}

Telegram (channel: 9)

Поле	Тип	Обязательно	Что указать
type	string	Да	`text`, `photo`, `video`, `audio`, `voice`, `document`
photo / video / audio / voice / document	object	Да*	Объект медиа

Поля медиа:

Поле	Тип	Что указать
link	string	URL файла
caption	string	Подпись

*- нужен один из медиа-объектов.

Пример текста:

{
  "payload": {
    "type": "text",
    "text": "Привет"
  }
}

Пример фото:

{
  "payload": {
    "type": "photo",
    "photo": {
      "link": "https://<домен>/files/photo.png",
      "caption": "Хорошее фото"
    }
  }
}

Push (channel: 10)

Поле	Тип	Обязательно	Что указать
notification	object	Да	Объект push-уведомления
notification.title	string	Да*	Заголовок
notification.body	string	Да*	Текст
notification.image	string	Нет	URL изображения

*- нужен хотя бы один из блоков: title, body или image.

Пример:

{
  "payload": {
    "notification": {
      "title": "Заголовок",
      "body": "Текст уведомления",
      "image": "https://<домен>/files/promo.png"
    }
  }
}

TTS (channel: 11)

Поле	Тип	Обязательно	Что указать
text	string	Да	Текст, который будет озвучен
language	string	Да	Код языка (`en`, `ru` и так далее)
repeat_count	integer	Нет	Сколько раз повторить (1, 2 или 3)

Пример:

{
  "payload": {
    "text": "31245",
    "language": "ru",
    "repeat_count": 1
  }
}

Mobile Push (channel: 13)

Поле	Тип	Обязательно	Что указать
title	string	Да	Заголовок уведомления
body	string	Да	Текст уведомления

Пример:

{
  "payload": {
    "title": "Ваш промокод",
    "body": "1111"
  }
}

FlashCall (channel: 14)

Поле	Тип	Обязательно	Что указать
code	string	Да	Последние цифры входящего звонка
dial_timeout	string	Нет	Секунды до завершения звонка, если не ответили

Пример:

{
  "payload": {
    "code": "1234",
    "dial_timeout": 5
  }
}

Общие правила

Для всех каналов работают общие параметры запроса: contact, channel, senderId, webhook, clientInfo, isOtp. Подробнее — OMNI API — отправка сообщений.

Если сообщение содержит одноразовый код — установите isOtp: true, чтобы содержимое скрывалось в EDR.

См. также

OMNI API — отправка сообщений

Эндпоинты, параметры, каскад, шаблоны

Подключение к API

Аутентификация, базовый URL

Вебхуки

Статусы сообщений

Обработка ошибок API

HTTP-коды и форматы ответов

Нужна помощь?

Multi API: support@multiapi.ru