Messages document WhatsApp
Un message document transporte une URL publique que WhatsApp récupère au moment de l'envoi, avec une légende facultative et un nom de fichier facultatif. C'est le type de média le plus volumineux, et le seul qui accepte à la fois une légende et un nom de fichier.
Envoyer un document
Définissez 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 +16505551234{
"name": "whatsapp_send",
"arguments": {
"document": {
"url": "https://cdn.example.com/invoices/a1b2c3.pdf"
},
"from": "+13124495648",
"to": "+16505551234"
}
}curl -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 forme complète ajoute caption et filename :
Exemple de code
{
"to": "+16505551234",
"from": "+13124495648",
"document": {
"url": "https://cdn.example.com/invoices/a1b2c3.pdf",
"caption": "Your invoice for order A1B2C3",
"filename": "invoice-a1b2c3.pdf"
}
}from est obligatoire sur chaque message de service : un numéro appartenant à votre espace de travail, pas un numéro géré par Bird.
Limites
| Champ | Limite | Appliquée par |
|---|---|---|
| Taille du fichier | 100 Mo | WhatsApp uniquement, à la récupération (async) |
| Type de fichier | PDF, Word, Excel, PowerPoint ou texte brut s'affichent correctement dans le client WhatsApp ; les autres types sont transmis mais non pris en charge | WhatsApp uniquement, à la récupération (async) |
| caption | jusqu'à 1024 caractères | Bird, à l'acceptation (422) |
| filename | 1 à 100 caractères | Bird, à l'acceptation (422) ; cette limite est propre à Bird, car WhatsApp ne documente aucune limite de nom de fichier |
| url | absolue, https, possède un hôte, pas d'espace brut | Bird, à l'acceptation (422) |
Bird vérifie la forme de l'URL ainsi que la longueur de la légende et du nom de fichier avant toute mise en file d'attente. Il ne vérifie pas la taille ni le type réels du fichier ; seule la récupération par WhatsApp au moment de l'envoi le peut. Consultez les pages du hub envoyer un média par URL et quand un média échoue.
Lire un document entrant
Un document entrant transporte le même objet document, plus un id et un mime_type que Bird a appris en récupérant le fichier. Les deux sont absents lors de la relecture d'un message sortant, car Bird n'a jamais récupéré le fichier qu'il a envoyé, et filename sur un document entrant correspond à ce que l'appareil du contact a fourni. Consultez Recevoir des documents WhatsApp pour la lecture entrante complète, le payload whatsapp.received et les points à surveiller.
Limites et modes d'échec
- La fenêtre de service client doit être ouverte. Les documents sont des messages de service, livrables uniquement dans une fenêtre ouverte ; consultez la page du hub fenêtre de service client.
- Bird rejette http ; WhatsApp lui-même la récupérerait. Consultez la page du hub envoyer un média par URL pour la vérification complète de la forme.
- Une récupération rejetée est tout de même facturée, et c'est le type de média le plus susceptible d'y être confronté. À 100 Mo, un document est l'élément le plus volumineux que vous puissiez envoyer, et Bird ne vérifie rien sur les octets réels à l'acceptation. Consultez la page du hub quand un média échoue pour media_rejected et le fait de facturation en cas d'échec. Le texte de rejet propre aux documents provenant de WhatsApp n'a pas été mesuré indépendamment comme celui des images, donc considérez la correspondance comme déduite par symétrie plutôt que confirmée cas par cas.
- Omettre filename ne signifie pas que le destinataire ne voit aucun nom. WhatsApp en dérive un à partir du chemin de l'URL, ce qui peut donner un hash opaque ou un slug plutôt qu'un nom lisible. Définissez filename explicitement pour contrôler ce qui s'affiche réellement.
- La limite de 100 caractères pour filename est un choix propre à Bird, pas une limite de WhatsApp. WhatsApp ne documente aucune limite de longueur de nom de fichier.
- WhatsApp met en cache une URL récupérée pendant environ 10 minutes. Renvoyer la même URL dans cette fenêtre resert la première récupération ; modifiez l'URL pour forcer une nouvelle récupération.
Étapes suivantes
- Messages de service WhatsApp : la fenêtre de service client et le modèle commun à tous les messages de service
- Images : pour envoyer une photo ou un graphique au lieu d'un fichier
- Templates : pour les messages que vous pouvez envoyer une fois la fenêtre fermée
- Envoyer des messages WhatsApp : l'enveloppe de requête, le modèle 202 et les réessais sûrs
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Regarder le guideConnecting WhatsApp to Bird: from buying a number to a live channelComprendre le conceptWhat is the 24-hour customer service window on WhatsApp?Utiliser l'outilWhatsApp message builderExplorer la fonctionnalitéWhatsApp
Essayez la pratique et obtenez un guide d'implémentation