WatsyAppAPI WatsyApp
Описанный ниже HTTPS-интерфейс принимает ключ вашего аккаунта WatsyApp и ID подключённого канала. Одинаковый маршрут отправки выбирает нужный транспорт через channelId.
РАЗРАБОТЧИКАМ · TELEGRAM
Telegram через API WatsyApp.
Отправляйте текст из своей серверной интеграции через подключённый личный Telegram или Telegram Bot. Реальная отправка через HTTPS API проверена для обоих типов каналов.
ПОДТВЕРЖДЁННЫЙ КОНТРАКТ
Два реальных запроса.
Оба сообщения получены.
Что проверено на рабочем сервисе
Через публичный https://watsyapp.com/v3/message отправлено по одному уникальному тексту в собственные существующие тестовые диалоги Telegram Bot и личного аккаунта по QR. Оба запроса вернули HTTP 200, messageId и ожидаемый chatId. Сообщение бота получено в Telegram Web ровно один раз; получение личного сообщения отдельно подтвердил пользователь.
Эта проверка относится к текстовой отправке известному собеседнику. Она не подтверждает холодный первый контакт по username, API вложений, массовые рассылки или публичную доставку входящих на ваш callback.
Три разных API
Telegram Bot API
Прямой интерфейс Telegram для ботов. Токен BotFather нужен для подключения бота в WatsyApp, но не является ключом этого API. Обычному боту пользователь сначала пишет сам.
Клиентский Telegram API
Личный аккаунт работает через отдельную Telegram-сессию по QR. В примере /v3/message не нужны api_id, api_hash или пароль Telegram: подключённым каналом управляет WatsyApp.
Подключение канала: личный аккаунт по QR или Telegram Bot. Telegram Business и обычные способы подключения — отдельные механизмы; этот API-гайд не заявляет Business-коннектор.
Доступ и выбор канала
Войдите в свой аккаунт WatsyApp, выберите нужный активный Telegram-канал и откройте «Интеграция API». Используйте API-ключ аккаунта и ID этого канала. Для первого теста возьмите существующий собственный диалог с известным числовым Telegram chatId.
Передавайте ключ только сервером в заголовке Authorization: Bearer. Не помещайте его в URL, публичный JavaScript, HTML или репозиторий. В примерах используются переменные окружения и вымышленные идентификаторы; подставлять секреты в страницу не нужно.
Список каналов аккаунта
curl 'https://watsyapp.com/v3/channels' \
--header "Authorization: Bearer $WATSYAPP_API_KEY"Ответ GET /v3/channels — массив доступных вашему ключу каналов. Выберите transport равный telegram для личного аккаунта или telegram_bot для бота и проверьте state. Пример ниже сокращён до нужных полей; значения вымышлены.
[
{"channelId":"YOUR_PERSONAL_CHANNEL_ID","transport":"telegram","state":"active"},
{"channelId":"YOUR_BOT_CHANNEL_ID","transport":"telegram_bot","state":"active"}
]Ключ и channelId должны принадлежать одному аккаунту. Чужой или неизвестный канал не становится доступным при подстановке ID.
ОТПРАВКА ТЕКСТА
POST /v3/message
Обязательные поля JSON: channelId, chatId и непустой text. Для обоих типов Telegram используйте один маршрут; тип определяется выбранным каналом. В проверенном сценарии chatId — строка с числовым ID существующего собеседника.
curl --request POST 'https://watsyapp.com/v3/message' \
--header "Authorization: Bearer $WATSYAPP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"channelId": "YOUR_TELEGRAM_CHANNEL_ID",
"chatId": "123456789",
"text": "Тест из моей интеграции"
}' Пример успешного ответа с вымышленными значениями:
{
"messageId": "tg:123456789:42",
"chatId": "123456789"
}Сохраните messageId как непрозрачный идентификатор. HTTP 200 и messageId означают успешный результат отправки по контракту, но не являются подтверждением прочтения адресатом. В нашем тесте получение дополнительно проверено на стороне Telegram.
Пример серверного JavaScript
// Выполняйте на сервере. Значения берите из своего аккаунта и тестового диалога.
const response = await fetch('https://watsyapp.com/v3/message', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.WATSYAPP_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
channelId: process.env.WATSYAPP_TELEGRAM_CHANNEL_ID,
chatId: process.env.TELEGRAM_TEST_CHAT_ID,
text: 'Тест из моей интеграции'
})
});
const result = await response.json();
if (!response.ok) throw new Error(result.error || `HTTP ${response.status}`);
// Сохраните result.messageId; при неизвестном результате не повторяйте запрос вслепую.
console.log({messageId: result.messageId});Не включайте автоматический повтор POST после тайм-аута или разрыва соединения: сообщение могло уйти, даже если ответ не получен. Клиентский idempotency-key в этом контракте не заявлен.
Входящие сообщения:
что этот API не обещает
GET /v3/webhooks сейчас возвращает:
{"webhooksUri":null,"enabled":false}Публичный callback входящих в этом интерфейсе отключён. Не выдумывайте адрес webhook и не считайте HTTP-успех исходящего запроса подтверждением двустороннего API для вашей системы. Подключённые каналы получают сообщения в WatsyApp; проверенный мост Telegram ↔ 2wix настраивается отдельно и не является вашим произвольным webhook.
В своих заданиях сохраняйте факт отправки и возвращённый messageId, исключайте повторный запуск одного задания. При построении будущего обработчика событий потребуется отдельный опубликованный контракт входящих и дедупликации. Этот гайд его не подменяет.
Проверенные ограничения
| Параметр | Состояние |
|---|---|
| Текст | Непустая строка до 4096 символов; 4097 символов отклонены HTTP 400 без отправки. |
| Личный аккаунт по QR | Проверена отправка в существующий диалог по числовому chatId. Новый первый контакт по @username отдельно не принят. |
| Обычный Bot | Сначала пользователь пишет боту. Случайный ID, телефон или username не заменяют это обращение. |
| contentUri | POST /v3/message с этим полем отклоняется HTTP 422. Этот маршрут документирован здесь для текста. |
| Медиа | Отдельный multipart /api/send и текущая разработка медиа не входят в принятую область этого гайда. |
| Группы и история | Групповые переписки и автоматический импорт прежних диалогов не заявлены. |
| Callback входящих | /v3/webhooks возвращает enabled:false; пользовательский webhook не включён. |
| Рассылки, Business и тариф | Не заявлены этим контрактом. Ограничения Telegram и блокировка получателем не обходятся API-ключом. |
Ошибки и повторная отправка
| HTTP | Что проверить |
|---|---|
| 400 | JSON, непустой text, длину, корректность chatId. Ответ содержит поле error. |
| 401 / 403 | Действительность Bearer-ключа и доступность аккаунта. |
| 404 | Принадлежность channelId вашему аккаунту и правильность ID. |
| 409 | Активное подключение, существующий адресат; для Bot — первое входящее от пользователя. |
| 422 | Не отправляете ли contentUri в текстовый /v3/message. |
| 502 или неизвестный результат | Сначала проверьте результат в тестовом диалоге. Не повторяйте POST вслепую. |
Проверки без действительного ключа, с contentUri и слишком длинным текстом выполнены отдельно и не создали новых сообщений. Во время приёмки каждого успешного запроса зафиксировано ровно одно сохранённое исходящее.
Вопросы об API
Нужен токен BotFather в запросе /v3/message?
Нет. Здесь используется API-ключ аккаунта WatsyApp и ID подключённого канала. Токен BotFather вводится при подключении бота, а не вместо Bearer-ключа WatsyApp.
Можно отправить запрос для личного Telegram?
Да, реальный HTTPS-запрос в существующий тестовый диалог по числовому chatId выполнен, получение подтверждено пользователем. Личный канал предварительно подключается по QR.
Можно указать номер телефона вместо chatId?
Номер телефона и Telegram chatId — разные данные. В этом гайде проверен числовой идентификатор существующего диалога; поиск нового адресата по телефону не заявлен.
Можно получить входящие на свой webhook?
В описанном интерфейсе callback отключён: GET /v3/webhooks возвращает enabled:false. Готовый мост 2wix работает отдельно и не означает произвольную подписку вашей системы.
Безопасно ли повторять запрос после тайм-аута?
Автоматически — нет: исходящее могло быть отправлено до потери ответа. Проверьте диалог и журнал задания. Гарантированная идемпотентность повторного клиентского POST здесь не заявлена.
Где официальная документация самого Telegram?
Telegram Bot API и клиентский API — отдельные интерфейсы Telegram. Примеры на этой странице обращаются к WatsyApp и описывают его контракт, а не универсальные возможности Telegram.
Контракт проверен 23 октября 2026 года. Ключи, ID и переписка реальных аккаунтов в примерах не опубликованы.
ПУТЕВОДИТЕЛЬ ПО СЕРВИСУ
Другие разделы WatsyApp
Выберите задачу: работа с диалогами, подключение номера или интеграция с вашей системой.