Sign inGet started

Richieste di informazioni di contatto WhatsApp

Una richiesta di informazioni di contatto inserisce un pulsante sotto un messaggio WhatsApp che chiede al destinatario di condividere un numero di telefono. Usala quando ti serve un numero per raggiungere qualcuno, ad esempio per una richiamata o una conferma di prenotazione, anziché un indirizzo salvato. Per una posizione, usa le richieste di posizione.

Inviare una richiesta di informazioni di contatto

Imposta interactive.type su request_contact_info, con un body_text e nient'altro. WhatsApp genera il pulsante stesso, quindi non c'è nulla con cui etichettarlo:
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 è obbligatorio su ogni messaggio di servizio: un numero di proprietà del tuo spazio di lavoro, non uno gestito da Bird. Questo tipo non definisce alcun campo proprio, e lo schema vieta esplicitamente header, footer_text e ogni campo degli altri tipi (buttons, list, cta_url, cards), quindi body_text è l'intero messaggio, con un limite di 1024 caratteri. Meta non dichiara alcun limite di lunghezza del corpo per questo tipo; Bird applica il limite di 1024 caratteri che ogni altro tipo interattivo tranne un menu a lista prevede.
in_reply_to_message_id funziona anche su questo tipo, per citare un messaggio precedente nella stessa conversazione. Consulta la sezione dell'hub citare un messaggio per correlare una risposta per capire come funziona la risoluzione e cosa può sfuggire.

Leggere il contatto condiviso

Un tap non produce un interactive_reply. Arriva come un normale messaggio in ingresso con un array contact_cards:
Esempio di codice
{
  "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 è un array, e un messaggio contacts che non conteneva alcuna scheda viene letto come [] anziché come campo assente. Lo stesso campo trasporta una scheda che invii tu, quindi una scheda che risponde a questa richiesta si distingue tramite origin, non dal campo su cui arriva. Controllare origin è obbligatorio prima di trattare una scheda come risposta alla tua richiesta. origin è contact_request quando la scheda risponde a questa richiesta, o other quando il contatto ha condiviso una scheda spontaneamente, che potrebbe indicare una terza persona e non il contatto stesso. Un tap contiene solo phone_numbers[].{phone_number, type} e omette vcard; l'oggetto contatto completo, con name, org, birthday e il resto, arriva solo su origin: "other". Questa risposta è visibile tramite l'elenco messaggi o GET /v1/whatsapp/messages/{id}; consulta la sezione dell'hub leggere una risposta per il percorso completo.

Correlare la risposta con la domanda

A differenza di una richiesta di posizione, Meta non inserisce alcun context nella risposta di questo tipo, quindi in_reply_to_message_id è omesso anziché risolto. Correla su from più un invio recente da parte tua, oppure accetta che non è possibile. Due richieste in sospeso allo stesso contatto sono indistinguibili: nulla nella risposta indica a quale richiesta si riferisce, quindi uno spazio di lavoro che invia una seconda richiesta di informazioni di contatto prima che la prima abbia ricevuto risposta non può sapere quale scheda risponde a quale.
Questo è il contrasto voluto con le richieste di posizione: la risposta di quel tipo contiene il context di Meta, quindi in_reply_to_message_id viene risolto e il meccanismo dell'hub citare un messaggio per correlare una risposta collega automaticamente la risposta. La risposta a una richiesta di informazioni di contatto non ha alcun meccanismo di questo tipo su cui appoggiarsi.

Richiedere tramite un template

Il messaggio interattivo request_contact_info è la controparte in formato libero del pulsante template REQUEST_CONTACT_INFO, che richiede la stessa scheda contatto ma può raggiungere un destinatario la cui finestra di servizio clienti è chiusa. Usa il messaggio interattivo quando il destinatario ti ha scritto di recente e vuoi formulare la richiesta per questa conversazione; usa il pulsante template quando la finestra è chiusa o quando la richiesta accompagna un messaggio che invii già come template. Consulta template WhatsApp per l'invio con un template.

Aspetti da tenere d'occhio

  • La finestra di servizio clienti deve essere aperta. Una richiesta di informazioni di contatto è un messaggio di servizio, consegnabile solo all'interno di una finestra aperta; consulta la sezione dell'hub finestra di servizio clienti. Il controllo della finestra fallisce in modo permissivo, quindi un 202 non è prova che la finestra fosse effettivamente aperta al momento dell'invio.
  • from deve essere un numero di proprietà del tuo spazio di lavoro, e la finestra che deve essere aperta è associata a quel numero, non al tuo spazio di lavoro nel suo insieme.
  • La risposta non può essere collegata alla richiesta tramite id. L'assenza di context lato Meta significa che in_reply_to_message_id è omesso nella risposta; correla su from più un invio recente da parte tua.
  • Un rifiuto è silenzioso. WhatsApp mostra al destinatario una schermata di condivisione, e chiuderla non produce alcun messaggio né webhook. L'assenza di un messaggio contact_cards è l'unico segnale, quindi qualsiasi flusso che attende una risposta ha bisogno di un proprio timeout anziché di un evento di rifiuto da monitorare.
  • Nessun header, nessun footer e nessuna etichetta per il pulsante. Lo schema vieta esplicitamente header e footer_text su questo tipo, e non c'è alcun campo per etichettare il pulsante. Tutto ciò che il destinatario legge deve essere in body_text.
  • Il numero condiviso non è garantito essere quello da cui il contatto scrive. Meta avvisa che l'ID di un utente e il numero di telefono potrebbero non corrispondere sempre, quindi non dare per scontato che il numero condiviso sia uguale a from.phone_number. Non è nemmeno garantito che sia in formato E.164: Bird lo normalizza dove è possibile analizzarlo e lo passa così com'è dove non lo è.
  • La risposta è un messaggio contact_cards, non un interactive_reply. Un'integrazione che monitora solo interactive_reply per un tap non intercetterà questo tipo, e lo stesso vale per una che monitora solo i messaggi in ingresso location per l'altro tipo di richiesta.
Tutto ciò che lo schema può esprimere qui, un body_text troppo lungo, un header, un footer_text o uno qualsiasi tra buttons, list, cta_url, cards, è un semplice errore di validazione della richiesta senza codice di catalogo. Una citazione che non si risolve fa fallire la richiesta prima che qualsiasi cosa venga creata o addebitata: 404 E15071 quando l'id non corrisponde a nessun messaggio di questo spazio di lavoro, 422 E15072 quando corrisponde a uno che non può essere citato. Consulta la sezione dell'hub errori per la tabella completa degli errori interattivi e Invio di messaggi WhatsApp per gli errori che qualsiasi invio WhatsApp può incontrare.

Prossimi passi