Documentatie
Sign inGet started
Aan de slag
Gidsen
API Reference
SDK's
CLI
Kennisbank
Changelog

WhatsApp contact-info-verzoeken

Een contact-info-verzoek plaatst één knop onder een WhatsApp-bericht die de ontvanger vraagt een telefoonnummer te delen. Gebruik het als je een nummer nodig hebt om iemand op te bereiken, zoals voor een terugbelverzoek of een boekingsbevestiging, en niet voor een opgeslagen adres. Gebruik voor een locatie in plaats daarvan locatieverzoeken.

Een contact-info-verzoek versturen

Stel interactive.type in op request_contact_info, met een body_text en verder niets. WhatsApp rendert de knop zelf, dus er is niets om als label te gebruiken:
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 is verplicht bij elk servicebericht: een nummer dat je werkruimte bezit, niet een door Bird beheerd nummer. Dit type definieert geen eigen veld, en het schema verbiedt een header, een footer_text en elk veld van andere types (buttons, list, cta_url, cards) expliciet, dus body_text is het volledige bericht, beperkt tot 1024 tekens. Meta specificeert geen limiet voor de body-lengte van dit type; Bird past de limiet van 1024 tekens toe die elk ander interactief type behalve een lijstmenu heeft.
in_reply_to_message_id werkt ook bij dit type, om een eerder bericht in hetzelfde gesprek te citeren. Zie in de hub een bericht citeren om een antwoord te correleren voor hoe resolutie werkt en wat het kan missen.

Het gedeelde contact lezen

Een tik levert geen interactive_reply op. Het komt binnen als een gewoon inkomend bericht met een contact_cards-array:
Codevoorbeeld
{
  "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 is een array, en een contacts-bericht dat geen kaart bevatte wordt teruggelezen als [] in plaats van als een afwezig veld. Hetzelfde veld bevat een kaart die je verstuurt, dus een kaart die op dit verzoek antwoordt wordt onderscheiden door origin, niet door het veld waarop het binnenkomt. Controleer origin voordat je een kaart als je antwoord behandelt. origin is contact_request als de kaart op dit verzoek antwoordt, of other als het contact ongevraagd een kaart deelde, die mogelijk een derde partij betreft en helemaal niet het contact zelf. Een tik bevat alleen phone_numbers[].{phone_number, type} en laat vcard weg; het volledige contactobject, met name, org, birthday en de rest, komt alleen binnen via origin: "other". Je ziet dit antwoord via de berichtenlijst of GET /v1/whatsapp/messages/{id}; zie in de hub een antwoord lezen voor het volledige pad.

Het antwoord correleren met de vraag

Anders dan bij een locatieverzoek plaatst Meta geen context op het antwoord van dit type, dus in_reply_to_message_id wordt weggelaten in plaats van opgelost. Correleer op from in combinatie met een recent eigen verzonden bericht, of accepteer dat het niet kan. Twee openstaande verzoeken aan hetzelfde contact zijn niet te onderscheiden: niets op het antwoord vermeldt op welk verzoek het reageert, dus een werkruimte die een tweede contact-info-verzoek stuurt voordat het eerste is beantwoord, kan niet bepalen welke kaart bij welk verzoek hoort.
Dit is het bewuste verschil met locatieverzoeken: het antwoord van dat type bevat Meta's eigen context, dus in_reply_to_message_id wordt opgelost en het mechanisme een bericht citeren om een antwoord te correleren in de hub koppelt het antwoord automatisch terug. Het antwoord op een contact-info-verzoek heeft geen dergelijk mechanisme om op te steunen.

In plaats daarvan vragen via een template

Het interactieve request_contact_info-bericht is het vrije-vorm-equivalent van de REQUEST_CONTACT_INFO-templateknop, die dezelfde contactkaart opvraagt maar ook een ontvanger kan bereiken van wie het klantenservicevenster gesloten is. Gebruik het interactieve bericht als de ontvanger je onlangs een bericht heeft gestuurd en je het verzoek wilt formuleren voor dit gesprek; gebruik de templateknop als het venster gesloten is, of als het verzoek meerijdt op een bericht dat je al als template verstuurt. Zie WhatsApp-templates voor het versturen met een template.

Aandachtspunten

  • Het klantenservicevenster moet open zijn. Een contact-info-verzoek is een servicebericht dat alleen binnen een open venster kan worden afgeleverd; zie in de hub klantenservicevenster. De venstercontrole faalt open, dus een 202 is geen bewijs dat het venster daadwerkelijk open was op het moment van verzenden.
  • from moet een nummer zijn dat je werkruimte bezit, en het venster dat open moet zijn is gekoppeld aan dat nummer, niet aan je werkruimte als geheel.
  • Het antwoord kan niet op id aan het verzoek worden gekoppeld. Geen context aan Meta's kant betekent dat in_reply_to_message_id op het antwoord wordt weggelaten; correleer op from in combinatie met een recent eigen verzonden bericht.
  • Een weigering is stil. WhatsApp toont de ontvanger een deelscherm, en het wegklikken ervan produceert geen bericht en geen webhook. De afwezigheid van een contact_cards-bericht is het enige signaal, dus elke flow die op een antwoord wacht heeft een eigen timeout nodig in plaats van een weigeringsevent om op te letten.
  • Geen header, geen footer en geen knoplabel. Het schema verbiedt een header en footer_text bij dit type expliciet, en er is geen veld om de knop mee te labelen. Alles wat de ontvanger leest moet in body_text staan.
  • Het gedeelde nummer is niet gegarandeerd het nummer waarmee het contact chat. Meta waarschuwt dat de ID en het telefoonnummer van een gebruiker niet altijd overeen hoeven te komen, dus neem niet aan dat het gedeelde nummer gelijk is aan from.phone_number. Het is ook niet gegarandeerd E.164: Bird normaliseert het waar het te parsen is en geeft het anders ongewijzigd door.
  • Het antwoord is een contact_cards-bericht, geen interactive_reply. Een integratie die alleen interactive_reply controleert op een tik mist dit type volledig, net als een integratie die alleen inkomende location controleert voor het andere verzoektype.
Alles wat het schema hier kan uitdrukken, een te lange body_text, een header, een footer_text, of elk van buttons, list, cta_url, cards, is een gewone validatiefout op het verzoek zonder cataloguscode. Een citaat dat niet opgelost kan worden laat het verzoek falen voordat er iets wordt aangemaakt of in rekening gebracht: 404 E15071 als de id geen bericht noemt dat deze werkruimte heeft, 422 E15072 als het er een noemt dat niet geciteerd kan worden. Zie in de hub fouten voor de volledige interactieve fouttabel en WhatsApp-berichten versturen voor de fouten die elk WhatsApp-verzending kan opleveren.

Vervolgstappen

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Bekijk de gidsConnecting WhatsApp to Bird: from buying a number to a live channelBegrijp het conceptWhat is the 24-hour customer service window on WhatsApp?Gebruik de toolWhatsApp message builderOntdek de mogelijkheidWhatsApp
Probeer de oefening en ontvang een implementatieoverzicht