Saltar al contenido principal
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>"
}
'
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"
  }'

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

​
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

​
instance
string
requerido
Nombre de la instancia (p. ej., $Instance_Name).

​
Cabeceras

​
token
string
requerido
TokenAccount o TokenInstance.
​
Content-Type
string
requerido
application/json

​
Cuerpo de la solicitud

​
number
string
requerido
Destino: teléfono (5511999999999) o JID (@s.whatsapp.net, @lid, @g.us, @newsletter).
​
latitude
float64
requerido
Latitud geográfica en grados decimales (p. ej., -23.5614). La precisión recomendada es de 4 a 6 decimales.
​
longitude
float64
requerido
Longitud geográfica en grados decimales (p. ej., -46.6558).
​
name
string
requerido
Etiqueta principal mostrada en la tarjeta de ubicación (línea destacada). Usualmente el nombre del lugar/establecimiento.
​
address
string
requerido
Dirección/descripción secundaria mostrada debajo de name en la tarjeta.
​
delay
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.
​
replyTo
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.
​
replyPrivate
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.
​
source
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

HTTPStatus internoMensaje
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
Envoltorio de error: 
{
  "success": false,
  "error": { "message": "Latitude and longitude are required" }
}