Enviar ubicación

POST

api

message

location

:instance

Enviar ubicación

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 o TokenInstance • Rate-limit: Global (100/min) • Idempotente: no

Descripción

Envía una ubicación geográfica como mensaje enriquecido (LocationMessage), con latitude, longitude, name (etiqueta principal) y address (línea secundaria). El destinatario ve una tarjeta con vista previa de mapa y botones “Abrir en mapas”. Soporta replyTo, replyPrivate, delay (en segundos) y source. No soporta menciones.

Ejemplos

Ubicación simple

Envía una tarjeta de ubicación con las coordenadas de Avenida Paulista (-23.5614, -46.6558), el nombre del lugar y la dirección completa. El destinatario ve una vista previa del mapa y puede abrirla en su app de navegación.

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)
}

Como respuesta a un mensaje

Envía la tarjeta de ubicación citando un mensaje anterior vía replyTo. Útil para responder a una pregunta “¿dónde nos encontramos?” manteniendo el mensaje original citado.

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)
}

Respuesta exitosa

El content retorna una representación textual de la ubicación (📍 name\naddress\nLat: ..., Long: ...) guardada en el historial, y messageType es fijo en 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"
    }
  }
}

Parámetros de ruta

string

requerido

Nombre de la instancia (p. ej., $Instance_Name).

Cabeceras

string

requerido

TokenAccount o TokenInstance.

string

requerido

application/json

Cuerpo de la solicitud

string

requerido

Destino: teléfono (5511999999999) o JID (@s.whatsapp.net, @lid, @g.us, @newsletter).

float64

requerido

Latitud geográfica en grados decimales (p. ej., -23.5614). La precisión recomendada es de 4 a 6 decimales.

float64

requerido

Longitud geográfica en grados decimales (p. ej., -46.6558).

string

requerido

Etiqueta principal mostrada en la tarjeta de ubicación (línea destacada). Usualmente el nombre del lugar/establecimiento.

string

requerido

Dirección/descripción secundaria mostrada debajo de name en la tarjeta.

int

predeterminado:"0"

Tiempo en segundos a esperar antes de enviar. Durante el intervalo, el servidor envía el indicador “escribiendo…” al destinatario y dispara “pausado” antes del envío real.

string

ID del mensaje a citar (respuesta). El mensaje original debe pertenecer a la misma instancia y haber sido guardado en la base de datos.

boolean

predeterminado:"false"

Cuando es true y replyTo apunta a un mensaje originado en un grupo, la respuesta se redirige al chat privado del autor original (manteniendo la cita). Ignorado si el mensaje original no es de un grupo.

string

predeterminado:"api"

Identificador de origen para trazabilidad (p. ej., crm, bot-suporte, n8n). Guardado en el registro del mensaje en la base de datos y propagado a los webhooks. Cuando se omite, el default es "api".

Notas

delay es en segundos, no milisegundos.
La validación actual rechaza envíos cuando tanto latitude como longitude son exactamente 0, el punto (0, 0) en el Atlántico raramente es una intención legítima y usualmente indica un payload con un campo faltante.
Los mensajes de ubicación no soportan mention ni mentionAll.
La ubicación “en vivo” no está soportada por este endpoint, solo ubicaciones estáticas.
Para números BR (que comienzan con 55), el servicio prueba automáticamente variaciones con y sin el 9° dígito.

Errores

HTTP	Status interno	Mensaje
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`

Envoltorio de error:

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

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Enviar ubicación

Descripción

Ejemplos

Ubicación simple

Como respuesta a un mensaje

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores

​Descripción

​Ejemplos

​Ubicación simple

​Como respuesta a un mensaje

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Notas

​Errores

Descripción

Ejemplos

Ubicación simple

Como respuesta a un mensaje

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores