ВойтиНачать бесплатный пробный период
easyCoexistence Официальные API

Как получать сообщения клиентов WhatsApp и комментарии соцсетей по вебхуку

Каждое подключение получает собственный вебхук для сообщений клиентов WhatsApp или комментариев из соцсетей через Partner API easyCoexistence. Сообщения WhatsApp поступают от Meta напрямую на этот URL и подписаны секретом приложения Tech Provider, а не секретом, которым владеете вы, поэтому аутентифицирует их длинный случайный секрет в пути URL. Комментарии и DM из Instagram и Facebook, а также комментарии TikTok пересылаются по мере поступления и подписываются для каждого аккаунта заголовком X-EC-Signature.

200 characters

Максимальная длина, которую Meta допускает для альтернативного URL обратного вызова, по которому сообщения номера поступают на ваш эндпоинт.

7 days

Срок, в течение которого Meta повторно отправляет вебхук WhatsApp, который ваш эндпоинт не принял, с всё более редкими интервалами; из-за этого возможны дубликаты.

AS32934

Сеть Meta; whois-запросы маршрутов к ней показывают адреса, с которых приходят вебхуки WhatsApp, и Meta периодически их меняет.

3 MB

Максимальный размер полезной нагрузки вебхука WhatsApp по данным Meta.

5 minutes

Возраст, после которого подписанная метка времени пересланного события должна отклоняться, при этом HMAC сравнивается за постоянное время.

Как каждое подключение получает собственный адрес назначения?

Через один вызов на каждый ресурс. Номер WhatsApp принимает PUT /connections/{id}/webhook с полями url и verify_token или ту же пару как webhook_url и webhook_verify_token в сессии подключения, так что номер направляется к вам с первой минуты. Аккаунт соцсети принимает PUT /channels/{id}/webhook после подключения. Значение null в url на любом из них отключает доставку. Два пути различаются тем, кто доставляет и как вы проверяете подлинность:

WhatsApp numberInstagram, Facebook, TikTok
Set withwebhook_url on the session, or PUT /connections/{id}/webhookPUT /channels/{id}/webhook, after it connects
Delivered byMeta, straight to your URLeasyCoexistence, forwarding each event as it arrives
BodyMeta's webhook, unchangedplatform, account_id, external_id and the network's entry
AuthenticateA long random secret in the URL pathX-EC-Signature, keyed with the account's secret
RetriesMeta's own, for up to 7 daysNone: one attempt
Copy keptNoneNone

Как направить сообщения номера на ваш эндпоинт?

Укажите HTTPS URL, в пути которого есть длинный случайный секрет, и токен проверки: webhook_verify_token в сессии подключения, от 8 до 200 символов, или verify_token в PUT. Meta сразу проверяет URL GET-запросом с hub.mode=subscribe, hub.verify_token и hub.challenge, и ваш эндпоинт должен вернуть значение hub.challenge, если токен совпадает. Если это рукопожатие не проходит, PUT возвращает 502 meta_rejected с собственным сообщением Meta; в сессии подключения номер всё равно подключается, а last_error сессии объясняет, почему URL не применён.

Node.js: Meta's handshake and the path secret
import express from "express";
import { timingSafeEqual } from "node:crypto";

const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();

function same(a, b) {
  const x = Buffer.from(String(a)), y = Buffer.from(String(b));
  return x.length === y.length && timingSafeEqual(x, y);
}

// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
  if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
  if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
    return res.sendStatus(403);
  }
  res.send(req.query["hub.challenge"]);
});

// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
  if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
  res.sendStatus(200); // answer first: Meta retries for up to 7 days
  enqueue(req.body); // deduplicate on each message id before acting
});

Почему нельзя проверить подпись Meta и чем её заменить?

Meta подписывает каждую доставку заголовком X-Hub-Signature-256, HMAC-SHA256 от полезной нагрузки с ключом App Secret принимающего приложения. Для номеров ваших клиентов этим приложением является приложение Tech Provider easyCoexistence, а его секрет не передаётся, поэтому заголовок невозможно проверить на вашей стороне. Вместо него учётными данными служит длинный случайный секрет в пути URL: сравните его за постоянное время и отклоняйте всё остальное. Вторым уровнем защиты внесите в allowlist маршруты, принадлежащие Meta (AS32934), и обновляйте этот список, поскольку Meta периодически меняет IP-адреса.

Какие вебхуки WhatsApp доходят до вашего URL?

Поля, которые альтернативный URL обратного вызова Meta может передавать: messages для того, что присылают клиенты, и статусы того, что отправили вы; smb_message_echoes для того, что бизнес отправляет из приложения WhatsApp Business; а также история и smb_app_state_sync разового импорта. Meta никогда не отправляет вебхуки шаблонов или аккаунта, такие как account_update, на переопределённый адрес. Они поступают на обратный вызов easyCoexistence, поэтому проверку шаблонов читают опросом, а отклонение приходит к вам как событие статуса.

  • Адрес назначения задаётся в аккаунте WhatsApp Business, поэтому два номера одного аккаунта используют его совместно: маршрутизируйте по value.metadata.phone_number_id.
  • Медиафайлы приходят в виде ID; загрузите файл из Meta с токеном клиента из запроса учётных данных.
  • Полезная нагрузка может достигать 3 МБ, поэтому поднимите любой лимит размера тела запроса, установленный ниже этого значения.

Как выглядит пересланное событие соцсети?

POST с Content-Type application/json и заголовком X-EC-Signature, содержащий четыре ключа: platform; account_id, ID канала, который использует Partner API; external_id, ID аккаунта в сети; и entry. Для Instagram и Facebook entry это запись вебхука Meta без изменений, с changes для комментариев и упоминаний и messaging для DM. Для TikTok там лежит событие comment.update с разобранным содержимым и comment_id, video_id и parent_comment_id в виде строк, поэтому 64-битные ID не округляются.

  • Аккаунты Instagram подписаны на comments, messages и mentions; страницы Facebook на feed, messages и mention; TikTok отправляет comment.update.
  • easyCoexistence не получает событий комментариев от YouTube или LinkedIn: их PUT отвечает 400 not_supported, а комментарии читаются через API каждой сети с учётными данными.
  • Пересылки не содержат заголовков X-EC-Event или X-EC-Delivery, поэтому дедуплицируйте по собственным ID сети, например по ID комментария или mid сообщения.
A forwarded Instagram comment
{
  "platform": "instagram",
  "account_id": "<CHANNEL_ID>",
  "external_id": "<INSTAGRAM_ACCOUNT_ID>",
  "entry": {
    "id": "<INSTAGRAM_ACCOUNT_ID>",
    "time": 1793440800,
    "changes": [
      {
        "field": "comments",
        "value": {
          "id": "<COMMENT_ID>",
          "from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
          "text": "<COMMENT_TEXT>",
          "media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
        }
      }
    ]
  }
}

Как проверить X-EC-Signature пошагово?

Используйте signing_secret, который вернул PUT /channels/{id}/webhook; он показывается только один раз и уникален для этого аккаунта. Заголовок имеет вид t=<unix>,v1=<hex>. Затем для каждой доставки:

  • Прочитайте сырое тело запроса как байты, до любого разбора JSON.
  • Разделите заголовок по запятым на t, Unix-время в секундах, и v1, hex-дайджест.
  • Отклоните доставку, если t отличается от ваших часов больше чем на 5 минут.
  • Вычислите HMAC-SHA256 от t, точки и сырого тела, с ключом секрета этого аккаунта, в виде hex.
  • Сравните с v1 за постоянное время, затем ответьте 2xx и поставьте работу в очередь.
Node.js: verifying a forwarded event
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database

app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
  const sig = Object.fromEntries(
    (req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
  );
  if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
    return res.sendStatus(401); // missing or stale timestamp
  }
  let event;
  try {
    event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
  } catch {
    return res.sendStatus(400);
  }
  const secret = secrets.get(event.account_id);
  if (!secret || !sig.v1) return res.sendStatus(401);
  const expected = createHmac("sha256", secret)
    .update(sig.t + ".")
    .update(req.body) // the raw bytes, exactly as they arrived
    .digest("hex");
  if (expected.length !== sig.v1.length ||
      !timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
    return res.sendStatus(401);
  }
  res.sendStatus(204); // one attempt and no retries: acknowledge, then work
  enqueue(event);
});

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

Ничего до вас не доходит, и ничего не ждёт отправки позже. Номер без webhook_url уходит на обратный вызов easyCoexistence, где его сообщения отбрасываются без сохранения, и для него не запускается импорт истории чатов, который запрашивается только при наличии адреса назначения. Аккаунт соцсети без адреса не пересылается: его события всё равно попадают в приложение easyCoexistence, но для вас ни одно не сохраняется. Задайте каждый адрес назначения до того, как понадобится трафик.

Что происходит с адресом назначения, когда подключение разрывается или удаляется?

Номер сохраняет свой адрес назначения. Когда разорвавшийся номер подключается снова, easyCoexistence заново задаёт ваш URL в Meta, то же происходит, когда приостановленный номер возвращается. Удаление аккаунта соцсети очищает его адрес назначения и секрет, поэтому после повторного подключения вызовите PUT /channels/{id}/webhook снова и сохраните новый секрет. Этот PUT выпускает новый секрет всякий раз, когда вызывается с URL, и старый перестаёт подписывать сразу.

Как настроить

  1. Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
  2. Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
  3. Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
  4. Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.

Распространённые ошибки

  • Проверка X-Hub-Signature-256 в доставках WhatsApp ваших клиентов. Meta вычисляет его секретом приложения easyCoexistence, который не передаётся, поэтому проверка не может пройти; аутентифицируйте секретом в пути URL.
  • Проверка X-EC-Signature по разобранному JSON. HMAC покрывает сырое тело побайтно, а повторная сериализация меняет байты, поэтому проверяйте до разбора.
  • Один секрет для всех каналов. Каждый аккаунт соцсети подписывает своим секретом, а события статусов другим, поэтому ищите секрет по account_id.
  • Долгая работа до ответа на пересланное событие. Оно отправляется один раз, ждёт 8 секунд вашего ответа и никогда не повторяется, поэтому сначала ответьте 2xx, а обрабатывайте потом.
Настройка с EasyCoexistence

easyCoexistence напрямую направляет сообщения каждого номера клиента от Meta на ваш сервер, а комментарии и DM Instagram и Facebook, а также комментарии TikTok пересылает на ваш эндпоинт по мере поступления, подписанными для каждого аккаунта. Копии не хранятся, каждое подключение отслеживается круглосуточно. От US$ 9 за подключение в месяц, до US$ 0,75 по мере добавления подключений, первые 3 дня бесплатно.

Часто задаваемые вопросы

Могу ли я проверить подпись Meta в сообщениях WhatsApp моих клиентов?

Нет. Meta подписывает их секретом приложения Tech Provider easyCoexistence, который не передаётся. Аутентифицируйте длинным случайным секретом в пути вашего URL и, при желании, диапазонами IP-адресов Meta.

Пересылают ли подключения YouTube и LinkedIn события комментариев?

Нет. easyCoexistence не получает событий комментариев от них, поэтому PUT /channels/{id}/webhook отвечает 400 not_supported. Читайте их комментарии через API каждой сети с учётными данными канала.

Повторяются ли пересланные события соцсетей, если мой сервер недоступен?

Нет. Каждое отправляется один раз, копия не сохраняется. Доставки WhatsApp отличаются: Meta сама повторяет их до 7 дней.

Проходят ли сообщения через easyCoexistence?

В WhatsApp нет: Meta доставляет сообщения номера напрямую на заданный вами вебхук. Комментарии и DM из соцсетей пересылаются на ваш эндпоинт по мере поступления, подписанные для каждого аккаунта, без сохранения копии.

Читайте дальше

Как узнать, что подключение клиента к WhatsApp или соцсети отключилосьСобытия connection.* и channel.*: тело запроса, причины вроде PRIMARY_INACTIVITY, X-EC-Signature, повторы около 33 часов и дедупликация по id.Как импортировать историю чатов и контакты приложения WhatsApp Business через APIИмпорт контактов и чатов за 180 дней из приложения WhatsApp Business через Coexistence: вебхуки history, chunk_order, прогресс и код 2593109.Как получить API-токены клиентов для WhatsApp, Instagram и TikTokПоля учётных данных для номера WhatsApp и аккаунтов в соцсетях, а также как работают обновление токенов и token_ready.События вебхука Instagram: комментарии, упоминания и личные сообщения (DM)Как комментарии, упоминания и DM из Instagram доходят до вашего эндпоинта: что содержит каждое событие, как подписываются доставки и что проверить.Вебхук Messenger для Facebook Page: сообщения и упоминанияПоля вебхука Facebook Page для сообщений Messenger и упоминаний: формат тела запроса, ID отправителей, вложения и доставка событий на ваш эндпоинт.События вебхука комментариев TikTokКак вебхук comment.update от TikTok сообщает о комментариях и ответах, что несёт каждое событие и как оно приходит на ваш эндпоинт с подписью.

Подключите первый канал за две минуты.

Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.

  • 3 дня бесплатно
  • Отмена в любой момент
  • Только официальные API
  • Мониторинг 24/7

Проверено по состоянию на