Clomni

Рецепт: уведомления и шаблоны WhatsApp с Вашего сайта

Обновлено: 11 ноября 2026 · 10 мин чтения

Этот рецепт помогает отправлять клиенту сообщения WhatsApp с Вашего сайта, из мобильного приложения или CRM: коды подтверждения, заказы, доставки, напоминания. Каждое сообщение записывается в диалог клиента в Clomni: когда клиент отвечает, оператор видит, что ему отправляли раньше.

Шаги

  1. 1

    Что Вы получите

    • Уведомление WhatsApp одним запросом из Вашей системы. Clomni сам находит или создаёт контакт и диалог.
    • Бесплатный текст, пока открыто 24-часовое окно, и одобренный шаблон, когда оно закрыто. Clomni сам проверяет окно.
    • Статус сообщения sent, delivered, read, failed, в том числе через вебхук.
    • Уведомления не забивают список «Открытые» у операторов: по умолчанию диалог остаётся закрытым и открывается, когда клиент отвечает.
  2. 2

    Два вида WhatsApp

    • WhatsApp Business API (Cloud): подключается через аккаунт Meta. Есть 24-часовое окно, вне окна уходит только одобренный шаблон, и Meta берёт за него плату. Endpoint /v1/whatsapp/* работают только с этим видом.
    • WhatsApp QR: WhatsApp на телефоне привязывается по QR-коду. Окна и шаблонов нет, но номер, который много отправляет, могут заблокировать. /v1/whatsapp/messages с номера QR не отправляет. В QR можно только отвечать в открытом диалоге (шаг 6).
  3. 3

    Нужные scope

    • messages:send.template (высокий риск): отправка шаблонов и их список.
    • messages:send (высокий риск): отправка текста. Если text отправляется вместе с fallback_template, нужны оба scope.
    • channels:read (низкий риск): список номеров WhatsApp и их channel_id.
    • messages:read (средний риск): проверка окна и статуса сообщения, вебхуки message.*.

    В форме review укажите примерный объём в день, кто создаёт сообщения (человек, система, AI) и как Вы получаете согласие на маркетинговые сообщения: Review: проверка scope и причины отказа.

    WhatsApp API, который работает с ключом API профиля (Начало работы с WhatsApp API: ключ API, account_id и channel_id), это отдельный продукт: там путь /v1/accounts/{account_id}/whatsapp/.... С токеном разработчика в пути нет ID workspace: /v1/whatsapp/.... Массовая отправка (bulk_messages) есть только в том API.

  4. 4

    1. Найдите канал

    curl "https://api.clomni.ai/v1/whatsapp/channels" \
  -H "Authorization: Bearer clomni_pat_xxx"

    У каждого номера в ответе есть channel_id и поле sendable. sendable: false это номер QR, этот API с него не отправляет.

  5. 5

    2. Выберите шаблон

    curl "https://api.clomni.ai/v1/whatsapp/templates?channel_id=5" \
  -H "Authorization: Bearer clomni_pat_xxx"

    Возвращаются только шаблоны, одобренные Meta (APPROVED). example_parameters это готовая заготовка параметров, которые ждёт шаблон: скопируйте её и подставьте свои данные. API шаблоны не создаёт: создайте шаблон в Meta, затем синхронизируйте шаблоны в настройках канала WhatsApp в панели. synced_at показывает, когда список получен в последний раз.

  6. 6

    3. Разберитесь с 24-часовым окном

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

    curl "https://api.clomni.ai/v1/whatsapp/messages/window?channel_id=5&phone_number=%2B994501234567" \
  -H "Authorization: Bearer clomni_pat_xxx"

    open: false и last_inbound_at: null означают, что этот номер Вам ни разу не писал: первое сообщение должно быть шаблоном.

  7. 7

    4. Отправьте

    Код подтверждения (шаблон):

    curl -X POST "https://api.clomni.ai/v1/whatsapp/messages" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"channel_id": 5, "phone_number": "+994501234567", "template": {"name": "verification_code", "language": "az", "parameters": {"body": {"1": "483920"}}}, "contact": {"name": "Leyla Hasanova", "identifier": "crm-10422"}, "source_reference": "otp-10422-1794120000"}'

    Уведомление о доставке (текст, если окно открыто, шаблон, если закрыто):

    curl -X POST "https://api.clomni.ai/v1/whatsapp/messages" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"channel_id": 5, "phone_number": "+994501234567", "text": "Посылка AZ-10422 передана курьеру.", "fallback_template": {"name": "cargo_status", "language": "az", "parameters": {"body": {"1": "AZ-10422", "2": "у курьера"}}}}'
    • Поле sent_as в ответе говорит, что ушло: session (текст) или template. Если окно закрыто и fallback_template нет, ничего не уходит и возвращается 422: платное сообщение не уйдёт без Вашего ведома.
    • source_reference это Ваш уникальный ключ. В течение 24 часов запрос с тем же ключом не создаёт новое сообщение, а возвращает первое: клиент не получит два кода, Meta не получит оплату дважды.
    • conversation_status по умолчанию resolved: диалог не попадает в список операторов. Передайте open, если оператор должен увидеть его сразу.
    • Номер должен быть в международном формате, от 8 до 15 цифр. Пробелы, дефисы и + удаляются. 0501234567 ошибочен, потому что в нём нет кода страны.
    • Параметры шаблона: для тела {"1": "..."} или имена, заданные в Meta, для заголовка media_url и media_type (image, video, document), для кнопок url или copy_code.
  8. 8

    5. Следите за статусом

    status: "sent" означает, что Meta приняла сообщение, а не что оно дошло. Чтобы прочитать последнее состояние:

    curl "https://api.clomni.ai/v1/whatsapp/messages/918234" \
  -H "Authorization: Bearer clomni_pat_xxx"

    Статусы: sent, delivered, read, failed (причина в поле external_error). Вместо запроса по каждому сообщению подпишитесь на вебхук message.updated. Чтобы получать ответ клиента, добавьте message.created. См. Вебхуки приложения и события: настройка, темы, проверка подписи.

  9. 9

    6. Ответ в открытом диалоге (Cloud и QR)

    Чтобы написать внутри диалога, используйте POST /v1/conversations/{conversation_id}/messages, где {conversation_id} это номер из панели. Этот путь работает и в Cloud, и в QR. В Cloud при закрытом окне передайте template_params, для этого нужен messages:send.template. Отправка здесь идёт в фоне: если сообщение не уйдёт, позже оно станет failed, причина будет в content_attributes.external_error. Для автоматических уведомлений путь из шага 4 проще.

  10. 10

    Частые ошибки

    • /v1/whatsapp/messages вызывается для номера QR, и приходит 422 «This API requires a WhatsApp Cloud API inbox». Проверяйте sendable.
    • Неверное имя шаблона или код языка, либо шаблон не синхронизирован в панели: 422 «No approved template named».
    • Число параметров не совпадает с шаблоном, и Meta отклоняет сообщение: статус становится failed. Сверяйтесь с example_parameters.
    • Отправка повторяется без source_reference, и клиент получает два кода.
    • sent читается как «доставлено». Доставку показывает delivered.
    • В QR приходит 463 или recipient_restricted, и сообщение автоматически повторяется. Не повторяйте: WhatsApp считает каждую попытку отдельно и продлевает ограничение.
    • Первое сообщение отправляется контакту со скрытым номером (identifier заканчивается на @lid). Клиент должен сначала написать сам или поделиться номером.
    • Маркетинг уходит без согласия. Жалобы снижают качество номера и его дневной лимит.

    Все endpoint сообщений: Scope и endpoint: диалоги и сообщения.

Документ

Платформа для разработчиков: руководство v1.0 · 41 стр. Открыть Скачать