Location message
A location message is a message that contains geographical information such as a map or a link to a map. You can send a location message by making a POST
request to the /messages:send
Conversation API endpoint with the following payload:
{- "app_id": "{{APP_ID}}",
- "recipient": "{{CONTACT_ID}}",
- "message": {
- "location_message": {
- "title": "Your ride is here!",
- "label": "Meet your driver at the specified address.",
- "coordinates": {
- "latitude": 55.610479,
- "longitude": 13.002873
}
}
}
}
Location message schema
A location message can take the following parameters and properties.
required | object (Coordinates) |
title required | string The title is shown close to the button or link that leads to a map showing the location. The title can be clickable in some cases. |
label | string Label or name for the position. |
Note:
Not all channels support every parameter.
The following sections give examples of how card messages are rendered in each channel and specific parameter support:
- SMS
- Facebook Messenger
- MMS
- RCS
- Viber Bot
- Viber Business Messages
- Telegram
- KakaoTalk
- Apple Messages for Business
- LINE
WhatsApp channel natively supports location messages. The following image gives an example of a location message.
SMS
SMS supports Location messages natively. The following image gives an example of a location message.
Facebook Messenger
Facebook Messenger supports location messages natively. The following image gives an example of a location message.
Instagram doesn't natively support location messages. The location message is transcoded as a text message which contains a URL that points to the Google Maps app. The following image gives an example of a location message.
Apple Messages for Business
Location messages will be sent with an Apple Maps URL and Apple supports the preview automatically.
MMS
MMS doesn't natively support location messages, and so they're transcoded and sent as text messages by Conversation API.
The following image gives an example of a location message.
RCS
RCS channel doesn't natively support Location Messages. You can simply put your coordinates in a message body and Conversation API transcodes it into a text message with one Location Choice.
The following image gives an example of a location message.
Viber Bot
Viber Bot channel natively supports location messages. The following image gives an example of a location message.
Viber Business Messages
Viber Business Messages channel doesn't natively support location messages and so they're transcoded and sent as text messages by Conversation API. The following image gives an example of a location message.
Telegram
Telegram Bot channel natively supports location messages.
KakaoTalk
KakaoTalk doesn't natively support location messages, and so they're transcoded and sent as text messages by Conversation API.
The Location message as text (including title, label, url) has a maximum length of 1000 characters.
LINE
LINE channel natively supports location messages.
WeChat channel doesn't natively support location messages. Location messages or location choices sent to WeChat will be converted to a Map URL. Clicking the URL will open the map within embedded browser.
Due to the restrictions on geographic data in China, the raw GPS data in WGS84 format (used by many Map Service Providers, such as Google) can't be used in China. Instead, local Chinese Map Service Providers use different geographic data formats, such as BD09.
To send a location message or location choice to WeChat, you need to have location data in BD09 format. Please get coordinates from a Chinese Map Service Provider such as Baidu Map.