Перейти к содержимому

sendLocation

Обновлено 17 октября 2026

Содержание
  1. Параметры
  2. Пример запроса
  3. Пример ответа
  4. Ещё примеры
  5. Точка без названия
  6. Ошибки
  7. Особенности каналов
  8. Что дальше

Отправляет геопозицию: точку на карте или место с названием и адресом — как «Отправить место» в приложении. Работает в Telegram и WhatsApp.
Запрос POST /waInstance{idInstance}/sendLocation/{apiTokenInstance}
Тело JSON
Каналы Telegram, WhatsApp. MAX и почта — 501

Параметры

Параметр Тип Обязательный Описание
chatId string да получатель: личный чат, группа или номер 79991234567@c.us — см. Идентификаторы чатов и сообщений
latitude number да широта, от −90 до 90
longitude number да долгота, от −180 до 180
nameLocation string нет название места
address string нет адрес. С названием или адресом уходит место, без них — точка
quotedMessageId string нет ответить цитатой на сообщение этого же чата
clientMessageId string нет ваш ключ от дублей — см. Надёжная отправка без дублей

Пример запроса

Как добраться до школы — место с названием и адресом в WhatsApp:

curl

curl -X POST "$GRATIO_URL/waInstance$GRATIO_ID/sendLocation/$GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "chatId": "79991234567@c.us",
    "latitude": 55.0188,
    "longitude": 82.9387,
    "nameLocation": "Школа робототехники",
    "address": "Красный проспект, 25",
    "clientMessageId": "route-79991234567"
  }'

Python

import os
import requests

BASE = f"{os.environ['GRATIO_URL']}/waInstance{os.environ['GRATIO_ID']}"
TOKEN = os.environ["GRATIO_TOKEN"]

url = f"{BASE}/sendLocation/{TOKEN}"
payload = {
    "chatId": "79991234567@c.us",
    "latitude": 55.0188,
    "longitude": 82.9387,
    "nameLocation": "Школа робототехники",
    "address": "Красный проспект, 25",
    "clientMessageId": "route-79991234567",
}
response = requests.post(url, json=payload, timeout=60)
print(response.status_code, response.json())

Node.js

const { GRATIO_URL, GRATIO_ID, GRATIO_TOKEN } = process.env;
const base = `${GRATIO_URL}/waInstance${GRATIO_ID}`;

const url = `${base}/sendLocation/${GRATIO_TOKEN}`;
const payload = {
  chatId: "79991234567@c.us",
  latitude: 55.0188,
  longitude: 82.9387,
  nameLocation: "Школа робототехники",
  address: "Красный проспект, 25",
  clientMessageId: "route-79991234567",
};
const response = await fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
console.log(response.status, await response.json());

PHP

<?php
$base = getenv('GRATIO_URL') . '/waInstance' . getenv('GRATIO_ID');
$url = $base . '/sendLocation/' . getenv('GRATIO_TOKEN');
$payload = [
    'chatId' => '79991234567@c.us',
    'latitude' => 55.0188,
    'longitude' => 82.9387,
    'nameLocation' => 'Школа робототехники',
    'address' => 'Красный проспект, 25',
    'clientMessageId' => 'route-79991234567',
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$response = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($response);

Пример ответа

Ответ 200 OK:

{"idMessage": "3EB0C767D26A1D5A6F0B"}

После отправки приходят outgoingAPIMessageReceived с locationMessageData и статус outgoingMessageStatus sent.

Ещё примеры

Точка без названия

Telegram, личный чат:

curl -X POST "$GRATIO_URL/waInstance$GRATIO_ID/sendLocation/$GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "chatId": "8617393401",
    "latitude": 55.0188,
    "longitude": 82.9387
  }'

Ошибки

Код code Когда Что делать
400 validation нет latitude или longitude, координата не число исправить запрос
400 bad_location координаты вне диапазона проверить широту и долготу
400 not_authorized канал не на связи проверить getStateInstance
400 no_account на номере …@c.us нет аккаунта в этом мессенджере выбрать другой канал
402 payment_required канал на паузе за неоплату продлить канал в кабинете
409 idempotency_conflict тот же clientMessageId с другими координатами новый ключ для нового сообщения
429 too_frequent и другие темп канала или правило WhatsApp повторить после Retry-After
469 rate_limited Telegram попросил паузу повторить после Retry-After
501 not_supported канал MAX или почта отправить адрес текстом через sendMessage
503 outcome_unknown связь оборвалась посреди отправки повторить с тем же clientMessageId

Особенности каналов

  • Telegram. С nameLocation или address уходит место с названием и адресом, без них — точка на карте.
  • WhatsApp. Название и адрес уходят вместе с точкой. Первое сообщение новому собеседнику ограничено правилами качества — см. WhatsApp.
  • MAX и почта — 501 not_supported.

Что дальше

Была ли статья полезна?

Похожие статьи