1-чат

MCP · REST API

MCP-сервер и API для мессенджеров

15 инструментов для работы с Telegram, WhatsApp*, Max и Instagram* из ИИ-агента: отправка и чтение сообщений, поиск контактов, вложения, webhook на входящие. Один ключ, одинаковые сигнатуры для всех каналов.

Получить API-ключGitHubllms.txt
15
инструментов
4
канала
2025-06-18
протокол MCP
@1-chat/mcp
пакет
mcp.json
{
  "mcpServers": {
    "1-chat": {
      "command": "npx",
      "args": ["-y", "@1-chat/mcp"],
      "env": {
        "ONECHAT_API_KEY": "sk-1chat-..."
      }
    }
  }
}

Быстрый старт

Три шага до первого сообщения

01

Выпустите ключ

В кабинете, раздел «API». При выпуске указываются права (read / write) и набор каналов.

bash
export ONECHAT_API_KEY=sk-1chat-...
02

Подключите сервер

Локально через npx или удалённо по HTTP — конфиг одинаков для любого MCP-клиента.

mcp.json
{
  "mcpServers": {
    "1-chat": {
      "command": "npx",
      "args": ["-y", "@1-chat/mcp"],
      "env": {
        "ONECHAT_API_KEY": "sk-1chat-..."
      }
    }
  }
}
03

Вызовите инструмент

Проверить подключение можно любым инструментом чтения — он не расходует лимит отправки.

tool call
{
  "tool": "list_chats",
  "arguments": { "unread_only": true, "limit": 20 }
}

Инструменты

15 функций MCP-сервера

Сигнатуры не зависят от канала. Тип Channel = 'telegram' | 'whatsapp' | 'max' | 'instagram'.

Диалоги и сообщения

list_chats(channel?: Channel, unread_only?: boolean, limit?: number)→ Chat[]

Диалоги по всем подключённым каналам с курсорной пагинацией. Без фильтра возвращает объединённый список.

get_messages(chat_id: string, limit?: number, before?: string)→ Message[]

История диалога в обратном хронологическом порядке. before — id сообщения для пагинации вглубь.

send_message(chat_id: string, text: string, reply_to?: string)→ Message

Отправка в существующий диалог. reply_to делает сообщение ответом на конкретное входящее.

start_chat(channel: Channel, to: string, text: string)→ Chat

Первое сообщение контакту, с которым переписки не было. to — телефон в E.164 или юзернейм.

mark_read(chat_id: string)→ void

Отмечает диалог прочитанным. Идемпотентно.

Контакты

search_contacts(query: string, channel?: Channel)→ Contact[]

Поиск по имени, телефону и юзернейму во всех каналах одним запросом. Совпадения дедуплицируются по контакту.

get_contact(contact_id: string)→ Contact

Карточка контакта: каналы связи, id диалогов, заметки, дата последнего сообщения.

resolve_contact(phone?: string, username?: string)→ ChannelAvailability[]

Проверка доступности до отправки: в каких каналах существует адресат. Экономит попытки и лимиты.

Медиа

send_media(chat_id: string, url?: string, base64?: string, caption?: string)→ Message

Изображение, документ или аудио. Источник — публичная ссылка либо base64. До 25 МБ на файл.

download_media(message_id: string)→ { url, mime, size }

Ссылка на входящее вложение, действительна 1 час. Скачивание не расходует лимит сообщений.

transcribe_voice(message_id: string)→ { text, duration }

Расшифровка голосового в текст. Русский и английский, автоопределение языка.

События и аккаунты

subscribe_events(webhook_url: string, channels?: Channel[], events?: EventType[])→ Subscription

Подписка на входящие. Без параметров — все события всех подключённых каналов.

list_accounts()→ Account[]

Подключённые каналы и состояние сессий. Используйте как health-check перед пакетной отправкой.

Заметки и календарь

create_note(chat_id: string, text: string)→ Note

Заметка к диалогу — видна человеку в интерфейсе 1-чата, в переписку не отправляется.

create_event(title: string, starts_at: string, chat_id?: string)→ Event

Событие в календаре. starts_at — ISO 8601 с таймзоной. chat_id связывает событие с диалогом.

Каналы

Поддержка инструментов по каналам

Различия накладывает платформа, а не наш API.

ИнструментTelegramTelegramWhatsApp*WhatsApp*MaxMaxInstagram*Instagram*
send_message
start_chatInstagram*: только в окне 24 часа после сообщения клиента.
send_mediaInstagram*: изображения, без документов.
transcribe_voiceMax: зависит от формата исходного аудио.
get_messagesInstagram*: история за последние 30 дней.
Групповые чаты
subscribe_events
поддерживается с ограничением платформы недоступно

REST API

Тот же слой без MCP

Если клиент не поддерживает MCP, обращайтесь к эндпоинтам напрямую с тем же ключом.

Аутентификация

Authorization: Bearer sk-1chat-...

Base URL — https://api.1-chat.ru/v1. Тело запросов и ответов — JSON. Ключ отзывается из кабинета мгновенно, вызовы фиксируются в журнале.

Эндпоинты

  • POST/v1/messagesОтправить сообщение или начать диалог
  • GET/v1/chatsСписок диалогов
  • GET/v1/chats/{id}/messagesИстория диалога
  • POST/v1/contacts/searchПоиск контактов по каналам
  • POST/v1/mediaОтправка вложения
  • POST/v1/webhooksПодписка на входящие события
  • GET/v1/accountsПодключённые каналы и статус сессий
POST /v1/messages
curl -X POST https://api.1-chat.ru/v1/messages \
  -H "Authorization: Bearer $ONECHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "telegram",
    "to": "+79991234567",
    "text": "Смета готова, отправляю файлом."
  }'
201 Created
{
  "id": "msg_01H9X2K4",
  "chat_id": "chat_tg_88213",
  "channel": "telegram",
  "direction": "outbound",
  "status": "sent",
  "created_at": "2026-08-05T09:14:02Z"
}

Webhooks

subscribe_events регистрирует URL, на который приходит POST по каждому входящему. Ответ 2xx подтверждает доставку, иначе событие повторяется с backoff в течение часа.

message.received
{
  "event": "message.received",
  "channel": "whatsapp",
  "chat_id": "chat_wa_41902",
  "message": {
    "id": "msg_01H9X31M",
    "text": "Здравствуйте, а на пятницу есть время?",
    "from": { "name": "Иван Петров", "phone": "+79991234567" },
    "has_media": false,
    "created_at": "2026-08-05T09:12:44Z"
  }
}

Коды ошибок

  • 401unauthorized

    Ключ неверный или отозван — выпустите новый.

  • 403channel_not_connected

    Канал не подключён к аккаунту либо не входит в скоуп ключа.

  • 409contact_unreachable

    Адресата нет в этом канале — проверьте через resolve_contact.

  • 422window_expired

    Истекло окно ответа платформы (Instagram*, 24 часа).

  • 429rate_limited

    Повторите через Retry-After секунд.

  • 503channel_unavailable

    Сессия канала переподключается — повторите с backoff.

Клиенты

Конфигурация под ваш агент

MCP — открытый стандарт: сервер работает в любом совместимом клиенте. Ниже готовые конфиги для распространённых.

Терминал, scope проекта или user

Claude Code
claude mcp add 1-chat \
  --env ONECHAT_API_KEY=sk-1chat-... \
  -- npx -y @1-chat/mcp
Подробная инструкция для Claude Code

Другой клиент — подключайтесь по HTTP

Любой MCP-совместимый агент работает с удалённым эндпоинтом https://mcp.1-chat.ru/mcp — локально ставить нечего.

Лимиты

Квоты и допустимое использование

РесурсЛимитОкно
Все запросы601 мин на ключ
Исходящие сообщения201 мин на канал
Первые сообщения новым контактам4024 ч на канал
Размер вложения25 МБна файл

Скоупы ключа

Ключ выпускается с правами read, write или обоими и ограничивается набором каналов. Агенту для отправки не нужен доступ к истории.

Поведение при 429

Ответ содержит Retry-After. Клиент MCP повторяет запрос сам с экспоненциальным backoff; при прямых вызовах REST это на вашей стороне.

Разгон новых контактов

Для аккаунта младше 7 дней лимит первых сообщений снижен и растёт постепенно. Так платформы не помечают аккаунт как рассылочный.

Допустимое использование

API предназначен для переписки с вашими клиентами и лидами. Рассылки по приобретённым базам нарушают условия использования и правила мессенджеров.

Сравнение

Чем отличается от официальных API

ВозможностьTelegram Bot APIWhatsApp Business API1-чат
Написать первымВ Business API — только шаблон в течение окна.
Свободный текст исходящихBusiness API требует утверждённых шаблонов.
Один интерфейс на 4 канала
Расшифровка голосовых
Готовый MCP-сервер

Сценарии

Типовые связки инструментов

Исходящие по своей базе

resolve_contact определяет доступный канал, start_chat открывает диалог. Без предварительного касания со стороны клиента.

resolve_contactstart_chat

Ответы на входящие

Webhook поднимает агента, get_messages отдаёт контекст, send_message возвращает ответ. Логика диалога остаётся у вас.

subscribe_eventsget_messagessend_message

Отправка документов

Сгенерированный PDF или изображение уходит ссылкой либо base64 в тот же диалог, где пришёл запрос.

send_media

Обработка вложений

Голосовое приходит агенту расшифровкой, файл — ссылкой на скачивание с ограниченным сроком жизни.

transcribe_voicedownload_media

Поиск по каналам

Один search_contacts вместо четырёх интеграций: результаты дедуплицируются по контакту, а не по мессенджеру.

search_contactslist_chats

Запись результата

Итог переписки возвращается в интерфейс 1-чата заметкой к диалогу и событием в календаре.

create_notecreate_event

Доступ

Тариф For Agentic

  • API-ключ и MCP-сервер
  • Все каналы: Telegram, WhatsApp*, Max, Instagram*
  • Webhook на входящие сообщения
  • Расшифровка голосовых
  • Журнал действий агента

14 дней бесплатно, без карты. Тариф не влияет на подписку основного приложения.

1 490 ₽/ мес

1 242 ₽/мес при оплате за год

Получить API-ключ

Документация

Страницы раздела

Каналы

Клиенты

Машиночитаемая версия для агентов — /llms.txt

Частые вопросы

Получите ключ и подключите агента

14 дней бесплатно, без карты. Ключ выпускается с нужными правами и отзывается в один клик.

Получить API-ключСмотреть на GitHub

Есть вопросы? Напишите нам в Telegram →