Solicitud de verificación de identidad (WhatsApp API)
El escenario envía al cliente una plantilla de WhatsApp personalizada cuando se requiere verificación de identidad o KYC pero aún no ha comenzado.
Descripción del caso de uso
El escenario envía al cliente una plantilla de WhatsApp personalizada cuando se requiere verificación de identidad o KYC pero aún no ha comenzado. El mensaje incluye el nombre del cliente, el proceso de verificación e instrucciones del siguiente paso. Un botón URL estático abre el portal de verificación o el flujo de carga de documentos.
Ejemplo de plantilla
Hola, {{1}}! Para continuar, por favor completa tu {{2}}. {{3}} Toca el botón de abajo para iniciar la verificación. Si tienes preguntas — estamos para ayudarte.
- {{1}}nombre del cliente
- {{2}}proceso de verificación (p. ej. verificación de identidad, control KYC, revisión de documentos)
- {{3}}instrucción del siguiente paso (p. ej. sube ID y toma selfie en el portal antes del viernes)
- “Iniciar verificación”botón — fijo en la plantilla de Meta

Cuándo usarlo
Usa este escenario cuando un cliente debe completar verificación de identidad o KYC antes de usar tu producto, recibir pagos o desbloquear funciones — y aún no ha iniciado el flujo, sin conversación abierta en WhatsApp para contactarlo en sesión. Encaja en equipos fintech que condicionan activación de cuenta al KYC, marketplaces que exigen verificación de vendedores antes de publicar, y agencias que conectan triggers de cumplimiento u onboarding desde el CRM del cliente a empujones de verificación en WhatsApp.
Flujo de trabajo
- El cliente actúa
Una regla de negocio o paso de onboarding exige que el cliente complete verificación de identidad o KYC.
acción del usuario - Capturar evento
El sistema detecta el evento de verificación requerida y obtiene el teléfono del destinatario.
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 verificación en WhatsApp con contexto del proceso e instrucciones del siguiente paso.
entregado - Estado registrado
Se registra el resultado de entrega; el cliente puede iniciar la verificación vía el enlace del portal.
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_NEXTSTEP="___" # {{3}} next step
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_NEXTSTEP=$TEST_NEXTSTEP"; 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}} next step → ${TEST_NEXTSTEP}
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_NEXTSTEP}" }
]
}
]
}
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,
"message": "Sent to [email protected]",
"description": "Message has been sent to the provider",
"id": "wamid.HBgLMzgwNjM5..."
}sentAceptado para envío — aún no en el teléfono del cliente
idGuárdalo; los callbacks de entrega y
hookInfose basan en él
Errores frecuentes
| Estado | Respuesta de la API | Causa | Solución |
|---|---|---|---|
| 200 | Message was not sent: template is not defined | Falta 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"}. |
| 200 | template 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. |
| 200 | Message was not sent: provide chatId, phone, bsuid, or username | Ningú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. |
