Enviar factura PDF por WhatsApp API (sendFile)

Este escenario envía un documento PDF con sendFile durante la ventana de atención al cliente de WhatsApp de 24 horas.

Descripción del caso de uso

Este escenario envía un documento PDF con sendFile durante la ventana de atención al cliente de WhatsApp de 24 horas. Úsalo cuando facturación debe adjuntar una factura sin iniciar una nueva conversación con plantilla.

Ejemplo de plantilla

Factura del ticket {{1}}

{{1}}
número de ticket de soporte mostrado en el pie de foto del PDF

WhatsApp Business API for session send — invoice pdf

Cuándo usarlo

Usa este escenario cuando facturación debe entregar una factura PDF mientras la conversación de soporte sigue abierta en WhatsApp — el cliente escribió primero y la ventana de sesión de 24 horas está activa. Encaja en seguimiento de facturación dentro de hilos de helpdesk, donde adjuntar documentos con plantillas aprobadas sería lento o innecesario para equipos que integran 1MSG con backends de tickets y facturación.

Sin ida y vuelta de plantilla para un PDF

sendFile entrega la factura dentro de la ventana de sesión de 24 horas abierta, así facturación adjunta application/pdf sin enviar ni esperar una nueva plantilla aprobada por Meta.

La factura queda en el hilo de soporte

El PDF llega en el mismo chat de WhatsApp que el cliente usó para soporte, como application/pdf con nombre invoice.pdf, en lugar de un adjunto de correo aparte que quizá nunca abra.

El cliente puede relacionar el archivo con su ticket

Una variable del pie de foto lleva el número de ticket de soporte en "Factura del ticket {{1}}", así el cliente puede vincular el documento con el caso abierto sin buscar en otro canal.

Menos reenvío manual desde el helpdesk

Cuando el helpdesk marca un ticket listo para facturación, tu backend obtiene el número de ticket y la URL PDF o ruta de subida, y sendFile se dispara con ese evento.

Entrega registrada para seguimiento de facturación

El estado de entrega se escribe de vuelta en el helpdesk o sistema de facturación, así finanzas sabe que la factura llegó al cliente en el mismo hilo.

Flujo de trabajo

Disparador
El helpdesk marca un ticket listo para facturación mientras la sesión sigue abierta.
evento · disparado
Capturar evento
Tu backend obtiene el número de ticket y la ubicación del PDF de factura.
phone: "+…"
Construir y enviar
sendFile envía application/pdf con nombre invoice.pdf y un pie de foto que referencia el ticket.
POST /send_file
Entregado
El cliente recibe el PDF en el mismo hilo de 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
MEDIA_URL="___"                         # local file path or HTTPS URL for sendFile body

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

read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "body": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
  "filename": "invoice.pdf"
}
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.

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.
200	wrong file	El archivo no se pudo descargar ni subir: URL inalcanzable o base64 inválido.	Envía en body una URL HTTPS pública o base64 válido, o sube el archivo con /uploadMedia y envía mediaId con mediaType.
200	Message was not sent: filename	sendFile sin filename, así que el archivo no tiene extensión.	Agrega filename con extensión, por ejemplo factura.pdf.