# TukTuk (tuk-tuk.online)

> Облачный шлюз к мессенджерам для людей и для программ. Хранит подключения к Telegram (боты и личные аккаунты), VK, Instagram Direct, Авито, MAX, Email (SMTP/IMAP), SMS через Android-шлюз, чат-виджету для сайта и входящим вебхукам. Отправляет и принимает сообщения, держит историю переписки, выполняет отложенные действия, ведёт рассылки, автоматические сценарии и автопостинг. Всё доступно по REST API под ключом со scopes.

Кабинет: https://lk.tuk-tuk.online · API: https://back.tuk-tuk.online/api/v1 · Документация: https://docs.tuk-tuk.online

## Зачем это ИИ-агенту

Агент умеет думать, но не умеет держать соединение с Telegram неделями, пережить собственный перезапуск, дождаться завтрашнего утра и гарантировать доставку. TukTuk берёт это на себя:

- хранит подключения и токены площадок, своего сервера пользователю не нужно;
- доставляет сообщения с учётом лимитов площадок, ретраев и статусов;
- выполняет отложенные действия: отправка на конкретное время, рассылки по окну, зациклённые воронки автопостинга;
- помнит историю переписки, теги и произвольные поля клиента;
- присылает входящие события на ваш URL вебхуком, поллинг не нужен.

## Начало работы

- [Регистрация](https://lk.tuk-tuk.online/register): бесплатный тариф, подтверждение почты не требуется.
- Ключ API: кабинет, Настройки проекта, вкладка API. Формат `tuk_sk_…`, показывается один раз.
- Проверка ключа: `GET https://back.tuk-tuk.online/api/v1/me` с заголовком `Authorization: Bearer tuk_sk_…`
- Что доступно этому ключу: `GET https://back.tuk-tuk.online/api/v1/manifest`
- Спецификация: [openapi.json](https://back.tuk-tuk.online/api/v1/openapi.json)

## MCP-сервер

- Команда: `npx -y https://docs.tuk-tuk.online/mcp/tuktuk-mcp.tgz`
- Переменные окружения: `TUKTUK_API_KEY` (обязательно), `TUKTUK_API_URL` (по умолчанию https://back.tuk-tuk.online/api/v1)
- Манифест: [mcp.json](https://tuk-tuk.online/mcp.json)
- Инструменты появляются по правам ключа: отправка и отложенная отправка, контакты, история, файлы, рассылки, связки, воронки, ассистенты, задачи, подписки на события.

## Что умеет API

- Каналы: `GET /api/v1/messengers`, список подключений со статусом. Секреты каналов не отдаются.
- Контакты: `GET|POST /api/v1/contacts`, `PATCH /api/v1/contacts/{id}`, теги, произвольные поля, статусы, заметки.
- История: `GET /api/v1/contacts/{id}/messages`, вложения и расшифровки голосовых.
- Отправка: `POST /api/v1/messages`, текст, медиа, голосовое, письмо. Адресация по контакту, телефону, email или идентификатору канала.
- Отложенная отправка: `POST /api/v1/messages/schedule`, момент отправки держит платформа.
- Файлы: `POST /api/v1/files`, забирает файл по ссылке в постоянное хранилище.
- Рассылки: `/api/v1/broadcasts`, сегмент по тегам и активности, темп, окно времени, отчёт по каждому получателю.
- Связки: `/api/v1/chains`, сценарии на входящее сообщение с ветвлениями, задержками, ИИ и вебхуками.
- Воронки автопостинга: `/api/v1/funnels`, сторис и посты по расписанию, в том числе зациклённые.
- ИИ-ассистенты: `/api/v1/assistants`, включение, настройка, пауза в конкретном диалоге.
- Задачи: `/api/v1/tasks`.
- События: `/api/v1/events/subscriptions`, вебхуки о входящих сообщениях и других событиях, подпись HMAC-SHA256.

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

- [Оглавление для нейросетей](https://docs.tuk-tuk.online/llms.txt)
- [Вся документация одним файлом](https://docs.tuk-tuk.online/llms-full.txt)
- [REST API](https://docs.tuk-tuk.online/api/rest.md)
- [Вебхуки событий](https://docs.tuk-tuk.online/api/webhooks.md)
- [Каналы связи](https://docs.tuk-tuk.online/channels.md)
- Любая страница документации доступна как Markdown: тот же адрес плюс `.md`

## Границы и безопасность

- Вход в API только по ключу, который выдал владелец рабочего пространства.
- У ключа есть scopes, срок действия, список разрешённых IP и лимит запросов в минуту.
- Ключ видит только своё рабочее пространство, чужой идентификатор возвращает 404.
- Через API нельзя выпускать ключи, платить, менять тариф и управлять правами.
- Все изменения пишутся в журнал аудита рабочего пространства.