WhatsApp Template API

API для разработчиков

Отправляйте одобренные шаблоны WhatsApp из своих систем одним вызовом API; дальше диалог продолжается в MonoChat.

WhatsApp
REST API
Только API

Установить из MonoStore Подробнее на monochat.ai

Обзор

WhatsApp Template API позволяет вашей CRM, ERP, интернет-магазину или любому бэкенду отправить клиенту одобренное шаблонное сообщение WhatsApp через MonoChat. В одном запросе указываются номер WhatsApp, с которого отправлять, номер телефона клиента, шаблон и его переменные.

Когда клиент отвечает, диалог попадает во входящие MonoChat, как любой другой. У приложения нет собственных экранов: всё происходит через три API-эндпоинта.

Основные возможности

Один вызов API. Отправьте шаблон по имени и языку, подставив переменные заголовка, текста, кнопок и карусели из ваших данных.
Прямо в чат. Каждая отправка возвращает идентификатор диалога и прямую ссылку на него в MonoChat.
Новые клиенты — не проблема. Если номера телефона ещё нет среди клиентов, клиент создаётся с указанным вами именем.

Установка и настройка

Подключите свой номер WhatsApp Business к MonoChat и убедитесь, что он верифицирован и у него есть шаблоны, одобренные Meta.
Установите WhatsApp Template API в разделе Настройки › MonoStore › Приложения или откройте ссылку для установки app.monochat.ai/apps/K6u29LpbwCHBozZ8o. Если у вас ещё нет аккаунта MonoChat, по ссылке можно сначала зарегистрироваться, и приложение установится автоматически.
Создайте API-токен в разделе Профиль › API-токены. Токен показывается только один раз, поэтому скопируйте его сразу.
Вызовите template/list.js, чтобы увидеть одобренные шаблоны и их переменные.
Вызовите template/send.js с номером клиента и значениями переменных, чтобы отправить первый шаблон.

Список приложений MonoStore в настройках MonoChat, включая WhatsApp Template API

Сведения о WhatsApp Template API в MonoStore с кнопкой «Установить»

примечание

Каждое сообщение тарифицируется как любое шаблонное сообщение, отправленное из MonoChat.
URL медиафайлов должны оставаться доступными, пока WhatsApp не загрузит файл.
Отправляйте тем клиентам, которые согласились получать от вас сообщения: WhatsApp может ограничить номера, сообщения которых блокируют или на которые жалуются.

Возможности

Список шаблонов

Одобренные шаблоны номера WhatsApp с их языком, категорией, статусом и переменными, чтобы ваша система знала, что можно отправить.

Отправка шаблона

По имени и языку шаблона, с переменными заголовка, текста, кнопок и карусели. Отсутствующее значение останавливает отправку, поэтому клиенту не уходит наполовину заполненное сообщение.

Назначение сотруднику

Укажите email сотрудника, и диалог откроется на его имя.

Медиазаголовки

Получите краткоживущие учётные данные для загрузки, разместите изображение, видео или документ в хранилище MonoChat и используйте его URL как заголовок шаблона.

Ссылка на диалог

Каждая отправка возвращает идентификатор сессии, идентификатор сообщения и ссылку, открывающую диалог в MonoChat.

Понятные ошибки

Неудачный вызов сообщает, что пошло не так, например «Channel not found» или «Variable missing».

Перед началом работы

Ваш номер WhatsApp Business подключён к MonoChat и верифицирован. См. Каналы.
Шаблоны, которые вы хотите отправлять, одобрены Meta. Шаблоны — это способ написать первым или связаться с клиентом вне 24-часового окна. См. Шаблонные сообщения.
У вас есть API-токен из раздела Профиль › API-токены. См. API-токены.
Вы знаете свой tenant slug: часть адреса MonoChat после /tenants/. В адресе https://app.monochat.ai/tenants/mybusiness slug — это mybusiness.

Справочник API

У приложения нет собственных экранов. Всё происходит через три эндпоинта, каждый из которых — POST с телом в формате JSON:

POST https://app.monochat.ai/api/<slug>/custom-functions/template-app/api/<endpoint>
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

Эндпоинт	Что делает
`template/list.js`	Возвращает список шаблонов одного из ваших номеров WhatsApp с их переменными.
`template/send.js`	Отправляет шаблон клиенту и возвращает ссылку на диалог.
`upload/get-token.js`	Выдаёт краткоживущие учётные данные для загрузки изображения, видео или документа для заголовка.

Номера телефонов всегда записываются с кодом страны и без +, например 905334445566. Успешный вызов возвращает 200 с данными эндпоинта в поле result.

1. Список шаблонов

POST /api/<slug>/custom-functions/template-app/api/template/list.js

Возвращает все шаблоны указанного номера WhatsApp Business: имя, код языка, категорию, компоненты (заголовок, текст, подвал, кнопки), типы переменных и статус одобрения.

Поле	Обязательное	Описание
`phoneNumber`	да	Ваш номер WhatsApp Business в MonoChat с кодом страны, без `+`.
`options`	нет	Постраничный вывод и фильтры, например `{ "pagination": { "currentPage": 1, "pageItems": 50 } }`.

POST /api/<slug>/custom-functions/template-app/api/template/list.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566"
}

Ответ (сокращённо):

{
  "result": {
    "templateMessages": [
      {
        "name": "new_product_announcement",
        "languageCode": "tr-TR",
        "category": "MARKETING",
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "variables": [
              { "type": "IMAGE", "value": null, "exampleValue": "https://.../sample-image.png" }
            ]
          },
          {
            "type": "BODY",
            "text": "Merhaba {{1}}, yeni ürünümüz {{2}} çıktı!",
            "sampleText": "Merhaba [Ayşe], yeni ürünümüz [XYZ Telefon] çıktı.",
            "variables": [
              { "type": "TEXT", "value": null, "exampleValue": "[Ayşe]" },
              { "type": "TEXT", "value": null, "exampleValue": "[XYZ Telefon]" }
            ]
          },
          {
            "type": "FOOTER",
            "text": "Teşekkürler",
            "sampleText": "Teşekkürler"
          }
        ],
        "status": "APPROVED"
      }
    ],
    "options": {
      "pagination": { "totalCount": 12, "currentPage": 1, "pageItems": 12, "totalPages": 1 }
    }
  }
}

Как это читать:

name: системное имя, с которым вы отправляете шаблон.
languageCode: язык, на котором его нужно отправить.
category: категория WhatsApp (MARKETING, UTILITY, AUTHENTICATION).
components: части, из которых состоит шаблон.

Компонент	Содержимое	Описание
`HEADER`	`IMAGE`, `VIDEO`, `DOCUMENT` или текст	Для медиа указывается `format`; переменные находятся в `variables`.
`BODY`	Текст с переменными	Текст сообщения с подстановками вроде `{{1}}`, `{{2}}`.
`FOOTER`	Текст	Обычно без переменных.
`BUTTONS`	URL, быстрый ответ…	Тексты кнопок и их переменные, если они есть.

Для приведённого выше шаблона нужны одно изображение для заголовка и два текста для тела (имя клиента и название товара). Подвал фиксированный («Teşekkürler»), кнопок нет.

2. Отправка шаблона

POST /api/<slug>/custom-functions/template-app/api/template/send.js

Отправляет клиенту одобренный шаблон. Если номера телефона ещё нет среди клиентов, клиент создаётся; диалог открывается (или используется существующий), и в нём отправляется шаблон.

Поле	Обязательное	Описание
`phoneNumber`	да	Номер WhatsApp Business, с которого отправлять. Он должен быть подключён к MonoChat и верифицирован.
`templateMessageName`	да	`name` шаблона в точности так, как его возвращает список.
`languageCode`	да	Язык шаблона так, как его возвращает список (например, `tr-TR`).
`customerPhoneNumber`	да	Номер WhatsApp клиента.
`variables`	если у шаблона есть переменные	Значения переменных шаблона (см. ниже).
`customerFirstName`, `customerLastName`	нет	Используются, если клиент новый для MonoChat.
`agentEmailAddress`	нет	Назначает диалог сотруднику с этим email.

Переменные. Каждый элемент массива variables содержит type и список parameters, указанные в порядке подстановок шаблона:

`type`	`parameters`
`HEADER`	Текстовая переменная заголовка или публичный URL изображения, видео или документа заголовка.
`BODY`	`{{1}}`, `{{2}}`, … тела по порядку.
`BUTTONS`	По одному значению для каждой кнопки с переменной (например, динамическая часть URL-кнопки или код купона) в порядке кнопок.
`CAROUSEL`	Вместо `parameters` — массив `cards` с одной записью на каждую карточку карусели, у каждой свои `components`.

{ "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "parameters": ["https://…/1.jpg"] }, { "type": "BODY", "parameters": ["…"] } ] } ] }

Отсутствующее значение останавливает отправку с ошибкой Variable missing, поэтому клиенту не уходит наполовину заполненное сообщение. У FOOTER переменные бывают редко.

POST /api/<slug>/custom-functions/template-app/api/template/send.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566",
  "templateMessageName": "new_product_announcement",
  "languageCode": "tr-TR",
  "customerPhoneNumber": "905306667788",
  "customerFirstName": "Ayşe",
  "agentEmailAddress": "sarah@yourcompany.com",
  "variables": [
    { "type": "HEADER", "parameters": ["https://…/product.jpg"] },
    { "type": "BODY", "parameters": ["Ayşe", "XYZ Phone"] }
  ]
}

Ответ:

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "…",
    "messageId": "…"
  }
}

url: открывает диалог в MonoChat для тех, кто вошёл в систему и имеет право его видеть.
sessionId: идентификатор диалога.
messageId: идентификатор сообщения в MonoChat. Статусы его доставки и прочтения отображаются в чате, как у любого другого сообщения.

Медиа в шаблонах. WhatsApp скачивает медиафайл заголовка по указанному вами URL, поэтому URL должен быть действительным и общедоступным. Ссылки, требующие входа в систему, не работают. Если вы загрузили файл через upload/get-token.js, используйте URL файла, составленный по ответу этого эндпоинта.

3. Загрузка медиа для заголовка

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js

Если заголовок шаблона — изображение, видео или документ, у файла должен быть публичный адрес, по которому WhatsApp сможет его скачать. Этот эндпоинт выдаёт краткоживущее разрешение на размещение файла в хранилище MonoChat.

Поле	Обязательное	Описание
`fileName`	да	Имя файла с расширением, например `product.jpg` или `promo.pdf`.

Файлы всегда сохраняются в папке chat-assets вашего рабочего пространства; более старые примеры, в которых передаётся поле key, продолжают работать, это значение не требуется.

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "product.jpg"
}

Ответ сообщает, куда поместить файл, и содержит учётные данные для этого:

Поле	Описание
`bucket`, `region`, `path`	Куда помещается файл.
`temporaryCredentials`	Учётные данные только для загрузки в этот единственный путь, действительные 15 минут.
`baseUrl`	Публичный адрес хранилища. URL файла — это `baseUrl` + `/` + `path`.

Сразу загрузите файл любым клиентом S3 с этими учётными данными, а затем передайте его URL как параметр HEADER при отправке шаблона. Очень большие файлы или форматы, которые WhatsApp не поддерживает (он принимает распространённые форматы изображений, видео и PDF), вызывают ошибку.

Пример: шаблон с изображением в заголовке

Допустим, у вас есть одобренный шаблон new_product_announcement с изображением в заголовке и двумя переменными в тексте (имя клиента и название товара), и вы хотите отправить его клиенту.

Получите список шаблонов. Вызовите template/list.js с вашим номером WhatsApp и найдите new_product_announcement. В его компонентах видна одна переменная IMAGE в заголовке и две переменные TEXT в тексте.
Загрузите изображение. Вызовите upload/get-token.js с { "fileName": "urun.jpg" }, загрузите файл с полученными учётными данными и составьте его URL из baseUrl и path.
Отправьте шаблон. Вызовите template/send.js, передав URL файла как параметр HEADER и ["Ayşe", "XYZ Telefon"] как параметры BODY ({{1}} → Ayşe, {{2}} → XYZ Telefon). Если бы у шаблона были переменные кнопок, вы бы добавили элемент BUTTONS таким же образом.
Откройте чат. url из ответа открывает диалог; когда клиент отвечает, диалог продолжается во входящих MonoChat.

Ошибки

Неудачный вызов возвращает статус ошибки и сообщение, в котором сказано, что пошло не так. Записывайте эти сообщения в журнал своей системы и при необходимости показывайте пользователям понятное сообщение.

Сообщение	Причина
`phoneNumber field is required`	`template/list.js` вызван без `phoneNumber`.
`phoneNumber, templateMessageName, customerPhoneNumber fields are required`	Отсутствует обязательное поле `template/send.js`.
`Channel not found`	`phoneNumber` не является номером WhatsApp вашего рабочего пространства.
`Channel is not verified`	Номер WhatsApp подключён, но не верифицирован.
`Template message not found`	На номере нет одобренного шаблона с таким именем и языком. Проверьте написание и `languageCode`.
`Template message is not approved`	Шаблон существует, но не одобрен Meta.
`Variable missing: …`	`variables` не соответствует шаблону, например шаблону нужны два значения в тексте, а вы передали одно.
`Agent user not found`	Нет сотрудника с email из `agentEmailAddress`.
`Customer Channel not found`	Не удалось создать или найти идентификатор клиента в WhatsApp.

HTTP-коды состояния, которые вы можете увидеть:

401 Unauthorized: заголовок Authorization: Bearer <API_TOKEN> отсутствует либо токен неверный или просрочен. Используйте действительный токен из вашего аккаунта.
403 Forbidden: у токена нет доступа к этому рабочему пространству или приложению, например указан неверный tenant slug.
404 Not Found: адрес эндпоинта неверный. Проверьте полный путь /api/<slug>/custom-functions/template-app/api/....
500 Internal Server Error: непредвиденная проблема в MonoChat или у поставщика WhatsApp либо отказ со стороны WhatsApp (номера нет в WhatsApp, клиент заблокировал вас, ограничения по качеству или частоте). Повторите позже и обратитесь в поддержку MonoChat, если проблема сохраняется.

Скриншоты

Отправка одобренного шаблона WhatsApp из CRM, ERP или интернет-магазина одним вызовом API через MonoChat

Список одобренных шаблонов WhatsApp с их переменными

Отправка шаблона на новый номер автоматически создаёт клиента

Один шаблон, отправленный на нескольких языках

Шаблоны с заголовками-изображениями, видео, документами и PDF

Вопросы и ответы

Есть ли у WhatsApp Template API пользовательский интерфейс?

Нет. Это приложение только с API и тремя эндпоинтами: список шаблонов, отправка шаблона и получение учётных данных для загрузки медиазаголовков.

Что нужно, прежде чем начать пользоваться?

Номер WhatsApp Business, подключённый к MonoChat и верифицированный, шаблоны, одобренные Meta, и API-токен из раздела Профиль › API-токены.

Что происходит, когда клиент отвечает?

Диалог попадает во входящие MonoChat, как любой другой. Каждая отправка также возвращает прямую ссылку на диалог, а назначить его сотруднику можно по email.

Можно ли отправить на номер, которого ещё нет среди клиентов?

Да. Если номера телефона ещё нет среди клиентов, клиент создаётся с указанным вами именем.

Сколько стоят шаблонные сообщения?

Каждое сообщение тарифицируется как любое шаблонное сообщение, отправленное из MonoChat. Meta устанавливает цены на шаблоны по категории и стране получателя; для оценки рассылки воспользуйтесь калькулятором стоимости массовых рассылок в WhatsApp.

Обзор​

Основные возможности​

Установка и настройка​

Возможности​

Список шаблонов​

Отправка шаблона​

Назначение сотруднику​

Медиазаголовки​

Ссылка на диалог​

Понятные ошибки​

Перед началом работы​

Справочник API​

1. Список шаблонов​

2. Отправка шаблона​

3. Загрузка медиа для заголовка​

Пример: шаблон с изображением в заголовке​

Ошибки​

Скриншоты​

Вопросы и ответы​

Есть ли у WhatsApp Template API пользовательский интерфейс?​

Что нужно, прежде чем начать пользоваться?​

Что происходит, когда клиент отвечает?​

Можно ли отправить на номер, которого ещё нет среди клиентов?​

Сколько стоят шаблонные сообщения?​

См. также​