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:

Code example

{
  "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

Field	Bound	Enforced by
latitude	required, -90 to 90, decimal degrees	Bird, at accept (422)
longitude	required, -180 to 180, decimal degrees	Bird, at accept (422)
name	optional, up to 1000 characters	Bird, at accept (422)
address	optional, up to 1000 characters, shown only when name is set	Bird, at accept (422)

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.

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

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Watch the guideConnecting WhatsApp to Bird: from buying a number to a live channel Understand the conceptWhat is the 24-hour customer service window on WhatsApp?Use the toolWhatsApp message builder Explore the capabilityWhatsApp

Try the practice and get an implementation brief