Skip to main content
POST
/
api
/
message
/
location
/
:instance
Send Location
curl --request POST \
  --url https://api.example.com/api/message/location/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "number": "<string>",
  "latitude": {},
  "longitude": {},
  "name": "<string>",
  "address": "<string>",
  "delay": 123,
  "replyTo": "<string>",
  "replyPrivate": true,
  "source": "<string>"
}
'
Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: no

​
Description

Sends a geographic location as a rich message (LocationMessage), with latitude, longitude, name (main label) and address (secondary line). The recipient sees a card with a map preview and “Open in maps” buttons. Supports replyTo, replyPrivate, delay (in seconds) and source. Does not support mentions.

​
Examples

​
Simple location

Sends a location card with the coordinates of Avenida Paulista (-23.5614, -46.6558), the name of the place and the full address. The recipient sees a map preview and can open it in their navigation app. 
curl -X POST "https://ryzeapi.cloud/api/message/location/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":    "5511999999999",
    "latitude":  -23.5614,
    "longitude": -46.6558,
    "name":      "Avenida Paulista",
    "address":   "Av. Paulista, 1578 - Bela Vista, São Paulo - SP"
  }'

​
As a reply to a message

Sends the location card quoting a previous message via replyTo. Useful for replying to a “where do we meet?” question while keeping the original message quoted. 
curl -X POST "https://ryzeapi.cloud/api/message/location/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":    "5511999999999",
    "latitude":  -23.5614,
    "longitude": -46.6558,
    "name":      "Meeting point",
    "address":   "Av. Paulista, 1578",
    "replyTo":   "3EB08FCF27E532F1B0F5"
  }'

​
Success response

The content returns a textual representation of the location (📍 name\naddress\nLat: ..., Long: ...) saved to history, and messageType is fixed at location.
200 OK
{
  "success": true,
  "message": "Location sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1B0F5",
    "direction":   "sent",
    "messageType": "location",
    "content":     "📍 Avenida Paulista\nAv. Paulista, 1578 - Bela Vista, São Paulo - SP\nLat: -23.561414, Long: -46.655881",
    "source":      "api",
    "timestamp":   "2026-04-30T14:30:00Z",
    "chat": {
      "jid":     "5511999999999@s.whatsapp.net",
      "isGroup": false
    },
    "sender": {
      "jid":      "5511777777777@s.whatsapp.net",
      "instance": "minha-instancia"
    }
  }
}

​
Path parameters

​
instance
string
required
Instance name (e.g., $Instance_Name).

​
Headers

​
token
string
required
TokenAccount or TokenInstance.
​
Content-Type
string
required
application/json

​
Request body

​
number
string
required
Destination: phone (5511999999999) or JID (@s.whatsapp.net, @lid, @g.us, @newsletter).
​
latitude
float64
required
Geographic latitude in decimal degrees (e.g., -23.5614). Recommended precision is 4 to 6 decimal places.
​
longitude
float64
required
Geographic longitude in decimal degrees (e.g., -46.6558).
​
name
string
required
Main label displayed on the location card (highlighted line). Usually the place/establishment name.
​
address
string
required
Address/secondary description displayed below name on the card.
​
delay
int
default:"0"
Time in seconds to wait before sending. During the interval, the server sends the “typing…” indicator to the recipient and fires “paused” before the actual send.
​
replyTo
string
ID of the message to be quoted (reply). The original message must belong to the same instance and have been saved in the database.
​
replyPrivate
boolean
default:"false"
When true and replyTo points to a message originating from a group, the reply is redirected to the original author’s private chat (keeping the quote). Ignored if the original message is not from a group.
​
source
string
default:"api"
Origin identifier for traceability (e.g., crm, bot-suporte, n8n). Saved on the message record in the database and propagated to webhooks. When omitted, defaults to "api".

​
Notes

  • delay is in seconds, not milliseconds.
  • The current validation rejects sends when both latitude and longitude are exactly 0, the point (0, 0) in the Atlantic is rarely a legitimate intent and usually indicates a payload with a missing field.
  • Location messages do not support mention or mentionAll.
  • “Live” location is not supported by this endpoint, only static locations.
  • For BR numbers (starting with 55), the service automatically tries variations with and without the 9th digit.

​
Errors

HTTPInternal statusMessage
400,Instance name is required
400,Invalid request body: <detail>
400,Number is required
400,Latitude and longitude are required
400,Name is required
400,Address is required
400invalid_numberInvalid phone number format: <detail>
500send_failedFailed to send message: <reason>
404,Instance not found
503disconnectedInstance is not connected to WhatsApp
Error envelope: 
{
  "success": false,
  "error": { "message": "Latitude and longitude are required" }
}