Mensajes de ubicación de WhatsApp

Un mensaje de ubicación envía un pin: un punto en el mapa, con un nombre y una dirección opcionales debajo. Esta es la parte de envío; para pedirle a un contacto que comparta su ubicación, consulta solicitudes de ubicación.

Enviar una ubicación

Establece location.latitude y 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

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 añade name y address:

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

address solo se muestra al destinatario cuando name también está establecido. from es obligatorio en cada mensaje de servicio: un número que pertenece a tu espacio de trabajo, no uno gestionado por Bird.

Límites

La documentación propia de WhatsApp indica latitude y longitude como obligatorios sin un rango numérico declarado; la verificación de rango ±90/±180 y los límites de 1000 caracteres en name y address son restricciones propias de Bird.

Leer una ubicación entrante

Un contacto que comparte su ubicación, de forma espontánea o en respuesta a una solicitud de ubicación, genera un mensaje entrante ordinario de location. Nada en él está garantizado: un pin sin procesar puede llegar sin name ni address, y uno entrante también puede incluir un url que enlaza al lugar, algo que nunca aparece en una ubicación que tú envías. La ubicación no es un tipo de medio, así que no hay archivo que descargar. Consulta Recibir ubicaciones de WhatsApp para la lectura entrante completa, el payload de whatsapp.received y qué tener en cuenta.

Límites y casos especiales

• La ventana de servicio al cliente debe estar abierta. Un envío de ubicación es un mensaje de servicio, entregable solo dentro de una ventana abierta; consulta la ventana de servicio al cliente del hub.
• name y address son genuinamente opcionales en lectura, no opcionales con respaldo. Un pin sin procesar no tiene ninguno de los dos, y address nunca aparece sin name. No asumas que una dirección postal acompaña a un par de coordenadas.
• Este no es el mismo tipo que una solicitud de ubicación. Las solicitudes de ubicación son un tipo interactivo que pide al destinatario su propia ubicación; esta página envía una hacia ellos. No confundas las dos formas de envío.
• Un toque en una solicitud de ubicación regresa como un mensaje entrante ordinario de location, no como un interactive_reply. Una integración que solo observa interactive_reply para toques pierde esto por completo; también debe observar mensajes entrantes de location.

Próximos pasos

• Mensajes de servicio de WhatsApp: la ventana de servicio al cliente y el modelo que comparten todos los mensajes de servicio
• Solicitudes de ubicación: pide a un contacto su ubicación en lugar de enviarle una
• Enviar mensajes de WhatsApp: la estructura de la solicitud, el modelo de 202 y reintentos seguros