Messages de localisation WhatsApp

Un message de localisation envoie un repère : un point sur la carte, avec un nom et une adresse facultatifs en dessous. Ceci concerne l'envoi ; pour demander à un contact de partager sa propre localisation, consultez les demandes de localisation.

Envoyer une localisation

Définissez location.latitude et 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 forme complète ajoute name et address :

Exemple de code

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

address ne s'affiche pour le destinataire que lorsque name est également défini. from est requis sur chaque message de service : un numéro appartenant à votre espace de travail, pas un numéro géré par Bird.

Limites

Champ	Borne	Appliquée par
latitude	requis, -90 à 90, degrés décimaux	Bird, à l'acceptation (422)
longitude	requis, -180 à 180, degrés décimaux	Bird, à l'acceptation (422)
name	facultatif, jusqu'à 1000 caractères	Bird, à l'acceptation (422)
address	facultatif, jusqu'à 1000 caractères, affiché uniquement quand name est défini	Bird, à l'acceptation (422)

La documentation de WhatsApp indique latitude et longitude comme requis sans plage numérique précisée ; la vérification de plage ±90/±180 et les limites de 1000 caractères sur name et address sont les bornes propres à Bird.

Lire une localisation entrante

Un contact qui partage sa localisation, spontanément ou en réponse à une demande de localisation, produit un message entrant location ordinaire. Rien n'y est garanti : un repère brut peut arriver sans name ni address, et un repère entrant peut aussi contenir un url pointant vers le lieu, qui n'apparaît jamais sur une localisation que vous envoyez. La localisation n'est pas un type de média, il n'y a donc pas de fichier à récupérer. Consultez Recevoir des localisations WhatsApp pour la lecture entrante complète, le payload whatsapp.received, et les points à surveiller.

Limites et cas particuliers

La fenêtre de service client doit être ouverte. Un envoi de localisation est un message de service, livrable uniquement dans une fenêtre ouverte ; consultez la fenêtre de service client du hub.
name et address sont réellement facultatifs en lecture, pas facultatifs avec une valeur de repli. Un repère brut ne contient ni l'un ni l'autre, et address n'apparaît jamais sans name. Ne supposez pas qu'une adresse postale accompagne une paire de coordonnées.
Ce n'est pas le même type qu'une demande de localisation. Les demandes de localisation sont un type interactif qui demande au destinataire sa propre localisation ; cette page en envoie une vers lui. Ne confondez pas les deux formes d'envoi.
Un appui sur une demande de localisation revient sous forme de message entrant location ordinaire, pas d'un interactive_reply. Une intégration qui surveille uniquement interactive_reply pour les appuis passe complètement à côté ; elle doit aussi surveiller les messages entrants location.

Étapes suivantes

Messages de service WhatsApp : la fenêtre de service client et le modèle commun à tous les messages de service
Demandes de localisation : demander à un contact sa localisation au lieu d'en envoyer une
Envoyer des messages WhatsApp : l'enveloppe de requête, le modèle 202, et les réessais sûrs

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Regarder le guideConnecting WhatsApp to Bird: from buying a number to a live channel Comprendre le conceptWhat is the 24-hour customer service window on WhatsApp?Utiliser l'outilWhatsApp message builder Explorer la fonctionnalitéWhatsApp

Essayez la pratique et obtenez un guide d'implémentation