WhatsApp Business API para traspaso a especialista — compartir tarjeta de contacto

Descripción del caso de uso

Este escenario envía una tarjeta de contacto de WhatsApp con sendContact durante la ventana de servicio al cliente de 24 horas. El cliente recibe el nombre y teléfono del especialista sin copiar dígitos manualmente.

Ejemplo de plantilla

Comunícate con nuestro especialista usando la tarjeta de contacto a continuación.

Cuándo usarlo

Úsalo cuando el soporte de primera línea ya aprobó el escalamiento a un especialista asignado y la ventana de servicio al cliente de 24 horas sigue abierta. Encaja en mesas de ayuda donde un experto humano debe tomar el caso sin perder el contexto del chat — sobre todo cuando compartir el teléfono como texto plano puede provocar una marcación incorrecta.

Flujo de trabajo

1. Disparador

   Un agente marca el ticket listo para escalamiento a especialista.

   evento · disparado

2. Capturar evento

   Tu backend carga el nombre visible y el número de teléfono del especialista.

   phone: "+…"

3. Construir y enviar

   sendContact entrega la tarjeta de contacto en la sesión activa.

   POST /send_contact

4. Entregado

   El cliente guarda o llama al especialista desde WhatsApp.

   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}/sendContact"

# specialist display name (code_contract)
# specialist phone in E.164 format
read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "contacts": [
    {
      "name": { "formatted_name": "Jane Specialist", "first_name": "Jane Specialist" },
      "phones": [{ "phone": "+12025550199", "type": "CELL" }]
    }
  ]
}
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