WhatsApp Business API para contacto de mensajero o conductor — 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 después de asignar un conductor o mensajero al pedido.

Ejemplo de plantilla

El contacto de tu mensajero para esta entrega está en la tarjeta de abajo.

Cuándo usarlo

Usa este escenario cuando logística asigna un conductor o mensajero a una entrega activa y el comprador necesita el teléfono de esa persona sin copiar dígitos de un mensaje de texto plano. Encaja en equipos de entrega última milla que comparten contactos para guardar con un toque dentro de una sesión abierta del pedido, y en operadores de flota que traspasan al mensajero asignado para que el cliente llame directo desde WhatsApp.

Flujo de trabajo

1. Disparador

   Logística asigna un conductor o mensajero a la entrega.

   evento · disparado

2. Capturar evento

   Tu backend carga el nombre para mostrar y teléfono del mensajero.

   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 mensajero 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": "Иван Курьер", "first_name": "Иван Курьер" },
      "phones": [{ "phone": "+998901234567", "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