Mensajes de documento de WhatsApp
Un mensaje de documento lleva una URL pública que WhatsApp obtiene en el momento del envío, con un pie de texto opcional y un nombre de archivo opcional. Es el tipo de medio más grande, y el único que admite tanto un pie de texto como un nombre de archivo.
Enviar un documento
Establece document.url:
const msg = await bird.whatsapp.send({
to: "+16505551234",
from: "+13124495648",
document: { url: "https://cdn.example.com/invoices/a1b2c3.pdf" },
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
document={"url": "https://cdn.example.com/invoices/a1b2c3.pdf"},
)
print(msg.id, msg.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
From: "+13124495648",
Document: &bird.WhatsAppDocumentSend{Url: "https://cdn.example.com/invoices/a1b2c3.pdf"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$document = (new WhatsAppMessageSendRequestDocument())
->setUrl('https://cdn.example.com/invoices/a1b2c3.pdf');
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
document: $document,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--document https://cdn.example.com/invoices/a1b2c3.pdf \
--from +13124495648 \
--to +16505551234curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+16505551234",
"from": "+13124495648",
"document": {
"url": "https://cdn.example.com/invoices/a1b2c3.pdf"
}
}'La forma completa añade caption y filename:
{
"to": "+16505551234",
"from": "+13124495648",
"document": {
"url": "https://cdn.example.com/invoices/a1b2c3.pdf",
"caption": "Your invoice for order A1B2C3",
"filename": "invoice-a1b2c3.pdf"
}
}from es obligatorio en cada mensaje de servicio: un número que tu espacio de trabajo posee, no uno gestionado por Bird.
Límites
| Campo | Límite | Aplicado por |
|---|---|---|
| Tamaño de archivo | 100 MB | Solo WhatsApp, al obtener el archivo (async) |
| Tipo de archivo | PDF, Word, Excel, PowerPoint o texto plano se muestran de forma fiable en el cliente de WhatsApp; otros tipos se transmiten pero no están soportados | Solo WhatsApp, al obtener el archivo (async) |
caption | hasta 1024 caracteres | Bird, al aceptar (422) |
filename | de 1 a 100 caracteres | Bird, al aceptar (422); este tope es propio de Bird, ya que WhatsApp no documenta ningún límite de nombre de archivo |
url | absoluta, https, con host, sin espacios en crudo | Bird, al aceptar (422) |
Bird comprueba la forma de la URL y la longitud del pie de texto y del nombre de archivo antes de encolar nada. No comprueba el tamaño ni el tipo real del archivo; solo la obtención propia de WhatsApp en el momento del envío puede hacerlo. Consulta en el hub enviar medios por URL y cuando un medio falla.
Leer un documento entrante
Un documento entrante lleva el mismo objeto document, más un id y mime_type que Bird obtuvo al descargar el archivo. Ambos están ausentes en la lectura de un mensaje saliente, ya que Bird nunca descargó el archivo que envió, y filename en uno entrante es lo que proporcionó el dispositivo del contacto. Consulta Recibir documentos de WhatsApp para la lectura entrante completa, el payload whatsapp.received y qué tener en cuenta.
Límites y modos de fallo
- La ventana de servicio al cliente debe estar abierta. Los documentos son mensajes de servicio, entregables solo dentro de una ventana abierta; consulta en el hub la ventana de servicio al cliente.
- Bird rechaza
http; WhatsApp mismo lo obtendría. Consulta en el hub enviar medios por URL para la comprobación completa de forma. - Una obtención rechazada se cobra igualmente, y este es el tipo de medio con más probabilidad de sufrirlo. Con 100 MB, un documento es lo más grande que puedes enviar, y Bird no comprueba nada de los bytes reales al aceptar. Consulta en el hub cuando un medio falla para ver
media_rejectedy el cobro en caso de fallo. - Omitir
filenameno significa que el destinatario no vea ningún nombre. WhatsApp deriva uno a partir de la ruta de la URL, que puede ser un hash opaco o un slug en lugar de algo legible. Establecefilenamede forma explícita para controlar lo que realmente se muestra. - El tope de 100 caracteres de
filenamees una decisión propia de Bird, no un límite de WhatsApp. WhatsApp no documenta ningún límite de longitud de nombre de archivo. - WhatsApp almacena en caché una URL obtenida durante unos 10 minutos. Reenviar la misma URL dentro de esa ventana sirve de nuevo la primera obtención; varía la URL para forzar una nueva.
Próximos pasos
- Mensajes de servicio de WhatsApp: la ventana de servicio al cliente y el modelo que comparten todos los mensajes de servicio
- Imágenes: para una foto o gráfico en lugar de un archivo
- Plantillas: para mensajes que puedes enviar una vez cerrada la ventana
- Enviar mensajes de WhatsApp: la estructura de la solicitud, el modelo
202y reintentos seguros
Recursos relacionados
Continúa con la documentación, guías y ejemplos de este tema.