WhatsApp location messages

A location message sends a pin: a point on the map, with an optional name and address underneath it. This is the send side; to ask a contact to share theirs instead, see location requests.

Send a location

Set location.latitude and 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
      }
    }'

The full shape adds name and 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 only displays to the recipient when name is also set. from is required on every service message: a number your workspace owns, not a Bird-managed one.

Limits

WhatsApp's own docs list latitude and longitude as required with no stated numeric range; the ±90/±180 range check and the 1000-character caps on name and address are Bird's own bounds.

Reading an inbound location

A contact sharing their location, unprompted or in reply to a location request, produces an ordinary inbound location message. Nothing on it is guaranteed: a raw pin can arrive with no name and no address at all, and an inbound one can also carry a url linking to the place, which never appears on a location you send. Location isn't a media type, so there's no file to fetch. See Receiving WhatsApp locations for the inbound read in full, the whatsapp.received payload, and what to watch for.

Limits and edge cases

• The customer service window has to be open. A location send is a service message, deliverable only inside an open window; see the hub's customer service window.
• name and address are genuinely optional on read, not optional-with-a-fallback. A raw pin has neither, and address never appears without name. Don't assume a street address accompanies a pair of coordinates.
• This is not the same type as a location request. Location requests are an interactive type that asks the recipient for their own location; this page sends one to them. Don't conflate the two send shapes.
• A tap on a location request comes back as an ordinary inbound location message, not an interactive_reply. An integration that watches only interactive_reply for taps misses this entirely; it has to also watch inbound location.

Next steps

• WhatsApp service messages: the customer service window and the model every service message shares
• Location requests: ask a contact for their location instead of sending one
• Sending WhatsApp messages: the request envelope, the 202 model, and safe retries