Sign inGet started

WhatsApp-Kontaktinfo-Anfragen

Eine Kontaktinfo-Anfrage platziert einen Button unter einer WhatsApp-Nachricht, der den Empfänger bittet, eine Telefonnummer zu teilen. Verwenden Sie sie, wenn Sie eine Nummer brauchen, um jemanden zu erreichen, etwa für einen Rückruf oder eine Buchungsbestätigung, nicht für eine gespeicherte Adresse. Für einen Standort verwenden Sie stattdessen Standortanfragen.

Eine Kontaktinfo-Anfrage senden

Setzen Sie interactive.type auf request_contact_info, mit einem body_text und nichts anderem. WhatsApp rendert den Button selbst, daher gibt es kein Feld, um ihn zu beschriften:
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  interactive: {
    type: "request_contact_info",
    body_text:
      "To confirm your booking we need a number to reach you on. Tap below to share yours.",
  },
});
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 eines anderen Typs (buttons, list, cta_url, cards) ausdrücklich, sodass body_text die gesamte Nachricht ist, begrenzt auf 1024 Zeichen. Meta nennt für diesen Typ kein Body-Längenlimit; Bird wendet die 1024-Zeichen-Grenze an, die jeder andere interaktive Typ außer einem Listenmenü trägt.
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 die Auflösungslogik und deren Grenzen.

Den geteilten Kontakt auslesen

Ein Tippen erzeugt kein interactive_reply. Es kommt als gewöhnliche eingehende Nachricht mit einem contact_cards-Array an:
Codebeispiel
{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+16505551234", "bsuid": "US.13491208655302741918" },
  "to": { "phone_number": "+13124495648" },
  "status": "received",
  "contact_cards": [
    {
      "origin": "contact_request",
      "phone_numbers": [{ "phone_number": "+14155550829", "type": "cell" }]
    }
  ],
  "created_at": "2026-08-26T10:00:00Z"
}
contact_cards ist ein Array, und eine contacts-Nachricht ohne Karte wird als [] zurückgegeben, nicht als fehlendes Feld. Dasselbe Feld trägt auch eine von Ihnen gesendete Karte, daher wird eine Karte, die auf diese Anfrage antwortet, durch origin unterschieden, nicht durch das Feld, auf dem sie ankommt. Die Prüfung von origin ist zwingend, bevor Sie eine Karte als Ihre Antwort behandeln. origin ist contact_request, wenn die Karte auf diese Anfrage antwortet, oder other, wenn der Kontakt eine Karte unaufgefordert geteilt hat, die möglicherweise einen Dritten benennt und gar nicht den Kontakt selbst. Ein Tippen trägt nur phone_numbers[].{phone_number, type} und lässt vcard weg; das vollständige Kontaktobjekt mit name, org, birthday und den übrigen Feldern kommt nur über origin: "other" an. 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

Anders als bei einer Standortanfrage setzt Meta kein context auf die Antwort dieses Typs, sodass in_reply_to_message_id weggelassen statt aufgelöst wird. Ordnen Sie über from plus einen kürzlich eigenen Versand zu, oder akzeptieren Sie, dass es nicht möglich ist. Zwei ausstehende Anfragen an denselben Kontakt sind nicht unterscheidbar: Nichts an der Antwort benennt, welche Anfrage sie beantwortet, sodass ein Workspace, der eine zweite Kontaktinfo-Anfrage sendet, bevor die erste beantwortet ist, nicht feststellen kann, welche Karte auf welche Anfrage antwortet.
Das ist der bewusste Unterschied zu Standortanfragen: Die Antwort dieses Typs trägt Metas eigenen context, sodass in_reply_to_message_id aufgelöst wird und der Hub-Mechanismus Eine Nachricht zitieren, um eine Antwort zuzuordnen die Antwort automatisch zuordnet. Die Antwort einer Kontaktinfo-Anfrage hat keinen solchen Mechanismus.

Stattdessen in einem Template anfragen

Die interaktive request_contact_info-Nachricht ist das Freitext-Gegenstück zum REQUEST_CONTACT_INFO-Template-Button, der dieselbe Kontaktkarte anfordert, aber einen Empfänger erreichen kann, dessen Kundenservice-Fenster geschlossen ist. Verwenden Sie die interaktive Nachricht, wenn der Empfänger Ihnen kürzlich geschrieben hat und Sie die Anfrage auf diese Konversation zuschneiden möchten; verwenden Sie den Template-Button, wenn das Fenster geschlossen ist oder die Anfrage auf einer Nachricht mitläuft, die Sie bereits als Template senden. Siehe WhatsApp-Templates für den Versand mit einem Template.

Worauf Sie achten sollten

  • Das Kundenservice-Fenster muss offen sein. Eine Kontaktinfo-Anfrage 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 dafür ist, dass das Fenster beim Versand tatsächlich offen war.
  • from muss eine Nummer sein, die Ihr Workspace besitzt, und das Fenster, das offen sein muss, ist an diese Nummer gebunden, nicht an Ihren Workspace insgesamt.
  • Die Antwort kann der Anfrage nicht per ID zugeordnet werden. Kein context auf Metas Seite bedeutet, dass in_reply_to_message_id in der Antwort weggelassen wird; ordnen Sie über from plus einen kürzlich eigenen Versand zu.
  • Eine Ablehnung ist stumm. WhatsApp zeigt dem Empfänger ein Freigabeblatt, und dessen Verwerfen erzeugt weder eine Nachricht noch einen Webhook. Das Ausbleiben einer contact_cards-Nachricht ist das einzige Signal, daher braucht jeder Ablauf, der auf eine Antwort wartet, ein eigenes Timeout statt eines Ablehnungsereignisses.
  • Kein Header, kein Footer und kein Button-Label. Das Schema verbietet header und footer_text bei diesem Typ ausdrücklich, und es gibt kein Feld, um den Button zu beschriften. Alles, was der Empfänger liest, muss in body_text stehen.
  • Die mitgeteilte Nummer ist nicht garantiert die, von der der Kontakt chattet. Meta warnt, dass die ID eines Nutzers und seine Telefonnummer nicht immer übereinstimmen müssen. Gehen Sie also nicht davon aus, dass die geteilte Nummer gleich from.phone_number ist. Sie ist auch nicht garantiert E.164-konform: Bird normalisiert sie, wo sie parsebar ist, und gibt sie andernfalls unverändert weiter.
  • Die Antwort ist eine contact_cards-Nachricht, kein interactive_reply. Eine Integration, die nur interactive_reply auf ein Tippen überwacht, verpasst diesen Typ vollständig, ebenso eine, die nur eingehende location für den anderen Anfragetyp überwacht.
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 sich nicht auflöst, lässt den Request fehlschlagen, bevor etwas erstellt oder berechnet wird: 404 E15071, wenn die ID keine Nachricht benennt, die dieser Workspace besitzt, 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