Отправка шаблонного сообщения

Отправка шаблонного сообщения WhatsApp на один или несколько номеров телефонов. Поддерживаются каналы WABA Coexistence (Meta Cloud API) и устаревший WABA (GupShup).

Эндпоинт

POST https://microservice.pleep.app/api/v1/messages/send-template

Заголовки

// POST /api/v1/messages/send-template
// X-API-Key: YOUR_API_KEY

{
  "bot_id": "your-bot-id",
  "channel": "waba_coexistence",
  "to": {
    "phone": "+77001234567"
  },
  "template_id": "welcome_template",
  "template_language": "ru"
}

// Ответ появится здесь после отправки запроса

Перед началом

Перед отправкой запроса вам нужно собрать несколько параметров: шаблон, Bot ID и канал. Ниже — пошаговая инструкция.

Шаг 1. Создайте шаблон

Перейдите в вашего AI-агента, затем в левом меню выберите Рассылки.

Если у вас ещё нет шаблона, нажмите Создать рассылку и создайте шаблон. Вы можете использовать переменные {{1}}, {{2}} и т.д. в тексте шаблона — например, для обращения к клиенту по имени. Шаблоны с переменными можно отправлять только через API.

После создания шаблон отправляется на модерацию в Meta. Дождитесь статуса Одобрен — только после этого шаблон можно использовать для отправки.

Подробнее о шаблонах читайте в разделе Рассылки → Шаблоны.

Шаг 2. Скопируйте Template ID

В разделе Рассылки найдите блок Мои шаблоны. Выберите нужный шаблон и нажмите на текст Template ID — он автоматически скопируется в буфер обмена.

Шаг 3. Найдите Bot ID

Перейдите в Интеграции, выберите вашу интеграцию WhatsApp Business и нажмите Управление. На странице интеграции вы увидите поле Bot ID — нажмите на иконку копирования, и Bot ID скопируется автоматически.

Шаг 4. Определите канал

Значение поля channel зависит от типа вашей интеграции WhatsApp:

Тело запроса

Объект получателя

Каждый получатель в поле to имеет следующую структуру:

Правила использования params

• params — необязательное поле. Указывайте его только если шаблон содержит переменные ({{1}}, {{2}} и т.д.)
• Если шаблон не содержит переменных — не передавайте поле params вообще
• Пустые строки в params запрещены — API вернёт ошибку 422 VALIDATION_ERROR при передаче "params": [""]
• Пустой массив "params": [] обрабатывается как отсутствие параметров

Примеры

Шаблон с переменными

{
  "bot_id": "your-bot-id",
  "channel": "waba_coexistence",
  "to": {
    "phone": "+77001234567",
    "params": ["Иван", "25.03.2026"]
  },
  "template_id": "welcome_template"
}

Шаблон без переменных

{
  "bot_id": "your-bot-id",
  "channel": "waba_coexistence",
  "to": {
    "phone": "+77001234567"
  },
  "template_id": "simple_greeting"
}

Несколько получателей (массовая отправка)

{
  "bot_id": "your-bot-id",
  "channel": "waba_coexistence",
  "to": [
    { "phone": "+77001234567", "params": ["Иван"] },
    { "phone": "+77009876543", "params": ["Мария"] },
    { "phone": "+77005551234", "params": ["Алексей"] }
  ],
  "template_id": "welcome_template",
  "template_language": "ru"
}

{
  "to": { "phone": "+77001234567", "params": [""] }
}

Ответы

Один получатель — успех

{
  "ok": true,
  "data": {
    "message_id": "wamid.HBgLNzcwMDEyMzQ1NjcVAgASGBQzRUI..."
  }
}

Массовая отправка — успех

{
  "ok": true,
  "data": {
    "total": 3,
    "sent": 2,
    "failed": 1,
    "results": [
      { "phone": "+77001234567", "ok": true, "message_id": "wamid.HBg..." },
      { "phone": "+77009876543", "ok": true, "message_id": "wamid.HBg..." },
      { "phone": "+77005551234", "ok": false, "error": "PROVIDER_ERROR", "message": "Некорректный номер телефона" }
    ]
  }
}

Коды ошибок

Формат ответа с ошибкой

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "params contains empty strings. Either provide actual values or omit the params field entirely.",
    "status": 422
  }
}

Ошибка провайдера (PROVIDER_ERROR)

При ошибке PROVIDER_ERROR ответ включает поле provider_response с исходным ответом от Meta или GupShup. Используйте его для отладки:

{
  "ok": false,
  "error": {
    "code": "PROVIDER_ERROR",
    "message": "Request failed with status code 400",
    "status": 502
  },
  "provider_response": {
    "error": {
      "message": "(#100) Invalid parameter",
      "type": "OAuthException",
      "code": 100
    }
  }
}