Sign inGet started

Richieste di posizione WhatsApp

Una richiesta di posizione aggiunge un pulsante sotto un messaggio WhatsApp che chiede al destinatario di condividere dove si trova. Usala quando ti serve una posizione attuale, come un punto di ritiro, anziché un indirizzo salvato. Per un numero di telefono, usa le richieste di informazioni di contatto.

Inviare una richiesta di posizione

Imposta interactive.type su location_request_message, con un body_text e nient'altro. WhatsApp renderizza il pulsante stesso, quindi non c'è nulla con cui etichettarlo:
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 è obbligatorio su ogni messaggio di servizio: un numero di proprietà del tuo spazio di lavoro, non uno gestito da Bird. Questo tipo non dichiara campi propri, e lo schema vieta esplicitamente un header, un 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.
in_reply_to_message_id funziona anche su questo tipo, per citare un messaggio precedente nella stessa conversazione. Consulta nella guida citare un messaggio per correlare una risposta per capire come funziona la risoluzione e cosa può non trovare.

Leggere la posizione condivisa

Un tap non produce un interactive_reply. Arriva come un normale messaggio location in entrata, con la stessa struttura che produrrebbe un contatto che condivide la propria posizione spontaneamente, quindi un'integrazione che già legge le posizioni in entrata non ha bisogno di un nuovo ramo per questo tipo:
Esempio di codice
{
  "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"
}
Nessuno dei campi di location è obbligatorio: latitude e longitude sono di solito entrambi presenti, ma name è assente quando il destinatario ha condiviso un segnaposto semplice, address compare solo quando è impostato anche name, e url compare solo sulle posizioni di attività commerciali che il client del destinatario ha incluso. Scrivi codice difensivo anziché dare per scontato che un indirizzo stradale accompagni il segnaposto. Puoi vedere questa risposta tramite la lista dei messaggi o GET /v1/whatsapp/messages/{id}; consulta nella guida leggere una risposta per il percorso completo.

Correlare la risposta con la richiesta

Meta imposta un context sulla risposta di questo tipo che indica la richiesta a cui risponde, quindi il messaggio in entrata contiene in_reply_to_message_id e non ti serve uno schema di correlazione personalizzato:
Esempio di codice
{
  "direction": "inbound",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "location": { "latitude": 37.7793, "longitude": -122.4193 }
}
Consulta citare un messaggio per correlare una risposta per capire come funziona la risoluzione e come si presenta un mancato riscontro.
Questo è il contrasto voluto con le richieste di informazioni di contatto: la risposta di quel tipo non contiene affatto un context, quindi il suo in_reply_to_message_id non si risolve mai e la correlazione ricade su from più il timing. La risposta a una richiesta di posizione si risolve, quindi in_reply_to_message_id è il modo affidabile per ricondurre la posizione condivisa alla richiesta che l'ha generata.

Aspetti da tenere d'occhio

  • La finestra di assistenza clienti deve essere aperta. Una richiesta di posizione è un messaggio di servizio, recapitabile solo all'interno di una finestra aperta; consulta nella guida la finestra di assistenza 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. Ometterlo, o indicare un numero che non è un mittente connesso, viene rifiutato prima che l'invio venga creato.
  • Nessuna risposta è garantita. Il destinatario può chiudere la schermata di condivisione della posizione, ignorare del tutto il messaggio o digitare un indirizzo come testo libero, che arriva come un normale messaggio di testo in entrata senza alcun location. Meta non documenta alcun segnale per una condivisione rifiutata o ignorata, quindi tratta la richiesta come fire-and-forget e gestisci un timeout dal tuo lato anziché attendere una risposta che potrebbe non arrivare mai.
  • Un segnaposto condiviso può contenere solo coordinate. Il client del destinatario decide se allegare un nome e un indirizzo; un segnaposto semplice non ha nessuno dei due, quindi non dare per scontato che l'uno accompagni l'altro.
  • Nessun header, nessun footer e nessun campo proprio. Lo schema vieta esplicitamente un header e un footer_text su questo tipo, e non c'è un campo per etichettare il pulsante. Eventuali note aggiuntive devono stare dentro body_text.
  • La risposta è un messaggio location, non un interactive_reply. Un'integrazione che osserva solo interactive_reply per un tap non intercetterà questo tipo; osserva invece i messaggi location in entrata.
Tutto ciò che lo schema può esprimere qui, un body_text troppo lungo, un header, un footer_text, o 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 indica un messaggio non presente in questo spazio di lavoro, 422 E15072 quando indica un messaggio che non può essere citato. Consulta nella guida gli errori per la tabella interattiva completa degli errori e Invio di messaggi WhatsApp per gli errori che qualsiasi invio WhatsApp può generare.

Prossimi passi