# 1-чат — MCP-сервер и API для мессенджеров

> MCP-сервер и REST API для работы с Telegram, WhatsApp, Max и Instagram из ИИ-агента:
> отправка и чтение сообщений, поиск контактов, вложения, webhook на входящие.
> Работает через пользовательский аккаунт, поэтому агент может написать контакту первым.

Пакет: @1-chat/mcp
Версия протокола MCP: 2025-06-18
HTTP-эндпоинт MCP: https://mcp.1-chat.ru/mcp
Base URL REST: https://api.1-chat.ru/v1
Репозиторий: https://github.com/one-chat/mcp-server
Выпуск ключа: https://app.1-chat.ru/settings/api
Стоимость: 1 490 ₽/мес, 14 дней бесплатно

## Подключение

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

Аутентификация REST: заголовок `Authorization: Bearer sk-1chat-...`
Тип 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 связывает событие с диалогом.

## Поддержка по каналам

- send_message: telegram=yes whatsapp=yes max=yes instagram=yes
- start_chat: telegram=yes whatsapp=yes max=yes instagram=partial (Instagram*: только в окне 24 часа после сообщения клиента.)
- send_media: telegram=yes whatsapp=yes max=yes instagram=partial (Instagram*: изображения, без документов.)
- transcribe_voice: telegram=yes whatsapp=yes max=partial instagram=no (Max: зависит от формата исходного аудио.)
- get_messages: telegram=yes whatsapp=yes max=yes instagram=partial (Instagram*: история за последние 30 дней.)
- Групповые чаты: telegram=yes whatsapp=yes max=yes instagram=no
- subscribe_events: telegram=yes whatsapp=yes max=yes instagram=yes

## REST-эндпоинты

- POST /v1/messages — Отправить сообщение или начать диалог
- GET /v1/chats — Список диалогов
- GET /v1/chats/{id}/messages — История диалога
- POST /v1/contacts/search — Поиск контактов по каналам
- POST /v1/media — Отправка вложения
- POST /v1/webhooks — Подписка на входящие события
- GET /v1/accounts — Подключённые каналы и статус сессий

## Коды ошибок

- 401 unauthorized — Ключ неверный или отозван — выпустите новый.
- 403 channel_not_connected — Канал не подключён к аккаунту либо не входит в скоуп ключа.
- 409 contact_unreachable — Адресата нет в этом канале — проверьте через resolve_contact.
- 422 window_expired — Истекло окно ответа платформы (Instagram*, 24 часа).
- 429 rate_limited — Повторите через Retry-After секунд.
- 503 channel_unavailable — Сессия канала переподключается — повторите с backoff.

## Лимиты

- Все запросы: 60 / 1 мин на ключ
- Исходящие сообщения: 20 / 1 мин на канал
- Первые сообщения новым контактам: 40 / 24 ч на канал
- Размер вложения: 25 МБ / на файл

При 429 ответ содержит заголовок Retry-After в секундах.
API предназначен для переписки с собственными клиентами и лидами;
рассылки по приобретённым базам нарушают условия использования.

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

- [MCP-сервер для Telegram](https://1-chat.ru/mcp/telegram): Пользовательский аккаунт вместо бота: полный набор инструментов без ограничений Bot API.
- [API и MCP для WhatsApp*](https://1-chat.ru/mcp/whatsapp): Свободный текст исходящих без утверждённых шаблонов и очереди на модерацию.
- [MCP-сервер для мессенджера Max](https://1-chat.ru/mcp/max): Российский мессенджер от VK с тем же набором инструментов, что и остальные каналы.
- [Подключение к Claude Code](https://1-chat.ru/mcp/claude-code): Установка одной командой, scope проекта или пользователя.
- [Подключение к Cursor](https://1-chat.ru/mcp/cursor): Конфигурация через mcp.json — на уровне проекта или пользователя.
- [Подключение к n8n](https://1-chat.ru/mcp/n8n): HTTP-транспорт: работает и в облачном n8n, без установки пакетов.
- [Раздел целиком](https://1-chat.ru/mcp): обзор, быстрый старт, справочник инструментов