Пропускная способность и лимиты скорости WhatsApp Cloud API

Какие коды ошибок появляются при достижении лимита?

Сопоставьте код с лимитом, затем выберите реакцию.

Коды 131048 и 131049 связаны с качеством и вовлечённостью, а не со скоростью, поэтому более частые повторы не помогут. См. устранение ошибок WhatsApp API.

В API OmniChannels.ai отказ вышестоящей стороны приходит как HTTP 502 с кодом ошибки Meta и текстом в message, а собственное ограничение скорости возвращает 429 с заголовком Retry-After. Полную таблицу и лимиты по умолчанию см. в разделе ошибки и лимиты.

Как ставить в очередь и повторять запросы?

Поставьте очередь между приложением и API, ограничьте скорость ниже предела и повторяйте только то, что может получиться позже.

1. Ставьте каждую отправку в очередь. Приложение пишет сообщения в очередь, а пул воркеров её разбирает. Никогда не перебирайте список клиентов в одном обработчике запроса.
2. Ограничивайте скорость токен-бакетом, заданным ниже вашей пропускной способности, оставляя запас для ответов и другого трафика, делящего тот же предел.
3. Сначала записывайте каждую попытку. Заведите строку на каждое сообщение с ключом вашего собственного ID операции, сохраните возвращённый ID сообщения и пропускайте всё уже принятое.
4. Повторяйте временные сбои. Ограничение скорости и временные ошибки сервера повторяются; ошибки валидации (400), аутентификации и шаблонов — нет.
5. Отсрочка с джиттером. После каждой попытки ждите дольше, добавляйте случайность, чтобы воркеры не повторяли запросы одновременно, и ограничивайте и задержку, и число попыток.
6. Учитывайте Retry-After, если он есть в ответе.
7. После тайм-аута проверяйте, прежде чем отправлять снова. Потерянный ответ не значит потерянное сообщение; сначала посмотрите события статуса.

const RETRYABLE = new Set([429, 500, 502, 503, 504]);

async function sendWithBackoff(send, { maxAttempts = 5, baseMs = 500, capMs = 30000 } = {}) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await send();
    if (res.ok) return res;
    if (!RETRYABLE.has(res.status) || attempt === maxAttempts) throw new Error(`failed: ${res.status}`);
    const wait = Math.random() * Math.min(capMs, baseMs * 2 ** (attempt - 1)); // full jitter
    await new Promise((r) => setTimeout(r, wait));
  }
}

На странице Meta о пропускной способности нет правила отсрочки для ошибки 130429, так что это общепринятая инженерная практика. Если 502 несёт код ограничения скорости Meta, считайте его допускающим повтор; для любого другого кода вышестоящей стороны сначала прочитайте сообщение. На странице ошибки и лимиты есть полная таблица повторов и защита от дублирующих отправок.

Как спланировать большую рассылку?

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

1. Подсчитайте уникальных получателей и сравните с вашим лимитом сообщений. Если список больше вашего уровня, начните с плана безопасного наращивания.
2. Оцените длительность. Число сообщений, делённое на пропускную способность, даёт секунды. В арифметике это так: 100 000 сообщений при 80 в секунду занимают 1 250 секунд, около 21 минуты, если больше ничто не использует предел.
3. Зарезервируйте ёмкость. Предел учитывает и входящие сообщения, поэтому оставьте запас на ответы клиентов во время рассылки.
4. Рассчитайте вебхук-сервер. Meta считает, что вебхук-серверы должны справляться с утроенным объёмом вашего исходящего трафика плюс ожидаемый входящий, при медианной задержке не выше 250 мс и менее 1% запросов дольше 1 секунды. См. руководство по вебхукам.
5. Сначала проверьте здоровье и качество шаблона и отправляйте партиями, чтобы можно было остановиться, если растёт число сбоев или блокировок. См. массовая рассылка в WhatsApp без блокировки.
6. Используйте media ID, а не ссылки, когда отправляете файлы в больших объёмах, как советует Meta. См. типы медиа и лимиты.

В OmniChannels.ai массовые конечные точки принимают множество получателей в одном запросе, а поле delay позволяет замедлить доставку. Пиковые планы согласуйте с нашей командой заранее.

Пример: распродажа в Дубае

«Marina Gadgets» (вымышленная компания) планирует шаблон для молниеносной распродажи для 60 000 клиентов, давших согласие.

1. Их лимит это позволяет, так что ограничение не в объёме, а в скорости. При 80 mps 60 000 сообщений требуют 750 секунд.
2. Они отправляют шесть партий по 10 000, с ограничителем скорости на 60 mps, что оставляет запас для ответов.
3. В одной партии появляется несколько ошибок 131056 для клиентов, которые в ту же минуту получили ещё и обновление по заказу. Эти отправки откладываются на несколько минут.
4. Воркер повторяет запросы, отклонённые из-за ограничения скорости, с отсрочкой и джиттером, и сообщение после получения ID больше не повторяется.
5. Вебхук-эндпоинт сохраняет события и возвращает 200, затем воркер обновляет статусы.
6. После каждой партии они проверяют сбои и качество шаблона, прежде чем продолжить.

Какие типичные ошибки?

• Путаница между лимитами. Пропускная способность, парный лимит, лимиты Graph API и лимиты сообщений — это разные проблемы.
• Немедленные повторы, из-за которых номер остаётся на пределе и проблема затягивается.
• Отправка на пределе, когда ответы и статусы конкурируют с кампанией.
• Повторная отправка после тайм-аута без проверки статуса, из-за чего сообщения дублируются.
• Опрос конечных точек Graph API в цикле и упор в почасовой лимит.
• Недостаточно мощные вебхук-серверы, которые отстают и вызывают повторы.
• Лимиты меняются. В этом руководстве значения Meta на момент написания.

Чем помогает OmniChannels.ai

BroadNet — официальный бизнес-провайдер решений Meta (Business Solution Provider), а OmniChannels.ai отправляет WhatsApp через один API с массовыми конечными точками, полем delay для ограничения скорости, планированием и статусами доставки в едином нормализованном формате вебхука. У реселлеров отдельные вебхуки и баланс для каждого субаккаунта. Пики планируйте вместе с нашей командой и читайте документацию WhatsApp API, ошибки и лимиты и страницу кампаний.