Shared Inbox de WhatsApp para nueva PlataformaMás
1msg official logo

Aviso de factura mensual con WhatsApp API

El escenario envía al cliente una plantilla de WhatsApp personalizada cuando se emite una factura mensual.

Descripción del caso de uso

El escenario envía al cliente una plantilla de WhatsApp personalizada cuando se emite una factura mensual. El mensaje incluye el nombre del cliente, nombre del servicio, monto de la factura y fecha de vencimiento. Un botón URL estático abre la página de pago.

Ejemplo de plantilla

Hola, {{1}}! Tu factura mensual de "{{2}}" es {{3}}. Vencimiento del pago: {{4}}.

Pagar factura
  • {{1}}
    nombre del cliente
  • {{2}}
    nombre del servicio o plan
  • {{3}}
    monto de la factura
  • {{4}}
    fecha de vencimiento del pago
  • “Pagar factura”
    botón — fijo en la plantilla de Meta
WhatsApp Business API for monthly invoice notification

Cuándo usarlo

Usa este escenario cuando facturación emite una factura mensual recurrente y el cliente no tiene chat abierto en WhatsApp — solo una plantilla aprobada puede llevar el aviso primero. Encaja en facturación SaaS y suscripciones, servicios públicos y membresías que pierden facturas en filtros de correo, e integradores que conectan calendarios de facturación recurrente con entrega por WhatsApp.

Facturas que el cliente sí ve
El nombre del cliente, el servicio, el monto y la fecha de vencimiento llegan como cuatro variables del cuerpo en WhatsApp, así la factura queda en el chat que revisa a diario y no en una carpeta de correo que ignora.
Pago sin buscar el enlace
Un botón URL estático con la etiqueta Pagar factura abre la página de pago en línea; la URL está fijada en la plantilla de Meta, así que vía API solo se envían las cuatro variables del cuerpo.
Cero avisos de factura manuales
Facturación dispara un evento de factura mensual emitida, el sistema obtiene el teléfono y los campos de la factura, y la plantilla personalizada sale sin que alguien retipee montos o fechas de vencimiento.
Entrega registrada para seguimiento
El resultado del envío se escribe para facturación o CRM, así los equipos pueden reintentar o escalar cuando el aviso de factura no llega al cliente.

Flujo de trabajo

  1. Disparador

    Facturación emite una factura mensual y dispara un evento.

    evento · disparado

  2. Capturar evento

    El sistema obtiene el teléfono del cliente y los campos de la factura.

    phone: "+…"

  3. Construir y enviar

    Se construye un mensaje de plantilla personalizado con cuatro variables en el cuerpo y un botón URL estático.

    POST /sendTemplate

  4. Entregado

    El cliente recibe la notificación de factura en WhatsApp y puede pagar con el botón.

    entregado

  5. Estado registrado

    Se registra el resultado de entrega para seguimiento de facturación o CRM.

    status: "read"

WhatsApp Business API for monthly invoice notification

Implementación técnica

Requisitos previos

  1. Clave API de 1MSG · Cómo obtener la clave API
  2. Cuenta de WhatsApp Business · Cómo conectar WABA
  3. Plantilla de WhatsApp · Cómo aprobar una plantilla WABA
  4. Opt-in del cliente · Cómo gestionar el consentimiento

Ejemplos de código

#!/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_SERVICE="___"         # {{2}} service name
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_SERVICE=$TEST_SERVICE" \
            "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}} service name → ${TEST_SERVICE}
# {{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_SERVICE}" },
        { "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

Respuesta y estado de entrega

HTTP 2xx y JSON "sent": true significan que 1MSG aceptó el mensaje para envío — no que ya llegó al teléfono del cliente. Guarda el campo id (tipo wamid.…) para correlacionar los callbacks de entrega.

200 OKRespuesta
{
  "sent": true,
  "message": "Sent to [email protected]",
  "description": "Message has been sent to the provider",
  "id": "wamid.HBgLMzgwNjM5..."
}
  • sent

    Aceptado para envío — aún no en el teléfono del cliente

  • id

    Guárdalo; los callbacks de entrega y hookInfo se basan en él

Estados de entrega y webhooks →

Errores frecuentes

EstadoRespuesta de la APICausaSolución
200Message was not sent: template is not definedFalta namespace, template o language en el cuerpo de la petición.Envía los tres. Toma namespace y el nombre exacto de la plantilla de GET /templates; language es un objeto: {"policy": "deterministic", "code": "es_MX"}.
200template name (…) does not exist in <language>La plantilla está aprobada en otro idioma que el solicitado.Usa el código de idioma exacto con el que se aprobó la plantilla (por ejemplo, es_MX no es lo mismo que es). Revísalo en GET /templates.
200Message was not sent: provide chatId, phone, bsuid, or usernameNingún destinatario que el canal pudiera resolver.Envía un solo destinatario: phone (código de país y número, solo dígitos), chatId (por ejemplo [email protected]) o bsuid.

Todos los códigos de error →

Preguntas comunes

Relacionado

Desarrolla para WhatsApp en horas
sin complicaciones de infraestructura