Rich-сообщения

Текст и изображения

Rich-форматы

Помимо обычной текстовой рекламы Sidekick поддерживает четыре rich-формата на основе rich-сообщений Telegram Bot API 10.3. Сервер собирает все параметры вызова Bot API, а ваш бот или SDK только добавляет chat_id и отправляет их. Всё включается явно: боты, которые не объявили поддержку rich-форматов, сохраняют прежнее поведение без изменений.

Дополнительные поля запроса

Три необязательных поля для POST /api/v1/ad (и inject()). Если пропустить их все, ничего не изменится: вы получите обычную текстовую рекламу. Неизвестные значения accept_formats сервер игнорирует, а не отклоняет, поэтому новая версия SDK продолжит получать рекламу и от старого сервера.

Ответ — получена rich-реклама

{
  "message": "Here is your answer.\n\nРеклама от Sidekick 👇\n\nTry Example for your next project.",
  "has_ad": true,
  "impression_id": "imp_example",
  "ad": {
    "text": "Try Example for your next project.",
    "formatted_text": "Try Example for your next project.",
    "button_text": "Learn more",
    "button_url": "https://sidekick-ads.com/api/v1/click/imp_example",
    "format": "response",
    "send": {
      "method": "sendRichMessage",
      "params": {
        "rich_message": {
          "blocks": [
            {
              "type": "paragraph",
              "text": [
                {
                  "type": "bold",
                  "text": "Example"
                }
              ]
            },
            {
              "type": "paragraph",
              "text": "Try Example for your next project."
            },
            {
              "type": "buttons",
              "align": "left",
              "buttons": [
                {
                  "text": "Learn more",
                  "style": "primary",
                  "url": "https://sidekick-ads.com/api/v1/click/imp_example"
                }
              ]
            },
            {
              "type": "footer",
              "text": "Sponsored · реклама подобрана Sidekick"
            }
          ]
        }
      }
    },
    "fallback": {
      "format": "text",
      "text": "Try Example for your next project.",
      "formatted_text": "Try Example for your next project.",
      "button_text": "Learn more",
      "button_url": "https://sidekick-ads.com/api/v1/click/imp_example"
    }
  }
}

• •ad.send — готовый вызов Bot API: передайте send.params с вашим chat_id в метод send.method. Медиа внутри блоков заданы HTTPS-ссылками: Telegram скачивает их при отправке, загружать файлы со своей стороны не нужно.
• •Основное правило: message — всегда обычная текстовая версия (ваш ответ с добавленной рекламой), а ad.fallback содержит её части в отдельных полях, с разметкой для вашего parse_mode. При любой ошибке Telegram отправьте их вместо rich-сообщения. Rich-реклама не должна нарушать работу бота.
• •send.ephemeral: true (первая сцена в группе для бота-администратора) означает отправку, видимую только целевому пользователю. Если Telegram вернул BOT_NOT_ADMIN (права изменились после обновления кеша), повторите отправку тех же параметров без ephemeral_message_parameters. Метод send в SDK делает это автоматически.
• •Интерактивные кнопки consent и quiz содержат callback_data с префиксом sk:. Передайте нажатие в POST /api/v1/ad/interact с тем же Bearer-токеном: сервер подготовит следующую сцену и вернёт новый объект { method, params } для отправки. Передайте тот же объект capabilities , что и в /ad — без custom_emoji вместо логотипа будет название бренда жирным шрифтом. SDK передаёт возможности повторно автоматически. Нажатия бесплатны: оплата следует модели кампании — за показ в CPM или за подтверждённое действие в CPA. За само нажатие плата не взимается; переходы проходят через адрес отслеживания.