Messaggi di posizione WhatsApp

Un messaggio di posizione invia un segnaposto: un punto sulla mappa, con un nome e un indirizzo facoltativi sotto. Questa è la parte di invio; per chiedere a un contatto di condividere la propria posizione, vedi richieste di posizione.

Inviare una posizione

Imposta location.latitude e location.longitude:

const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  location: { latitude: 37.7793, longitude: -122.4193 },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+16505551234",
    from_="+13124495648",
    location={"latitude": 37.7793, "longitude": -122.4193},
)
print(msg.id, msg.status)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
		To:   "+16505551234",
		From: "+13124495648",
		Location: &bird.WhatsAppLocationSend{Latitude: 37.7793, Longitude: -122.4193},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$location = (new WhatsAppMessageSendRequestLocation())
    ->setLatitude(37.7793)
    ->setLongitude(-122.4193);
$message = $bird->whatsapp->send(
    to: '+16505551234',
    from: '+13124495648',
    location: $location,
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --from +13124495648 \
  --latitude 37.7793 \
  --longitude -122.4193 \
  --to +16505551234

{
  "name": "whatsapp_send",
  "arguments": {
    "from": "+13124495648",
    "location": {
      "latitude": 37.7793,
      "longitude": -122.4193
    },
    "to": "+16505551234"
  }
}

curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "to": "+16505551234",
      "from": "+13124495648",
      "location": {
        "latitude": 37.7793,
        "longitude": -122.4193
      }
    }'

La forma completa aggiunge name e address:

Esempio di codice

{
  "to": "+16505551234",
  "from": "+13124495648",
  "location": {
    "latitude": 37.7793,
    "longitude": -122.4193,
    "name": "Ferry Building Pickup",
    "address": "1 Market St, San Francisco, CA 94105"
  }
}

address viene mostrato al destinatario solo quando è impostato anche name. from è obbligatorio in ogni messaggio di servizio: un numero di proprietà del tuo spazio di lavoro, non uno gestito da Bird.

Limiti

Campo	Vincolo	Applicato da
latitude	obbligatorio, da -90 a 90, gradi decimali	Bird, all'accettazione (422)
longitude	obbligatorio, da -180 a 180, gradi decimali	Bird, all'accettazione (422)
name	facoltativo, fino a 1000 caratteri	Bird, all'accettazione (422)
address	facoltativo, fino a 1000 caratteri, mostrato solo quando name è impostato	Bird, all'accettazione (422)

La documentazione di WhatsApp elenca latitude e longitude come obbligatori senza un intervallo numerico dichiarato; il controllo dell'intervallo ±90/±180 e il limite di 1000 caratteri su name e address sono vincoli propri di Bird.

Leggere una posizione in entrata

Quando un contatto condivide la propria posizione, spontaneamente o in risposta a una richiesta di posizione, il risultato è un normale messaggio location in entrata. Nulla è garantito: un segnaposto grezzo può arrivare senza name e senza address, e uno in entrata può anche contenere un url che rimanda al luogo, cosa che non compare mai in una posizione inviata. La posizione non è un tipo media, quindi non c'è un file da scaricare. Vedi Ricezione delle posizioni WhatsApp per la lettura completa in entrata, il payload whatsapp.received e a cosa prestare attenzione.

Limiti e casi particolari

La finestra del servizio clienti deve essere aperta. L'invio di una posizione è un messaggio di servizio, recapitabile solo all'interno di una finestra aperta; vedi la finestra del servizio clienti dell'hub.
name e address sono realmente facoltativi in lettura, non facoltativi con un valore di riserva. Un segnaposto grezzo non ha nessuno dei due, e address non compare mai senza name. Non dare per scontato che un indirizzo stradale accompagni una coppia di coordinate.
Questo non è lo stesso tipo di una richiesta di posizione. Le richieste di posizione sono un tipo interattivo che chiede al destinatario la propria posizione; questa pagina ne invia una a loro. Non confondere le due forme di invio.
Un tap su una richiesta di posizione ritorna come un normale messaggio location in entrata, non come un interactive_reply. Un'integrazione che controlla solo interactive_reply per i tap lo perde del tutto; deve anche controllare i messaggi location in entrata.

Prossimi passi

Messaggi di servizio WhatsApp: la finestra del servizio clienti e il modello condiviso da ogni messaggio di servizio
Richieste di posizione: chiedere a un contatto la sua posizione invece di inviarne una
Invio di messaggi WhatsApp: la struttura della richiesta, il modello 202 e le strategie sicure per riprovare

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaConnecting WhatsApp to Bird: from buying a number to a live channel Comprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builder Esplora la funzionalitàWhatsApp

Prova l'esercitazione e ottieni un brief di implementazione