Mensagens de localização WhatsApp

Uma mensagem de localização envia um pin: um ponto no mapa, com um nome e endereço opcionais abaixo dele. Esta é a parte de envio; para pedir que um contato compartilhe a localização dele, veja solicitações de localização.

Enviar uma localização

Defina 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
      }
    }'

A forma completa adiciona name e address:

Exemplo de código

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

address só é exibido para o destinatário quando name também está definido. from é obrigatório em toda mensagem de serviço: um número que o seu espaço de trabalho possui, não um gerenciado pelo Bird.

Limites

Campo	Limite	Aplicado por
latitude	obrigatório, -90 a 90, graus decimais	Bird, ao aceitar (422)
longitude	obrigatório, -180 a 180, graus decimais	Bird, ao aceitar (422)
name	opcional, até 1000 caracteres	Bird, ao aceitar (422)
address	opcional, até 1000 caracteres, exibido apenas quando name está definido	Bird, ao aceitar (422)

A documentação do próprio WhatsApp lista latitude e longitude como obrigatórios sem faixa numérica declarada; a verificação de faixa ±90/±180 e os limites de 1000 caracteres em name e address são limites próprios do Bird.

Lendo uma localização recebida

Um contato compartilhando sua localização, espontaneamente ou em resposta a uma solicitação de localização, produz uma mensagem location recebida comum. Nada nela é garantido: um pin bruto pode chegar sem name e sem address, e um recebido também pode trazer um url vinculando ao local, que nunca aparece em uma localização que você envia. Localização não é um tipo de mídia, então não há arquivo para baixar. Veja Recebendo localizações WhatsApp para a leitura completa da mensagem recebida, o payload whatsapp.received e o que observar.

Limites e casos extremos

A janela de atendimento ao cliente precisa estar aberta. Um envio de localização é uma mensagem de serviço, entregável apenas dentro de uma janela aberta; veja a janela de atendimento ao cliente do hub.
name e address são genuinamente opcionais na leitura, não opcionais-com-fallback. Um pin bruto não tem nenhum dos dois, e address nunca aparece sem name. Não assuma que um endereço acompanha um par de coordenadas.
Este não é o mesmo tipo que uma solicitação de localização. Solicitações de localização são um tipo interativo que pede ao destinatário a própria localização; esta página envia uma para ele. Não confunda as duas formas de envio.
Um toque em uma solicitação de localização retorna como uma mensagem location recebida comum, não como um interactive_reply. Uma integração que monitora apenas interactive_reply para toques perde isso completamente; ela precisa também monitorar mensagens recebidas location.

Próximos passos

Mensagens de serviço WhatsApp: a janela de atendimento ao cliente e o modelo que toda mensagem de serviço compartilha
Solicitações de localização: peça a localização de um contato em vez de enviar uma
Enviando mensagens WhatsApp: o envelope de solicitação, o modelo 202 e tentativas seguras de reenvio

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaConnecting WhatsApp to Bird: from buying a number to a live channel Entenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builder Explore a funcionalidadeWhatsApp

Experimente na prática e obtenha um resumo de implementação