WhatsApp Business API para encuesta post-entrega
El escenario envía al cliente una plantilla de WhatsApp personalizada después de entregar un pedido, pidiéndole calificar la calidad de la entrega.
Descripción del caso de uso
El escenario envía al cliente una plantilla de WhatsApp personalizada después de entregar un pedido, pidiéndole calificar la calidad de la entrega. El mensaje incluye el nombre del cliente, número de pedido y un breve prompt de encuesta. Un botón URL estático abre el formulario de feedback de entrega o página de encuesta.
Ejemplo de plantilla
Hola, {{1}}! El pedido #{{2}} ha sido entregado. {{3}} Por favor califica la calidad de la entrega — toma alrededor de un minuto.
- {{1}}nombre del cliente
- {{2}}número de pedido
- {{3}}prompt o instrucción de encuesta (p. ej. califica tu experiencia de entrega del 1 al 5, toma 1 minuto)
- “Calificar entrega”botón — fijo en la plantilla de Meta

Cuándo usarlo
Usa este escenario cuando un pedido se marca como entregado y el equipo necesita una encuesta de satisfacción de entrega estructurada en WhatsApp, en lugar de un mensaje manual de seguimiento o una encuesta solo por correo. Encaja en e-commerce y marcas D2C que recopilan feedback de 1–5 estrellas o NPS tras la entrega de última milla, equipos de logística con encuestas post-entrega estandarizadas y agencias que conectan triggers de entrega completada desde OMS, WMS o workflows e-commerce propios.
Flujo de trabajo
- Disparador
El transportista o OMS dispara un evento de entrega completada cuando el pedido llega al cliente.
evento·disparado - Capturar evento
El sistema obtiene el teléfono del destinatario y los campos de encuesta.
phone:"+…" - Construir y enviar
Se construye un mensaje de plantilla personalizado con tres variables en el cuerpo y un botón URL estático.
POST/sendTemplate - Entregado
El cliente recibe la solicitud de encuesta de entrega en WhatsApp con contexto del pedido.
entregado - Estado registrado
Se registra el resultado de entrega; la finalización de la encuesta se rastrea fuera de WhatsApp.
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 ===
TEST_PHONE="___" # client phone in international format
TEST_CUSTOMERNAME="___" # {{1}} customer name
TEST_PROCESS="___" # {{2}} process name
TEST_INFO="___" # {{3}} additional info
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_PROCESS=$TEST_PROCESS" \
"TEST_INFO=$TEST_INFO"; 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}} process name → ${TEST_PROCESS}
# {{3}} additional info → ${TEST_INFO}
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_PROCESS}" },
{ "type": "text", "text": "${TEST_INFO}" }
]
}
]
}
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.
{
"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. |

