WhatsApp Business API para notificación de nuevo pago
El escenario envía al gerente de finanzas una plantilla de WhatsApp personalizada cuando se recibe un pago nuevo.
Descripción del caso de uso
El escenario envía al gerente de finanzas una plantilla de WhatsApp personalizada cuando se recibe un pago nuevo. El mensaje incluye el nombre del cliente, monto del pago y fecha del pago. Un botón URL estático abre el dashboard de facturación.
Ejemplo de plantilla
💳 Nuevo pago recibido
Cliente: {{1}}
Monto: {{2}}
Fecha: {{3}}
Revisa el pago en el dashboard de facturación.
- {{1}}nombre del cliente
- {{2}}monto del pago
- {{3}}fecha del pago
- “Abrir facturación”botón — fijo en la plantilla de Meta

Cuándo usarlo
Usa este escenario cuando una pasarela de pago o el sistema de facturación registra un cargo exitoso y el gerente de finanzas necesita enterarse antes de volver a revisar el dashboard. Encaja en equipos de finanzas que monitorean pagos entrantes, operaciones de facturación que concilian pagos offline o bancarios en ERP, e integradores que conectan webhooks de PSP a alertas internas al gerente vía 1MSG.
Flujo de trabajo
- Disparador
Facturación o la pasarela de pago emite un evento de pago nuevo.
evento·disparado - Capturar evento
El sistema obtiene el teléfono del gerente de finanzas y los campos del resumen del pago.
phone:"+…" - Construir y enviar
Se construye una plantilla de notificación interna con tres variables en el cuerpo y un botón URL estático.
POST/sendTemplate - Entregado
El gerente recibe la alerta en WhatsApp en su teléfono.
entregado - Estado registrado
Se registra el resultado de entrega; el gerente abre el dashboard de facturación con el botón.
status:"read"

Implementación técnica
Requisitos previos
- Clave API de 1MSG · Cómo obtener la clave API
- Cuenta de WhatsApp Business · Cómo conectar WABA
- Plantilla de WhatsApp · Cómo aprobar una plantilla WABA
- 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 ===
MANAGER_PHONE="___" # manager phone in international format
TEST_CUSTOMERNAME="___" # {{1}} customer name
TEST_PAYMENTAMOUNT="___" # {{2}} payment amount
TEST_DATE="___" # {{3}} date or time
PHONE_NORM="$(printf '%s' "$MANAGER_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" "MANAGER_PHONE=$MANAGER_PHONE" \
"TEST_CUSTOMERNAME=$TEST_CUSTOMERNAME" \
"TEST_PAYMENTAMOUNT=$TEST_PAYMENTAMOUNT" \
"TEST_DATE=$TEST_DATE"; 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}} payment amount → ${TEST_PAYMENTAMOUNT}
# {{3}} date or time → ${TEST_DATE}
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_PAYMENTAMOUNT}" },
{ "type": "text", "text": "${TEST_DATE}" }
]
}
]
}
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 manager."
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.
{
"sent": true,
"id": "wamid.HBgLMzgwNjM5...",
"message": "Message accepted for delivery"
}sentAceptado para envío — aún no en el teléfono del cliente
idGuárdalo; los callbacks de entrega y
hookInfose basan en él
La entrega llega después, como un callback aparte. Registra un webhook (POST …/webhook) y 1MSG enviará las actualizaciones de estado a tu endpoint HTTPS en un payload hooks[] de nivel superior.
{
"hooks": [
{
"id": "gBGGeSaGViBfAgnlzOSHEwK9O6F",
"type": "message",
"status": "sent",
"timestamp": "1654864094",
"recipient_id": "556123122026"
}
]
}statussent,delivered,read— o un estado de fallo cuando apliqueidCorrelaciona el callback con el
iddevuelto por el envíotimestampSegundos Unix, como cadena
Si prefieres no recibir callbacks, consulta GET {base}/{channel}/hookInfo?messageId=<id> en su lugar. En la práctica la entrega suele completarse en segundos — pero el contrato de la API no lo garantiza, así que nunca bloquees un flujo esperándola.
Errores frecuentes
| Estado | Respuesta | Causa |
|---|---|---|
| 200 | Message was not sent: template is not defined | Falta namespace, template o language en el cuerpo de la petición. |
| 200 | template name (…) does not exist in <language> | La plantilla está aprobada en otro idioma que el solicitado. |
| 200 | Message was not sent: provide chatId, phone, bsuid, or username | Ningún destinatario que el canal pudiera resolver. |
| 403 | access denied | El token es incorrecto, o pertenece a otro canal que el de la URL. |
| 429 | too many requests. please try later | El canal superó su límite de envío. |

