WhatsApp Business API para instrucciones pre-visita
El escenario envía al cliente una plantilla de WhatsApp personalizada antes de una visita con instrucciones de preparación.
Descripción del caso de uso
El escenario envía al cliente una plantilla de WhatsApp personalizada antes de una visita con instrucciones de preparación. El mensaje incluye nombre del cliente, servicio, fecha de visita e instrucciones en la cuarta variable. Un botón URL estático abre detalles de la reserva.
Ejemplo de plantilla
Hola, {{1}}! Antes de tu {{2}} el {{3}}, ten en cuenta: {{4}}
- {{1}}nombre del cliente
- {{2}}servicio o tipo de cita
- {{3}}fecha de visita
- {{4}}instrucciones de preparación pre-visita
- “Ver reserva”botón — fijo en la plantilla de Meta

Cuándo usarlo
Usa este escenario cuando se acerca una visita y el cliente aún necesita pasos claros de preparación antes de llegar — reglas de ayuno, documentos que traer o qué usar — pero esas instrucciones quedan en correos o PDF que quizá nunca abre. Encaja en equipos de salud que envían preparación antes de un procedimiento, salones y negocios de servicios con requisitos pre-visita, e integradores que conectan jobs pre-visita del agendador a WhatsApp outbound.
Flujo de trabajo
- Disparador
El sistema de agendamiento dispara un evento de instrucciones pre-visita.
evento·disparado - Capturar evento
El sistema obtiene el teléfono del cliente y los campos de la reserva.
phone:"+…" - 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 - Entregado
El cliente recibe el mensaje de WhatsApp con guía de preparación.
entregado - Estado registrado
Se registra el resultado de entrega para agendamiento o seguimiento en CRM.
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_SERVICE="___" # {{2}} service name
TEST_BOOKINGDATE="___" # {{3}} booking date
TEST_ADDITIONALINFO="___" # {{4}} 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_SERVICE=$TEST_SERVICE" \
"TEST_BOOKINGDATE=$TEST_BOOKINGDATE" \
"TEST_ADDITIONALINFO=$TEST_ADDITIONALINFO"; 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}} booking date → ${TEST_BOOKINGDATE}
# {{4}} additional info → ${TEST_ADDITIONALINFO}
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_BOOKINGDATE}" },
{ "type": "text", "text": "${TEST_ADDITIONALINFO}" }
]
}
]
}
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. |

