WhatsApp-Standortanfragen
Eine Standortanfrage platziert einen Button unter einer WhatsApp-Nachricht, der den Empfänger bittet, seinen aktuellen Standort zu teilen. Verwenden Sie sie, wenn Sie eine aktuelle Position benötigen, etwa einen Abholpunkt, und keine gespeicherte Adresse. Für eine Telefonnummer verwenden Sie stattdessen Kontaktinfo-Anfragen.
Standortanfrage senden
Setzen Sie interactive.type auf location_request_message, mit einem body_text und sonst nichts. WhatsApp rendert den Button selbst, daher gibt es nichts, womit er beschriftet werden könnte:
const msg = await bird.whatsapp.send({
to: "+16505551234",
from: "+13124495648",
interactive: {
type: "location_request_message",
body_text:
"Let's start with your pickup. Share your current location, or type an address instead.",
},
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
interactive={
"type": "location_request_message",
"body_text": "Let's start with your pickup. Share your current location, or type an address instead.",
},
)
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",
Interactive: &bird.WhatsAppInteractiveSend{
Type: "location_request_message",
BodyText: "Let's start with your pickup. Share your current location, or type an address instead.",
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$interactive = (new WhatsAppMessageSendRequestInteractive())
->setType('location_request_message')
->setBodyText("Let's start with your pickup. Share your current location, or type an address instead.");
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
interactive: $interactive,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--from +13124495648 \
--interactive "{\"body_text\":\"Let's start with your pickup. Share your current location, or type an address instead.\",\"type\":\"location_request_message\"}" \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"from": "+13124495648",
"interactive": {
"body_text": "Let's start with your pickup. Share your current location, or type an address instead.",
"type": "location_request_message"
},
"to": "+16505551234"
}
}curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": "+16505551234",
"from": "+13124495648",
"interactive": {
"type": "location_request_message",
"body_text": "Let'\''s start with your pickup. Share your current location, or type an address instead."
}
}'from ist bei jeder Service-Nachricht erforderlich: eine Nummer, die Ihr Workspace besitzt, keine von Bird verwaltete. Dieser Typ benennt kein eigenes Feld, und das Schema verbietet header, footer_text und jedes Feld anderer Typen (buttons, list, cta_url, cards) ausdrücklich, sodass body_text die gesamte Nachricht ist, begrenzt auf 1024 Zeichen.
in_reply_to_message_id funktioniert auch bei diesem Typ, um eine frühere Nachricht in derselben Konversation zu zitieren. Siehe im Hub Eine Nachricht zitieren, um eine Antwort zuzuordnen für Details zur Auflösung und was sie verfehlen kann.
Den geteilten Standort lesen
Ein Tippen erzeugt kein interactive_reply. Es kommt als gewöhnliche eingehende location-Nachricht an, in derselben Form, die ein Kontakt erzeugen würde, der seinen Standort unaufgefordert teilt. Eine Integration, die bereits eingehende Standorte liest, braucht für diesen Typ keinen neuen Zweig:
Codebeispiel
{
"id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
"direction": "inbound",
"from": { "phone_number": "+16505551234" },
"to": { "phone_number": "+13124495648" },
"status": "received",
"in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
"location": {
"latitude": 37.7793,
"longitude": -122.4193,
"name": "Embarcadero Plaza",
"address": "1 Market St, San Francisco, CA 94105"
},
"created_at": "2026-08-25T09:04:11Z"
}Keines der Felder von location ist erforderlich: latitude und longitude sind in der Regel beide vorhanden, aber name fehlt, wenn der Empfänger nur einen einfachen Pin geteilt hat, address erscheint nur, wenn name ebenfalls gesetzt ist, und url erscheint nur bei Geschäftsstandorten, die der Client des Empfängers zufällig mitliefert. Programmieren Sie defensiv, statt davon auszugehen, dass eine Straßenadresse mit dem Pin kommt. Sie sehen diese Antwort über die Nachrichtenliste oder GET /v1/whatsapp/messages/{id}; siehe im Hub Eine Antwort lesen für den vollständigen Ablauf.
Die Antwort der Frage zuordnen
Meta setzt bei der Antwort dieses Typs ein context, das die Anfrage benennt, auf die geantwortet wird. Die eingehende Nachricht enthält also in_reply_to_message_id, und Sie brauchen kein eigenes Zuordnungsschema:
Codebeispiel
{
"direction": "inbound",
"in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
"location": { "latitude": 37.7793, "longitude": -122.4193 }
}Siehe Eine Nachricht zitieren, um eine Antwort zuzuordnen für Details zur Auflösung und wie ein Fehlschlag aussieht.
Das ist der bewusste Unterschied zu Kontaktinfo-Anfragen: Die Antwort dieses Typs enthält überhaupt kein context, sodass in_reply_to_message_id nie aufgelöst wird und die Zuordnung auf from plus Timing zurückfällt. Die Antwort einer Standortanfrage wird dagegen aufgelöst, daher ist in_reply_to_message_id der zuverlässige Weg, den geteilten Standort der Anfrage zuzuordnen, die ihn ausgelöst hat.
Worauf Sie achten sollten
- Das Kundenservice-Fenster muss offen sein. Eine Standortanfrage ist eine Service-Nachricht, die nur innerhalb eines offenen Fensters zustellbar ist; siehe im Hub Kundenservice-Fenster. Die Fensterprüfung schlägt offen fehl, sodass ein 202 kein Beweis ist, dass das Fenster beim Senden tatsächlich offen war.
- from muss eine Nummer sein, die Ihr Workspace besitzt. Wird sie weggelassen oder eine Nummer angegeben, die kein verbundener Absender ist, wird die Anfrage abgelehnt, bevor der Versand erstellt wird.
- Eine Antwort ist nicht garantiert. Der Empfänger kann den Standortfreigabe-Bildschirm schließen, die Nachricht ganz ignorieren oder stattdessen eine Adresse als Freitext eingeben, die als gewöhnliche eingehende Textnachricht ohne location ankommt. Meta dokumentiert kein Signal für eine abgelehnte oder verworfene Freigabe. Behandeln Sie die Anfrage daher als Fire-and-Forget und setzen Sie auf Ihrer Seite ein Timeout, statt auf eine Antwort zu warten, die möglicherweise nie kommt.
- Ein geteilter Pin kann nur Koordinaten enthalten. Der Client des Empfängers entscheidet, ob ein Name und eine Adresse angehängt werden; ein einfacher Pin enthält beides nicht. Gehen Sie also nicht davon aus, dass das eine mit dem anderen kommt.
- Kein Header, kein Footer und kein eigenes Feld. Das Schema verbietet header und footer_text bei diesem Typ ausdrücklich, und es gibt kein Feld, um den Button zu beschriften. Jeder Hinweistext, den Sie benötigen, muss in body_text stehen.
- Die Antwort ist eine location-Nachricht, kein interactive_reply. Eine Integration, die nur interactive_reply auf ein Tippen überwacht, verpasst diesen Typ vollständig; überwachen Sie stattdessen eingehende location.
Alles, was das Schema hier ausdrücken kann, ein zu langes body_text, ein header, ein footer_text oder eines von buttons, list, cta_url, cards, ist ein einfacher Request-Validierungsfehler ohne Katalogcode. Ein Zitat, das nicht aufgelöst wird, lässt die Anfrage fehlschlagen, bevor etwas erstellt oder berechnet wird: 404 E15071, wenn die ID keine Nachricht benennt, die dieser Workspace enthält, 422 E15072, wenn sie eine benennt, die nicht zitiert werden kann. Siehe im Hub Fehler für die vollständige interaktive Fehlertabelle und WhatsApp-Nachrichten senden für die Fehler, die jeder WhatsApp-Versand auslösen kann.
Nächste Schritte
- Interaktive WhatsApp-Nachrichten: was alle sechs interaktiven Typen gemeinsam haben
- Kontaktinfo-Anfragen: nach einer Telefonnummer statt eines Standorts fragen
- WhatsApp-Nachrichten senden: der Request-Envelope, das 202-Modell und sicheres erneutes Versuchen
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