💬 Командный WhatsApp-Инбокс на новой ПлатформеЕщё
1msg official logo

WhatsApp Business API для уведомления об отправке счета

Сценарий отправляет клиенту персонализированный шаблон WhatsApp, когда выставляется новый счет.

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

Сценарий отправляет клиенту персонализированный шаблон WhatsApp при выставлении нового счета. Сообщение включает имя клиента, номер счета, сумму к оплате и срок оплаты. Статическая кнопка URL открывает страницу счета или оплаты.

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

Здравствуйте, {{1}}! Выписан счет №{{2}} на сумму {{3}}. Оплатить до: {{4}}.

Оплатить счет
  • {{1}}
    имя клиента
  • {{2}}
    номер счета
  • {{3}}
    сумма к оплате
  • {{4}}
    срок оплаты
  • “Оплатить счет”
    кнопка — исправлена в шаблоне Meta
WhatsApp Business API for invoice send notification

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

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

Меньше потерянных счетов
Четыре переменные в теле подставляют в чат WhatsApp клиента его имя, номер счета, сумму задолженности и дату оплаты, чтобы сводка оставалась на виду, а не была закопана в отфильтрованном вложении электронной почты.
Оплата в одно касание из сообщения
Кнопка с постоянным URL открывает страницу счета или оплаты, указанную в шаблоне Meta, чтобы клиент мог просмотреть или оплатить без поиска ссылки в электронной почте — через API передаются только четыре переменные в теле.
Нет ручной отправки счетов
Биллинг создает событие нового счета, система подставляет телефон клиента и поля счета, и шаблон отправляется автоматически — никто не вводит вручную суммы или сроки оплаты для каждого клиента.
Статус доставки для последующей обработки счетов
Результат доставки фиксируется после отправки, поэтому биллинговые или CRM-системы могут отслеживать, дошел ли счет до клиента, и обрабатывать ошибки в соответствии с правилами платформы.

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

  1. Триггер

    Биллинг выставляет новый счет и вызывает событие.

    event · triggered

  2. Фиксировать событие

    Система распознает номер телефона клиента и поля счета.

    phone: "+…"

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

    Персонализированное сообщение по шаблону создается с четырьмя переменными в теле и кнопкой со статическим URL.

    POST /sendTemplate

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

    Клиент получает краткое резюме счета WhatsApp и может оплатить по кнопке.

    delivered

  5. Статус отслежен

    Результат доставки записывается; ошибки обрабатываются согласно правилам платформы.

    status: "read"

WhatsApp Business API for invoice send notification

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

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

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

Примеры кода

#!/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)

TEMPLATE_NAME="___"                        # approved template name
TEMPLATE_NAMESPACE="___"                   # template namespace (required — send fails without it)
TEMPLATE_LANGUAGE="___"                    # template language code, e.g. "en"



# === Test data ===
TEST_PHONE="___"                 # client phone in international format
TEST_CUSTOMERNAME="___"         # {{1}} customer name
TEST_TICKETNUMBER="___"         # {{2}} ticket number
TEST_PAYMENTAMOUNT="___"         # {{3}} payment amount
TEST_DUEDATE="___"         # {{4}} due date

PHONE_NORM="$(printf '%s' "$TEST_PHONE" | tr -cd '0-9')"

for pair in "CHANNEL_ID=$CHANNEL_ID" "API_TOKEN=$API_TOKEN" \
            "TEMPLATE_NAME=$TEMPLATE_NAME" "TEMPLATE_NAMESPACE=$TEMPLATE_NAMESPACE" \
            "TEMPLATE_LANGUAGE=$TEMPLATE_LANGUAGE" "TEST_PHONE=$TEST_PHONE" \
            "TEST_CUSTOMERNAME=$TEST_CUSTOMERNAME" \
            "TEST_TICKETNUMBER=$TEST_TICKETNUMBER" \
            "TEST_PAYMENTAMOUNT=$TEST_PAYMENTAMOUNT" \
            "TEST_DUEDATE=$TEST_DUEDATE"; do
    val="${pair#*=}"
    if [ -z "$val" ] || [ "$val" = "___" ]; then
        echo "Missing configuration value: ${pair%%=*}" >&2
        exit 1
    fi
done

if [ -z "$PHONE_NORM" ]; then
    echo "Error: phone number has no digits after normalization" >&2
    exit 1
fi

URL="${API_BASE_URL%/}/${CHANNEL_ID}/sendTemplate"

# params carries body ONLY. Button text is fixed in the Meta template — no button param.

# {{1}} customer name → ${TEST_CUSTOMERNAME}
# {{2}} ticket number → ${TEST_TICKETNUMBER}
# {{3}} payment amount → ${TEST_PAYMENTAMOUNT}
# {{4}} due date → ${TEST_DUEDATE}
read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "template": "${TEMPLATE_NAME}",
  "namespace": "${TEMPLATE_NAMESPACE}",
  "language": { "policy": "deterministic", "code": "${TEMPLATE_LANGUAGE}" },
  "params": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "${TEST_CUSTOMERNAME}" },
        { "type": "text", "text": "${TEST_TICKETNUMBER}" },
        { "type": "text", "text": "${TEST_PAYMENTAMOUNT}" },
        { "type": "text", "text": "${TEST_DUEDATE}" }
      ]
    }

  ]
}
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.…), чтобы сопоставить уведомления о доставке.

200 OKОтвет
{
  "sent": true,
  "id": "wamid.HBgLMzgwNjM5...",
  "message": "Message accepted for delivery"
}
  • sent

    Принято для отправки — еще не на телефоне клиента

  • id

    Храните это: обратные вызовы доставки и hookInfo привязаны к этому

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

200 OKВебхук статуса доставки — данные, которые вы получаете
{
  "hooks": [
    {
      "id": "gBGGeSaGViBfAgnlzOSHEwK9O6F",
      "type": "message",
      "status": "sent",
      "timestamp": "1654864094",
      "recipient_id": "556123122026"
    }
  ]
}
  • status

    sent, delivered, read — или статус отказа, если применимо

  • id

    Соотносит колбэк с id результатом вызова send

  • timestamp

    Байты с Unix-часами в виде строки

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

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

СтатусОтветПричина
200Message was not sent: template is not definednamespace, template or language missing from the request body.
200template name (…) does not exist in <language>The template is approved in a different language than the one requested.
200Message was not sent: provide chatId, phone, bsuid, or usernameNo recipient the channel could resolve.
403access deniedThe token is wrong, or belongs to a different channel than the URL.
429too many requests. please try laterThe channel is over its send rate.

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

Да, для отправки холодных сообщений в WhatsApp нужен одобренный Meta шаблон.

Связанные

Оплаты и счета
WhatsApp Business API для подтверждения успешной оплаты
Сценарий отправляет клиенту персонализированный шаблон WhatsApp при успешной оплате.
Оплаты и счета
WhatsApp Business API для напоминания о просроченной оплате
Сценарий отправляет клиенту персонализированный шаблон WhatsApp, когда оплата просрочена.
Оплаты и счета
WhatsApp Business API для уточнения способа оплаты
Сценарий отправляет клиенту персонализированный шаблон WhatsApp, когда для выставления счёта нужно узнать способ оплаты.
Оплаты и счета
WhatsApp Business API для отправки ссылки на оплату
Сценарий отправляет клиенту персонализированный шаблон WhatsApp, когда для выставления счёта или при оплате необходимо собрать оплату.
Оплаты и счета
WhatsApp Business API для уведомлений об офлайн оплатах
Сценарий отправляет клиенту персонализированный шаблон WhatsApp при фиксации офлайн-оплаты.
Оплаты и счета
WhatsApp Business API для уведомлений о новых оплатах
Сценарий отправляет финансовому менеджеру персонализированный шаблон WhatsApp, когда поступает новая оплата.
Оплаты и счета
WhatsApp Business API для ежемесячного уведомления о счёте
Сценарий отправляет клиенту персонализированный шаблон WhatsApp при выдаче ежемесячного счёта.
Оплаты и счета
WhatsApp Business API для напоминания о возврате займа
Сценарий отправляет клиенту персонализированный шаблон WhatsApp перед датой погашения кредита или рассрочки.

Интегрируйте WhatsApp за часы
без проблем с инфраструктурой