Sign inGet started

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);
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