Channel Location Parsing and Portable Outbound Payloads

OpenClaw converts shared locations received from chat channels into two forms:

• compact coordinate text that gets appended to the incoming message body, and
• structured fields carried inside the auto-reply context payload. Any labels, addresses, or captions/comments supplied by the channel are inserted into the prompt through the shared untrusted metadata JSON block rather than appearing directly in the user body.

Channels that are currently handled:

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

Text formatting

Location rendering produces friendly lines with no brackets. Coordinates are expressed to six decimal places, while accuracy is rounded off to whole meters:

• Pin:
  • 📍 48.858844, 2.294351 ±12m
• Named place (name/address appear only in the metadata block, on the same line):
  • 📍 48.858844, 2.294351 ±12m
• Live share:
  • 🛰 Live location: 48.858844, 2.294351 ±12m

When a label, address, or caption/comment is present, it is retained in the context payload and surfaces in the prompt as fenced untrusted JSON (fields get omitted when absent):

Location:
```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

With a location present, these fields are appended 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)

If the channel fails to specify an explicit source, OpenClaw makes an inference: live shares map to live, locations carrying a name or address map to place, and all remaining cases map to pin.

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

Outbound payloads

Portable outbound locations rely on the same NormalizedLocation shape across the message tool and the Plugin SDK. A payload holding only coordinates stands for a pin. Channels that natively support venues can translate name plus address into a venue card.

Telegram currently surfaces this via message(action="send"). The first cut is intentionally isolated: location payloads cannot be combined with text or media, and incomplete venue pairs cause a failure rather than quietly discarding a name or address. Channels without support do not advertise the location parameter.

Channel notes

• LINE: location message title/address correspond to LocationName/LocationAddress; live locations are unsupported.
• Matrix: geo_uri gets parsed as a pin location; the u (uncertainty) parameter feeds into LocationAccuracy, the event body fills LocationCaption, altitude is disregarded, and LocationIsLive is always false.
• Telegram: venues map to LocationName/LocationAddress; live locations are recognized through live_period.
• WhatsApp: locationMessage.comment and liveLocationMessage.caption populate LocationCaption.

Related

• Location command (nodes)
• Camera capture
• Media understanding