Neura Market Logo

Channel Location Parsing and Portable Outbound Location Payloads

This page explains how OpenClaw normalizes shared locations from chat channels into compact coordinate text and structured fields. It covers supported platforms like LINE, Matrix, Telegram, and WhatsApp for developers integrating location features.

Read this when

  • Adding or modifying channel location parsing
  • Using location context fields in agent prompts or tools

OpenClaw normalizes shared locations from chat channels into:

  • compact coordinate text appended to the inbound body, and
  • structured fields in the auto-reply context payload. Channel-provided labels, addresses, and captions or comments are rendered into the prompt through the shared untrusted metadata JSON block, not inline in the user body.

Currently supported:

  • LINE (location messages with title or address)
  • Matrix (m.location with geo_uri)
  • Telegram (location pins, venues, and live locations)
  • WhatsApp (locationMessage and liveLocationMessage)

Text formatting

Locations are displayed as friendly lines without brackets. Coordinates use six decimal places; accuracy is rounded to whole meters:

  • Pin:
    • 📍 48.858844, 2.294351 ±12m
  • Named place (same line; the name and address go to the metadata block only):
    • 📍 48.858844, 2.294351 ±12m
  • Live share:
    • 🛰 Live location: 48.858844, 2.294351 ±12m

If the channel includes a label, address, or caption or comment, it is kept in the context payload and appears in the prompt as fenced untrusted JSON (fields are omitted when absent):

Location (untrusted metadata):
```json
{
  "latitude": 48.858844,
  "longitude": 2.294351,
  "accuracy_m": 12,
  "source": "place",
  "name": "Eiffel Tower",
  "address": "Champ de Mars, Paris",
  "caption": "Meet here"
}
```

Context fields

When a location is present, these fields are added to ctx:

  • LocationLat (number)
  • LocationLon (number)
  • LocationAccuracy (number, meters; optional)
  • LocationName (string; optional)
  • LocationAddress (string; optional)
  • LocationSource (pin | place | live)
  • LocationIsLive (boolean)
  • LocationCaption (string; optional)

When the channel does not set an explicit source, OpenClaw infers it: live shares become live, locations with a name or address become place, everything else is pin.

The prompt renderer treats LocationName, LocationAddress, and LocationCaption as untrusted metadata and serializes them through the same bounded JSON path used for other channel context.

Outbound payloads

The message tool and Plugin SDK use the same NormalizedLocation shape for portable outbound locations. A coordinate-only payload represents a pin. Channels with native venue support may map name plus address to a venue card.

Telegram currently exposes this through message(action="send"). Its first implementation is deliberately standalone: location payloads cannot be mixed with text or media, and incomplete venue pairs fail instead of silently dropping a name or address. Unsupported channels do not advertise the location parameter.

Channel notes

  • LINE: location message title or address map to LocationName or LocationAddress; no live locations.
  • Matrix: geo_uri is parsed as a pin location; the u (uncertainty) parameter maps to LocationAccuracy, the event body populates LocationCaption, altitude is ignored, and LocationIsLive is always false.
  • Telegram: venues map to LocationName or LocationAddress; live locations are detected via live_period.
  • WhatsApp: locationMessage.comment and liveLocationMessage.caption populate LocationCaption.