WhatsApp-Dokumentnachrichten
Eine Dokumentnachricht enthält eine öffentliche URL, die WhatsApp beim Senden abruft, mit einer optionalen Beschriftung und einem optionalen Dateinamen. Sie ist der größte Medientyp und der einzige, der sowohl eine Beschriftung als auch einen Dateinamen enthält.
Dokument senden
Setzen Sie 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"
}
}'Die vollständige Struktur fügt caption und filename hinzu:
Codebeispiel
{
"to": "+16505551234",
"from": "+13124495648",
"document": {
"url": "https://cdn.example.com/invoices/a1b2c3.pdf",
"caption": "Your invoice for order A1B2C3",
"filename": "invoice-a1b2c3.pdf"
}
}from ist bei jeder Service-Nachricht erforderlich: eine Nummer, die Ihr Workspace besitzt, keine von Bird verwaltete.
Beschränkungen
| Feld | Grenzwert | Geprüft von |
|---|---|---|
| Dateigröße | 100 MB | nur WhatsApp, beim Abruf (async) |
| Dateityp | PDF, Word, Excel, PowerPoint oder Klartext werden im WhatsApp-Client zuverlässig dargestellt; andere Typen werden übertragen, aber nicht unterstützt | nur WhatsApp, beim Abruf (async) |
| caption | bis zu 1024 Zeichen | Bird, bei Annahme (422) |
| filename | 1 bis 100 Zeichen | Bird, bei Annahme (422); dieses Limit ist Birds eigenes, da WhatsApp kein Dateinamenlimit dokumentiert |
| url | absolut, https, hat einen Host, kein rohes Leerzeichen | Bird, bei Annahme (422) |
Bird prüft die Form der URL sowie die Länge der Beschriftung und des Dateinamens, bevor etwas in die Warteschlange gestellt wird. Dateigröße und -typ werden nicht geprüft; das kann nur der eigene Abruf von WhatsApp beim Senden. Siehe im Hub Medien per URL senden und Wenn Medien fehlschlagen.
Ein eingehendes Dokument lesen
Ein eingehendes Dokument enthält dasselbe document-Objekt, zusätzlich ein id und mime_type, die Bird durch Abruf der Datei ermittelt hat. Beide fehlen bei einem ausgehenden Rücklesen, da Bird die gesendete Datei nie selbst abgerufen hat, und filename bei einem eingehenden Dokument enthält das, was das Gerät des Kontakts geliefert hat. Siehe WhatsApp-Dokumente empfangen für das vollständige eingehende Lesen, die whatsapp.received-Payload und worauf Sie achten sollten.
Beschränkungen und Fehlerfälle
- Das Kundenservice-Fenster muss offen sein. Dokumente sind Service-Nachrichten und nur innerhalb eines offenen Fensters zustellbar; siehe im Hub Kundenservice-Fenster.
- Bird lehnt http ab; WhatsApp selbst würde es abrufen. Siehe im Hub Medien per URL senden für die vollständige Formprüfung.
- Ein fehlgeschlagener Abruf wird trotzdem berechnet, und dieser Medientyp ist am ehesten davon betroffen. Mit 100 MB ist ein Dokument das Größte, was Sie senden können, und Bird prüft bei der Annahme nichts an den tatsächlichen Bytes. Siehe im Hub Wenn Medien fehlschlagen für media_rejected und die Tatsache, dass bei Fehlschlag trotzdem Kosten anfallen. Der eigene Ablehnungstext von Dokumenten aus WhatsApp wurde nicht unabhängig gemessen wie der von Bildern, daher ist das Mapping als per Symmetrie abgeleitet zu betrachten, nicht als pro Ursache bestätigt.
- Das Weglassen von filename bedeutet nicht, dass der Empfänger keinen Namen sieht. WhatsApp leitet einen aus dem URL-Pfad ab, was ein undurchsichtiger Hash oder Slug sein kann statt etwas Lesbarem. Setzen Sie filename explizit, um zu steuern, was tatsächlich angezeigt wird.
- Das 100-Zeichen-Limit für filename ist Birds eigene Wahl, keine WhatsApp-Beschränkung. WhatsApp dokumentiert überhaupt kein Dateinamenlängenlimit.
- WhatsApp speichert eine abgerufene URL etwa 10 Minuten im Cache. Wenn Sie dieselbe URL innerhalb dieses Zeitraums erneut senden, wird der erste Abruf wiederverwendet; ändern Sie die URL, um einen neuen Abruf zu erzwingen.
Nächste Schritte
- WhatsApp-Service-Nachrichten: das Kundenservice-Fenster und das Modell, das alle Service-Nachrichten gemeinsam haben
- Bilder: für ein Foto oder eine Grafik statt einer Datei
- Templates: für Nachrichten, die Sie senden können, wenn das Fenster geschlossen ist
- WhatsApp-Nachrichten senden: der Request-Envelope, das 202-Modell und sichere Wiederholungsversuche
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.
Anleitung ansehenConnecting WhatsApp to Bird: from buying a number to a live channelDas Konzept verstehenWhat is the 24-hour customer service window on WhatsApp?Das Tool verwendenWhatsApp message builderDie Funktion erkundenWhatsApp
Übung ausprobieren und ein Implementierungs-Briefing erhalten