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 \
  --to +16505551234 \
  --from +13124495648 \
  --latitude 37.7793 \
  --longitude -122.4193

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:

Ejemplo 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 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.

Ejemplo de código

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

An inbound location can also carry a url linking to the place, usually only on a business location; it never appears on a location you send. Location isn't a media type, so there's no file to fetch and no 30-day retention window. See Receiving WhatsApp messages for the message list, the API, and the webhook path.

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
How sending works: the request envelope, the 202 model, and safe retries

WhatsApp location messages

Send a location

Limits

Reading an inbound location

Limits and edge cases

Next steps