Skip to content

Location Message

Also called: WhatsApp location pin · Map pin message · Static location · type: location

A WhatsApp message carrying a map pin with latitude, longitude and an optional name and address, used for store locations and delivery points.

Reviewed

What is a location message?

A location message is a WhatsApp message that shows a single pin on a small map, with an optional place name and address beneath it. Tapping it opens the customer's maps app at that point, ready for directions. It is one of the core WhatsApp Message Types: businesses use it to say "here we are" (a store, a clinic, an exam centre, a pickup counter), and customers use it to say "here I am" when they share a pin with a business.

On the WhatsApp Cloud API you send one with type: location and a location object holding latitude and longitude in decimal degrees, plus optional name and address. Meta's examples pass the coordinates as strings in the request, while inbound webhooks deliver them as numbers. When a customer sends a pin, the Messages Webhook carries a message of type: location with latitude and longitude, and only if they picked a named place, name, address and sometimes a url for business locations.

The pin is static: one point at one moment. That sets it apart from a Location Request Message, the asking side, whose Send location button invites the customer to share their position, and from an Address Message, which collects a typed postal address and is available to businesses in India messaging customers in India. A location message is free-form, so it needs an open customer service window; to put a map in a business-initiated message, use a utility or marketing template with a location Template Header.

Key takeaways

  • A location message carries one map pin (latitude, longitude, optional name and address) that opens in the customer's maps app.
  • Send it with type: location; coordinates are decimal degrees, and a name and address make the pin far more useful.
  • Pins customers share arrive as type: location messages, with coordinates as numbers and a name and address only when they chose a place.
  • It shows a fixed point; to ask where a customer is, send a location request message instead.
  • As a free-form message it needs an open 24-hour window; utility and marketing templates can carry a location header.

See InfiQ pricing

Interactive stop

Read a pin a customer just shared

8 / 8
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "914412345678",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Karthik"
                },
                "wa_id": "919840012345"
              }
            ],
            "messages": [
              {
                "from": "919840012345",
                "id": "wamid.HBgMOTE5ODQwMDEyMzQ1FQIAEhgUM0E3QjRDOEQ5RTBGMTIzNDU2NzgA",
                "timestamp": "1760861400",
                "type": "location",
                "location": {
                  "latitude": 12.98157,
                  "longitude": 80.21802,
                  "name": "Velachery bus terminus",
                  "address": "Velachery Main Road, Chennai 600042"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}
A location webhook from a customer in Chennai. Step through the fields: the type, the coordinates (numbers here, strings when you send) and the optional place name and address.

Field 8: entry.0.changes.0.value.metadata.phone_number_id — Your number that received the pin; reply from the same one.

How does a location message work?

  1. Keep accurate coordinates

    Store each branch's latitude and longitude once, checked on a map, with five or six decimal places. Five decimals is roughly 1 metre; two decimals can be a kilometre off.

  2. Add a name and address

    Use the name on the signboard and an address with a landmark and PIN code, so the pin still makes sense before the map loads.

  3. Send it while the window is open

    POST type: location to /{PHONE_NUMBER_ID}/messages within 24 hours of the customer's last message. Outside the window, use a template with a location header.

  4. Parse shared pins

    Read location.latitude and location.longitude from inbound messages, range-check them, and treat name and address as optional extras.

  5. Act on the point

    Find the nearest branch, check whether a delivery address falls in your service zone, or attach the pin to the order so a rider can navigate to it.

Example: The nearest branch in Chennai

A Chennai hardware chain's bot gets "Where is your nearest store?" and asks the customer to share a location. Her pin from Velachery arrives as a location webhook; the bot calculates distances to the chain's 14 branches and replies with a location message for the closest one, named Velachery branch, with an address that includes the landmark and PIN code, followed by a text with opening hours and the branch phone number. When she orders a delivery later, the same shared pin is saved with the order for the driver.

— The nearest branch in Chennai

A location message in code

curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/messages" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "919840012345",
    "type": "location",
    "location": {
      "latitude": "12.97910",
      "longitude": "80.21840",
      "name": "Velachery branch",
      "address": "100 Feet Road, near the bus terminus, Velachery, Chennai 600042"
    }
  }'

Illustrative coordinates. Name and address are optional but make the pin readable before the map loads.

A location message: key facts and limits

Message type
type: location
Required
latitude and longitude, in decimal degrees
Optional
name and address
Inbound extras
name and address only if a place was chosen; url for some business places
Precision
5 decimal places ≈ 1 m; 2 decimals ≈ 1 km
When
Inside the 24-hour customer service window
Outside the window
Template with a location header (utility or marketing)

Why does a location message matter?

Addresses in India are often approximate: "behind the temple, second gate, blue building". A pin removes the ambiguity. Customers get turn-by-turn directions to the right branch rather than the one with a similar name, and riders, technicians and field agents get coordinates instead of a paragraph. For store-locator bots, answering with the nearest branch as a location message is often the single most useful reply.

Common mistakes with a location message

  • Swapping latitude and longitude

    In India latitude runs roughly from 8 to 37 and longitude from 68 to 97. A range check on every send and every inbound pin catches a swapped pair before a customer is sent into the sea.

  • Too few decimal places

    Coordinates rounded to two decimals can be a kilometre away from the door. Keep five or six decimals for branches and delivery points.

  • A pin with no name or address

    A bare pin shows a map and nothing else until it loads. Always add the place name and an address with a landmark.

  • Using a location message to ask

    Sending your own pin does not invite the customer to share theirs. To ask, send a location request message with its Send location button.

  • Treating a shared pin as a verified address

    A customer may share where they are now, such as an office, rather than where the parcel should go. Confirm delivery pins, or collect a structured address with an address message.

Best practices for a location message

  • Follow a store pin with opening hours and a phone number, or attach a Contacts Message for the branch.
  • Geocode branch addresses once and verify them on a map instead of geocoding at send time.
  • Precise location is personal data under the DPDP Act: keep customer pins only as long as the order or visit needs them.
  • Round coordinates in logs and analytics; nobody needs a customer's exact door in a dashboard.

Location Message FAQs

How do I send a location on the WhatsApp Business API?+
POST a message with `type: location` and a `location` object containing `latitude` and `longitude` in decimal degrees, plus an optional `name` and `address`, to `/{PHONE_NUMBER_ID}/messages` while the customer service window is open.
Can I send a location message outside the 24-hour window?+
Not as a free-form message. Outside the window, send an approved utility or marketing template with a location header; the coordinates are set when you send it.
What is the difference between a location message and a location request message?+
A location message is the pin itself, sent by you or by the customer. A location request message is an interactive message with a Send location button that asks the customer to share theirs.
Does the location webhook include an address?+
Only sometimes. `latitude` and `longitude` are always there; `name` and `address` appear only when the customer picked a named place instead of sharing their raw current position.
Which coordinate format does WhatsApp use?+
Decimal degrees, latitude first: for example 12.97910, 80.21840 in Chennai. Convert degrees-minutes-seconds before sending, and use negative values for south and west.

Talk to InfiQ

From definition to your first message

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms