Send Location

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>"
}
'

const options = {
  method: 'POST',
  headers: {token: '<token>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    number: '<string>',
    latitude: {},
    longitude: {},
    name: '<string>',
    address: '<string>',
    delay: 123,
    replyTo: '<string>',
    replyPrivate: true,
    source: '<string>'
  })
};

fetch('https://api.example.com/api/message/location/:instance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/api/message/location/:instance"

payload = {
    "number": "<string>",
    "latitude": {},
    "longitude": {},
    "name": "<string>",
    "address": "<string>",
    "delay": 123,
    "replyTo": "<string>",
    "replyPrivate": True,
    "source": "<string>"
}
headers = {
    "token": "<token>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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"
  }'

await fetch(`https://ryzeapi.cloud/api/message/location/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number:    "5511999999999",
    latitude:  -23.5614,
    longitude: -46.6558,
    name:      "Avenida Paulista",
    address:   "Av. Paulista, 1578 - Bela Vista, São Paulo - SP"
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/location/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number":    "5511999999999",
        "latitude":  -23.5614,
        "longitude": -46.6558,
        "name":      "Avenida Paulista",
        "address":   "Av. Paulista, 1578 - Bela Vista, São Paulo - SP"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number":    "5511999999999",
        "latitude":  -23.5614,
        "longitude": -46.6558,
        "name":      "Avenida Paulista",
        "address":   "Av. Paulista, 1578 - Bela Vista, São Paulo - SP"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/location/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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"
  }'

await fetch(`https://ryzeapi.cloud/api/message/location/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number:    "5511999999999",
    latitude:  -23.5614,
    longitude: -46.6558,
    name:      "Meeting point",
    address:   "Av. Paulista, 1578",
    replyTo:   "3EB08FCF27E532F1B0F5"
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/location/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number":    "5511999999999",
        "latitude":  -23.5614,
        "longitude": -46.6558,
        "name":      "Meeting point",
        "address":   "Av. Paulista, 1578",
        "replyTo":   "3EB08FCF27E532F1B0F5"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number":    "5511999999999",
        "latitude":  -23.5614,
        "longitude": -46.6558,
        "name":      "Meeting point",
        "address":   "Av. Paulista, 1578",
        "replyTo":   "3EB08FCF27E532F1B0F5"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/location/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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

string

required

Instance name (e.g., $Instance_Name).

Headers

string

required

TokenAccount or TokenInstance.

string

required

application/json

Request body

string

required

Destination: phone (5511999999999) or JID (@s.whatsapp.net, @lid, @g.us, @newsletter).

float64

required

Geographic latitude in decimal degrees (e.g., -23.5614). Recommended precision is 4 to 6 decimal places.

float64

required

Geographic longitude in decimal degrees (e.g., -46.6558).

string

required

Main label displayed on the location card (highlighted line). Usually the place/establishment name.

string

required

Address/secondary description displayed below name on the card.

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.

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.

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.

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

HTTP	Internal status	Message
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`
400	`invalid_number`	`Invalid phone number format: <detail>`
500	`send_failed`	`Failed to send message: <reason>`
404	,	`Instance not found`
503	`disconnected`	`Instance is not connected to WhatsApp`

Error envelope:

{
  "success": false,
  "error": { "message": "Latitude and longitude are required" }
}

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Description

Examples

Simple location

As a reply to a message

Success response

Path parameters

Headers

Request body

Notes

Errors

​Description

​Examples

​Simple location

​As a reply to a message

​Success response

​Path parameters

​Headers

​Request body

​Notes

​Errors

Description

Examples

Simple location

As a reply to a message

Success response

Path parameters

Headers

Request body

Notes

Errors