WhatsApp Business API para menú de soporte — botones interactivos

Descripción del caso de uso

Este escenario envía un mensaje con botones interactivos con sendButton durante la ventana de atención al cliente de 24 horas. Tres respuestas rápidas permiten al cliente elegir menú principal, estado del pedido o derivación a agente sin escribir.

Ejemplo de plantilla

¿Cómo podemos ayudarte hoy?

Cuándo usarlo

Úsalo cuando un mensaje del cliente abre o continúa una sesión de soporte en WhatsApp y necesita una vía de autoservicio rápida antes de que un agente lea texto libre. Encaja en colas de soporte nivel 1 donde consultas repetidas de estado de pedido, menú y escalamiento ralentizan la primera respuesta dentro de la ventana de atención de 24 horas.

Flujo de trabajo

1. Estado registrado

   Llega un mensaje del cliente vía webhook y mantiene la sesión abierta.

   status: "read"

2. Construir y enviar

   Tu backend envía el menú de botones interactivos con guía en el pie de foto.

   POST /send_button

3. El cliente actúa

   El cliente toca una de las tres opciones.

   acción del usuario

4. Entregado

   El webhook entrega el id del botón para enrutar a flujos de menú, estado o agente.

   entregado

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. Ventana de sesión de 24 horas abierta · Cómo funciona la ventana de 24 horas
4. Opt-in del cliente · Cómo gestionar el consentimiento
5. Endpoint de webhook · Cómo configurar webhooks

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)



# === Test data ===
TEST_PHONE="___"                 # client phone in international format

PHONE_NORM="$(printf '%s' "$TEST_PHONE" | tr -cd '0-9')"
URL="${API_BASE_URL%/}/${CHANNEL_ID}/sendButton"

read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "body": "How can we help you today?",
  "footer": "Choose an option",
  "sections": [
    { "type": "reply", "reply": { "id": "menu", "title": "Main menu" } },
    { "type": "reply", "reply": { "id": "status", "title": "Order status" } },
    { "type": "reply", "reply": { "id": "agent", "title": "Talk to agent" } }
  ]
}
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."
else
  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"
}

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"
    }
  ]
}

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

Preguntas frecuentes