1MSG
Reference

WhatsApp Business API

1MSG.IO — официальный WhatsApp Business API: отправка сообщений, приём webhooks и управление каналом.

Авторизация. В каждом запросе нужен токен канала со страницы канала в кабинете. Не передавайте его третьим лицам.

Токен можно передать одним из способов (API ищет в body, затем в query, затем в заголовке):

  • поле token в JSON-теле (POST)
  • query-строка ?token=
  • заголовок Authorization: Bearer <token> — предпочтительно в production (не попадает в access-логи)

URL. https://api.1msg.io/{channelId}/<method>

Окно сессии. Все методы send* кроме /sendTemplate (и шаблонов order-details) работают только при открытом 24-часовом окне обслуживания с получателем.

Быстрый старт: https://help.1msg.io/platform-1msg/getting-start/quick-start

Канал

Управляйте своим каналом WhatsApp Business API.

Webhooks

Настройка URL для входящих событий WhatsApp и форматы callback-payload (сообщения, ACK, группы, coexistence echo, звонки).

Обмен сообщениями

Как отправлять и принимать сообщения с помощью WhatsApp Business API

Users

Блокировка, разблокировка и список заблокированных пользователей WhatsApp

Группы

Управление группами WhatsApp

Шаблоны

Шаблон сообщения через WhatsApp Business API

Продукты и Каталоги

Как создавать и отправлять сообщения с одним и несколькими продуктами.

Вы можете отправлять карточки товаров через Карусель следующими способами:

Шаблонные сообщения (Template messages): не требуют наличия 24-часового окна обслуживания клиента между вами и получателем для отправки сообщения. Используйте метод sendTemplate.

Произвольные сообщения (Free-form messages): могут быть отправлены пользователю только при наличии открытого окна обслуживания клиента между вами и пользователем. Используйте метод sendCarousel.

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

В шаблоне /sendCarousel для отправки Карусели Каталога могут быть либо 1 кнопка URL либо одна или несколько кнопок быстрого ответа.

Каталог

Настройки каталога и корзины (GET/POST /commerce).

Поля ответа GET: id, is_cart_enabled, is_catalog_visible.

Тело POST: { "params": { "is_cart_enabled": boolean, "is_catalog_visible": boolean } }.

Медиа

Используйте медиа-узел для загрузки, извлечения или удаления медиафайлов

Аналитика шаблонов

Ограничения

  • Аналитика кликов по кнопкам доступна только для шаблонов категорий MARKETING и UTILITY.
  • Не поддерживаются аккаунты WhatsApp Business, которыми владеют бизнес-аккаунты Meta или которые передаются бизнес-аккаунтам Meta в пределах Европейского союза (ЕС), Великобритании и Японии, а также аккаунты, номер телефона компании которых содержит код Великобритании, Японии или одной из стран ЕС, либо одного из регионов Великобритании, Японии и ЕС.
  • Данные о событиях чтения и нажатия для сообщений с шаблонами WhatsApp доступны только в течение 7 дней с даты отправки сообщения. По истечении этого 7-дневного периода соответствующие счетчики прочитанных сообщений и кликов обнуляются, и дальнейшие обновления для этих сообщений не фиксируются.

WhatsApp Flows

Управление WhatsApp Flow: создание, превью, публикация, депрекация.

Flow, который запрашивает экраны у вашего сервера, требует две вещи, которые 1msg не хостит: подписанный публичный ключ номера и endpointUri на вашем HTTPS-сервере. Запросы data channel не приходят в webhook канала.

Публичный ключ

Сгенерируйте пару RSA 2048. Храните private.pem у себя. В 1msg его не отправляйте.

openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem

Содержимое public.pem загрузите методом POST /whatsapp_business_encryption. Затем вызовите GET /whatsapp_business_encryption:

  • VALID — подпись совпадает с сохранённым ключом. Это не доказывает, что ваш endpoint работает.
  • MISMATCH — сохранённый ключ и подпись не совпадают. Загрузите публичный ключ ещё раз.

На номер действует один ключ. Новая загрузка заменяет предыдущий.

endpointUri

endpointUri задаётся при создании Flow или методом PATCH /flows/{flowId}/metadata. Это ваш URL, а не метод 1msg.

WhatsApp отправляет POST с полями encrypted_flow_data, encrypted_aes_key и initial_vector. Расшифруйте encrypted_aes_key ключом private.pem (RSA-OAEP, SHA-256), затем тело через AES-128-GCM. Ответ — строка base64 с заголовком Content-Type: text/plain, зашифрованная тем же AES-ключом и IV с инвертированным каждым байтом. Если расшифровать не удалось, ответьте HTTP 421: приложение WhatsApp заново запросит публичный ключ.

Тот же URL получает служебный ping (расшифрованный ответ {"data":{"status":"active"}}). Эти запросы не приходят в webhook канала. Когда форма заполнена, итог приходит на webhookUrl канала: messages[].interactive.type = nfm_reply.

Channel

Calling

WhatsApp Calling API (beta) — VoIP signaling proxy.

1msg does not host media, store call history, or store recordings. You need your own WebRTC or SIP stack.

Prerequisites

  • Meta Calling enabled on the number (Cloud API; not COEX)
  • Paid channel — trial / subscriptionBlocked → 403 plain text
  • Webhook URL configured (POST /webhook) for calls events

Inbound (user → business)

  1. Webhook type=calls, event=connect — take call_id + SDP offer
  2. Optional: POST /initiateCall action=pre_accept + WebRTC answer SDP
  3. action=accept + WebRTC answer SDP, or action=reject
  4. Later event=terminate, or action=terminate to hang up

Answer within ~30–60s or Meta ends as unanswered.

Critical: accept / pre_accept need a WebRTC-generated SDP answer. Do not echo Meta's offer. Postman/curl alone cannot establish real media.

Outbound (business → user)

  1. Send Call Permission Request (CPR) — template or interactive
  2. Wait for permission reply on the messages webhook (call_permission_reply)
  3. POST /initiateCall action=connect + business SDP offer
  4. Apply Meta's SDP answer from the calls connect webhook

Meta limits (summary): permission ~7 days; up to 5 calls / 24h / user; max 2 CPR / 7 days; auto-revoke after 4 unanswered.

Webhooks (type=calls)

Passthrough of Meta field=calls plus type, instanceId. Events: connect (offer or answer SDP), statuses (RINGING / ACCEPTED / REJECTED), terminate. CPR replies use the messages path, not type=calls.

See operations below for request bodies and examples.

RU: accept/pre_accept требуют WebRTC SDP answer; Postman alone не поднимает медиа.

Templates

Messaging

Profile

Media

24-hour conversation window

When you can send any message to a customer on WhatsApp and when only a pre-approved template will do.

Получение информации о профиле GET

Следующая страница

WhatsApp Business API | 1MSG