Enviar tarjeta de contacto con WhatsApp API

Este escenario envía una tarjeta de contacto de WhatsApp con sendContact durante la ventana de servicio al cliente de 24 horas.

Probar la demo Ver ejemplo de código

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.

WhatsApp Business API for specialist handoff — share contact card

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.

Menos llamadas al número equivocado

sendContact entrega el nombre visible del especialista y el teléfono en E.164 como vCard en la sesión activa, así el cliente toca para llamar en lugar de reescribir dígitos desde un mensaje de texto.

Contacto guardado con un toque

La tarjeta abre el flujo nativo de guardar contacto de WhatsApp, así el nombre y número del especialista quedan en la agenda del cliente sin entrada manual.

El traspaso sigue en el mismo hilo

El mensaje sale dentro de la sesión abierta después de que un agente marca el ticket listo para escalamiento, así el cliente no abandona el chat de soporte para buscar un número en otro lado.

Los agentes no comparten números a mano

Tu backend carga el nombre y teléfono del especialista desde el contrato de integración cuando se aprueba el escalamiento, así los agentes de primera línea no copian ni dictan dígitos.

Flujo de trabajo

Disparador
Un agente marca el ticket listo para escalamiento a especialista.
evento · disparado
Capturar evento
Tu backend carga el nombre visible y el número de teléfono del especialista.
phone: "+…"
Construir y enviar
sendContact entrega la tarjeta de contacto en la sesión activa.
POST /send_contact
Entregado
El cliente guarda o llama al especialista desde WhatsApp.
entregado

Implementación técnica

Requisitos previos

Clave API de 1MSG · Cómo obtener la clave API
Cuenta de WhatsApp Business · Cómo conectar WABA
Ventana de sesión de 24 horas abierta · Cómo funciona la ventana de 24 horas
Opt-in del cliente · Cómo gestionar el consentimiento
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.

200 OKRespuesta

{
  "sent": true,
  "message": "Sent to [email protected]",
  "description": "Message has been sent to the provider",
  "id": "wamid.HBgLMzgwNjM5..."
}

sent
Aceptado para envío — aún no en el teléfono del cliente
id
Guárdalo; los callbacks de entrega y hookInfo se basan en él

Estados de entrega y webhooks →

Errores frecuentes

Estado	Respuesta de la API	Causa	Solución
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.
401	token is required	La petición no incluye el token.	Agrega el token del canal como parámetro token en la URL: https://api.1msg.io/{channelId}/{method}?token=…
429	too many requests. please try later	El canal superó su límite de envío.	Encola los mensajes de tu lado y reintenta con backoff exponencial.