Отправка сообщения WhatsApp через API: cURL, Node, Python, PHP

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F campaignName=order-updates \
  -F destinationNo=971500000000 \
  -F messageType=TEMPLATE \
  -F templateName=order_update \
  -F templateLanguage=en_US \
  -F bodyTemplateVariables=INV-400

// Node.js 18+ (встроенные fetch и FormData)
const form = new FormData();
form.append("batchId", "0");
form.append("campaignName", "order-updates");
form.append("destinationNo", "971500000000");
form.append("messageType", "TEMPLATE");
form.append("templateName", "order_update");
form.append("templateLanguage", "en_US");
form.append("bodyTemplateVariables", "INV-400");

const res = await fetch("https://api.broadnet.me/whatsapp/message/sendbulk", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BROADNET_TOKEN}` }, // fetch сам задаёт границу multipart
  body: form,
});
console.log(await res.json());

import os
import requests

fields = {
    "batchId": "0",
    "campaignName": "order-updates",
    "destinationNo": "971500000000",
    "messageType": "TEMPLATE",
    "templateName": "order_update",
    "templateLanguage": "en_US",
    "bodyTemplateVariables": "INV-400",
}
# Отправляйте каждое поле как часть multipart (files=), а не с url-кодированием (data=).
r = requests.post(
    "https://api.broadnet.me/whatsapp/message/sendbulk",
    headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"},
    files={k: (None, v) for k, v in fields.items()},
    timeout=30,
)
print(r.json())

<?php
$ch = curl_init("https://api.broadnet.me/whatsapp/message/sendbulk");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("BROADNET_TOKEN")],
    // Массив (а не строка) заставляет cURL отправить multipart/form-data.
    CURLOPT_POSTFIELDS => [
        "batchId" => "0",
        "campaignName" => "order-updates",
        "destinationNo" => "971500000000",
        "messageType" => "TEMPLATE",
        "templateName" => "order_update",
        "templateLanguage" => "en_US",
        "bodyTemplateVariables" => "INV-400",
    ],
]);
echo curl_exec($ch);
curl_close($ch);

{
  "totalFiles": 1,
  "totalSuccess": 1,
  "totalFailed": 0,
  "totalDuplicates": 0,
  "batchId": "2609091405000000001",
  "fileResults": [
    {
      "fileName": "direct",
      "totalRecords": 1,
      "successCount": 1,
      "failedRecipients": [],
      "duplicateRecipients": []
    }
  ],
  "message": "Messages queued for delivery"
}

Какие поля запроса важнее всего?

Какие поля обязательны, зависит от messageType. Вот самые распространённые.

Для планирования используются scheduled, scheduleTime и gmt, а delay ограничивает скорость доставки. Полный список — в справочнике WhatsApp API.

Как отправить шаблон с кнопкой или OTP?

Передайте значение кнопки в buttonsTemplateVariable. Для шаблона аутентификации с кнопкой копирования кода передайте код и в поле основного текста, и в поле кнопки.

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=971500000000 \
  -F messageType=TEMPLATE \
  -F templateName=login_code \
  -F templateLanguage=en_US \
  -F bodyTemplateVariables=482913 \
  -F buttonsTemplateVariable=482913

Здесь login_code — заглушка для вашего собственного одобренного шаблона аутентификации. Для нескольких кнопок buttonsTemplateVariable принимает JSON-массив. Генерируйте код на сервере, храните его в виде хеша со сроком действия и никогда не логируйте. Доставку в режимах one-tap, zero-tap и copy-code описывает наше руководство по OTP.

Как ответить внутри окна обслуживания клиента?

Используйте тип сессионного сообщения. Для простого текстового ответа нужны messageType=TEXT и content.

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=971500000000 \
  -F messageType=TEXT \
  -F campaignName=support \
  -F "content=Your order has shipped. Reply here if you need anything."

Для кнопок ответа отправьте messageType=INTERACTIVE и interactivePayload, соответствующий формату интерактивных сообщений Meta.

curl -X POST https://api.broadnet.me/whatsapp/message/sendbulk \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -F batchId=0 \
  -F destinationNo=971500000000 \
  -F messageType=INTERACTIVE \
  -F campaignName=support \
  -F 'interactivePayload={"type":"button","body":{"text":"Confirm your delivery slot?"},"action":{"buttons":[{"type":"reply","reply":{"id":"slot_ok","title":"Confirm"}},{"type":"reply","reply":{"id":"slot_change","title":"Change"}}]}}'

Чтобы отметить входящее сообщение прочитанным и при желании показать индикатор набора текста, вызовите POST /whatsapp/message/read с JSON:

curl -X POST https://api.broadnet.me/whatsapp/message/read \
  -H "Authorization: Bearer $BROADNET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "messageId": "wamid.HBgMOTcxNTAwMDAwMDAwFQIAEhgg", "typing": true }'

Рекомендации по оформлению см. в нашем руководстве по интерактивным сообщениям.

Как отслеживать доставку?

Статусы отправляются на вебхук, настроенный в вашем аккаунте, и их также можно читать по пакету. Каждый получатель проходит через SUBMITTED, SENT, DELIVERED и READ либо завершается как FAILED или REJECTED с указанием причины.

curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&status=FAILED&page=0&size=50" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

batch_Id обязателен; status, destination, search, page и size необязательны, а page нумеруется с нуля. Используйте опрос как страховку на случай пропущенных событий и создайте приёмник по описанию в нашем руководстве по вебхукам. Пакеты также можно приостанавливать, возобновлять и прерывать с помощью эндпоинтов пакетов из справочника.

Какие ошибки нужно обрабатывать?

Сначала читайте HTTP-статус, затем тело ошибки. API возвращает ошибки в JSON-теле из пяти полей, а специфические для WhatsApp сбои могут приходить от Meta.

Распространённые коды Meta объясняет наше руководство по кодам ошибок. Поскольку ключа идемпотентности нет, выполняйте шаги защиты от дублей из раздела ошибки и лимиты: сначала запишите pending-запись, сохраните возвращённый batchId, а после тайм-аута проверьте статус, прежде чем отправлять снова.

Пример: сервис уведомлений о заказах

«Souq Rafiq» (условный пример), розничный продавец из ОАЭ, отправляет шаблон order_update, когда заказ отправлен.

1. Сервис заказов записывает строку с ключом order-8842-shipped и статусом pending.
2. Он вызывает sendbulk с шаблоном и номером заказа в bodyTemplateVariables.
3. При ответе 200 он сохраняет batchId и отмечает строку как accepted.
4. Обработчик вебхука обновляет строку до DELIVERED или READ, либо FAILED с указанием причины.
5. Если клиент отвечает, инструмент поддержки использует сессионное сообщение TEXT внутри окна.
6. Ночное задание читает bulk-insights по вчерашним пакетам и сверяет недостающие статусы.

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

• Отправка JSON. Эндпоинт отправки WhatsApp принимает multipart; Content-Type: application/json не сработает.
• data= в Python вместо files=, из-за чего форма url-кодируется.
• Свободный текст вне окна, который завершается ошибкой. Используйте шаблон.
• Неверный код языка, например en вместо en_US у шаблона.
• Принятие 200 за доставку. Он означает «в очереди».
• Слепые повторы после тайм-аута, из-за которых клиенту можно написать дважды.
• Токен в клиентском коде. Вызывайте API только из бэкенда.
• Ограничения: детали payload зависят от шаблона. Структуру переменных для вашей первой персонализированной рассылки подтвердите у нашей команды.

Как помогает OmniChannels.ai

BroadNet — официальный Meta Business Solution Provider, а подключение к WhatsApp Business API проходит через Meta Embedded Signup; наша команда вместе с вами готовит регистрацию, а одобрения остаются за Meta. REST API документирован спецификацией OpenAPI 3.1 и TypeScript SDK @broadnet/cpaas-sdk, а статусы доставки приводятся к единому виду во всех каналах. Начните с документации WhatsApp API или быстрого старта.