WhatsApp Business API для отправки в рамках сессии — pdf-файл счёта

Обзор сценария

Этот сценарий отправляет PDF-документ с помощью sendFile в течение 24-часового окна обслуживания клиентов WhatsApp. Используйте его, когда необходимо прикрепить инвойс, не начиная новый разговор по шаблону.

Пример шаблона

Счёт на оплату за тикет {{1}}

• {{1}}
  номер тикета поддержки, указанный в подписи PDF-файла

Когда использовать

Используйте этот сценарий, когда выставление счетов должно отправить счёт в формате PDF, пока поддержка переписывается в WhatsApp — клиент уже написал первым, и 24-часовое окно сессии активно. Это подходит для продолжения работы с выставлением счетов в тикетах службы поддержки, где прикрепление документов через одобренные шаблоны было бы медленным или ненужным для команд, интегрирующих 1MSG с бекэндами для тикетов и выставления счетов.

Как это работает

1. Триггер

   Служба поддержки отмечает тикет готовым для выставления счёта, пока сеанс ещё открыт.

   event · triggered

2. Фиксация события

   Ваш бэкенд определяет номер тикета и местоположение PDF-файла счёта.

   phone: "+…"

3. Собрать и отправить

   sendFile отправляет файл формата application/pdf с именем invoice.pdf и подписью, ссылающейся на тикет.

   POST /send_file

4. Доставлено

   Клиент получает PDF в том же чате WhatsApp.

   delivered

Техническая реализация

Предварительные условия

1. Ключ API 1MSG · Как получить API-ключ
2. Аккаунт WhatsApp Business · Как подключить WABA
3. Открыть 24-часовое окно сеанса · Как работает 24-часовое окно
4. Согласие клиента на получение сообщений · Как управлять согласием клиентов
5. Конечная точка вебхука · Как настроить вебхуки

Примеры кода

#!/usr/bin/env bash
set -euo pipefail

# === Configuration (replace "___" placeholders) ===
API_BASE_URL="https://api.1msg.io"        # production 1MSG API base URL
CHANNEL_ID="___"                           # channel ID from 1MSG dashboard
API_TOKEN="___"                            # channel JWT token (Bearer)



# === Test data ===
TEST_PHONE="___"                 # client phone in international format
MEDIA_URL="___"                         # local file path or HTTPS URL for sendFile body

PHONE_NORM="$(printf '%s' "$TEST_PHONE" | tr -cd '0-9')"
URL="${API_BASE_URL%/}/${CHANNEL_ID}/sendFile"

read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "body": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
  "filename": "invoice.pdf"
}
JSON

RESPONSE="$(curl -s -w '\n%{http_code}' -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "$PAYLOAD")"

HTTP_CODE="$(printf '%s' "$RESPONSE" | tail -n1)"
BODY="$(printf '%s' "$RESPONSE" | sed '$d')"

case "$BODY" in
  *'"sent":true'*) ok=1 ;;
  *) ok=0 ;;
esac

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ] && [ "$ok" -eq 1 ]; then
  echo "Message sent to client."
  echo "API response: $BODY"
else
  echo "Send failed. HTTP status: $HTTP_CODE" >&2
  echo "$BODY" >&2
  exit 1
fi

Статус ответа и доставки

HTTP 2xx и JSON "sent": true означают, что 1MSG принял сообщение для отправки — это не значит, что оно уже доставлено на телефон клиента. Сохраняйте поле id (выглядит как wamid.…), чтобы сопоставлять с уведомлениями о доставке.

{
  "sent": true,
  "id": "wamid.HBgLMzgwNjM5...",
  "message": "Message accepted for delivery"
}

Доставка приходит позже, в виде отдельного обратного вызова. Зарегистрируйте вебхук (POST …/webhook), и 1MSG отправит обновления статуса на ваш HTTPS-эндпоинт в базовом hooks[] payload.

{
  "hooks": [
    {
      "id": "gBGGeSaGViBfAgnlzOSHEwK9O6F",
      "type": "message",
      "status": "sent",
      "timestamp": "1654864094",
      "recipient_id": "556123122026"
    }
  ]
}

Если вы предпочитаете не использовать обратные вызовы, вместо этого опрашивайте GET {base}/{channel}/hookInfo?messageId=<id>. На практике доставка часто завершается в течение нескольких секунд, но это не гарантировано контрактом API, поэтому никогда не блокируйте поток в ожидании доставки.

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

ЧАСТО ЗАДАВАЕМЫЕ ВОПРОСЫ