Handling Map Locations in Chat Channels

I’ve spent too much time trying to parse different message formats just to figure out where a user is located. Every chat platform has its own way of sending coordinates, names, and live updates. It gets messy fast when you want to build an auto-reply that actually understands location data without writing custom parsers for every single API.

I prefer when tools take that inconsistent data and turn it into something predictable. OpenClaw does this by normalizing shared locations into human-readable text and structured fields you can use in your logic.

What You’ll Need

• An active OpenClaw instance
• A connected account on Telegram, WhatsApp, or Matrix

Quick Start

When a user sends a location, OpenClaw automatically processes it. You don’t need to toggle any special flags. The system handles two outputs: a text string appended to the message and structured data in the ctx payload.

1. Text Formatting

OpenClaw renders locations as friendly lines. If the user includes a caption or a comment, it appears on the next line. Here is how the different types look:

• Pins: 📍 48.858844, 2.294351 ±12m
• Named Places: 📍 Eiffel Tower — Champ de Mars, Paris (48.858844, 2.294351 ±12m)
• Live Shares: 🛰 Live location: 48.858844, 2.294351 ±12m

If a caption is included, the output looks like this:

📍 48.858844, 2.294351 ±12m
Meet here

2. Context Fields

For automated logic, you can access the structured fields inside the ctx object. These are the fields available when a location is detected:

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

Troubleshooting

If you aren’t seeing the data you expect, keep these channel-specific behaviors in mind:

• Matrix Constraints: OpenClaw parses the geo_uri as a pin location. It ignores altitude data, and the LocationIsLive field is always set to false for Matrix messages.
• Telegram and WhatsApp Captions: For Telegram, venues are mapped to LocationName and LocationAddress. For WhatsApp, any text in locationMessage.comment or liveLocationMessage.caption is appended as the caption line in the text output.

If you hit a snag with a specific platform, check the AI Setup Assistant for help with your configuration.

What’s Next

• Telegram Integration Guide
• WhatsApp Integration Guide
• Matrix Integration Guide
• Context Payload Reference