# Подключение Gemini Spark Source: Locale: ru releaseGitSha: c9a428d902de0b479a981e43774f38b9ec077ed7 sourceContentDigest: 5fe94106e6f6b6981acd5637f1aff04f86f781b37ef55ea1f696d0184593ce31 Version: 1 Подключение даёт вашему агенту доступ к AI-фронт-офису в Telegram в пределах ваших прав. Нужны аккаунт выбранного клиента, Telegram для входа человека и доступный HTTPS endpoint. Настройка Spark сверена с официальными источниками 2026-10-01; успешный ручной проход этого хоста и его конкретная версия здесь не заявлены. ## Настройка Google документирует подключение custom apps по MCP URL для Gemini Spark; эта возможность отмечена в [обновлении от 29 июня 2026](https://support.google.com/gemini/answer/17171264?hl=en). Для custom apps нужны возраст от 18 лет, нахождение в США, личный Google-аккаунт и включённый Keep Activity. Рабочие и учебные аккаунты не поддерживаются; функция доступна только на английском. 1. Откройте [веб-приложение Gemini](https://gemini.google.com). 2. Перейдите в Settings → Connected Apps; если пункта нет, откройте Personal Intelligence → Connected Apps. 3. В разделе Custom apps добавьте приложение с MCP URL `https://mcp.telegafirst.com/api/v1/mcp`. 4. Нажмите Next и следуйте экранным шагам авторизации. Для обращения к подключённому приложению в запросе введите `@` и выберите его. Добавление custom app выполняется только в веб-приложении; после подключения им можно пользоваться в веб- и мобильном Gemini. Эти шаги не подтверждают custom MCP в приложении для Mac или успешное подключение TelegaFirst в вашей сессии. [Официальная инструкция Google](https://support.google.com/gemini/answer/17209137?co=GENIE.Platform%3DDesktop\&hl=en). ### Отдельная альтернатива: Gemini CLI Gemini CLI — другой продукт, это не подтверждение Spark. Его официальная документация описывает Streamable HTTP через `httpUrl` и OAuth: ```json {"mcpServers":{"telegafirst":{"httpUrl":"https://mcp.telegafirst.com/api/v1/mcp","trust":false}}} ``` В Gemini CLI используйте `/mcp auth telegafirst` и браузерный вход. [Документация Gemini CLI](https://geminicli.com/docs/tools/mcp-server/). Если custom apps недоступны вашему аккаунту или выбранному интерфейсу Spark, используйте другой поддерживающий клиент или [независимый curl-сценарий](https://telegafirst.com/docs/curl-device-grant). ## Discovery и согласие Следующие шаги описывают протокол TelegaFirst после добавления custom app в поддерживаемом веб-интерфейсе Spark или настройки отдельного Gemini CLI. Документированный путь Spark не подтверждает завершённый OAuth или успешный вызов в вашей сессии. Используйте canonical endpoint `https://mcp.telegafirst.com/api/v1/mcp` с Streamable HTTP. При первом неавторизованном запросе сервер возвращает HTTP 401 с `WWW-Authenticate`; клиент получает OAuth discovery и открывает вход. Подтвердите показанное согласие в Telegram от своего имени. Отказ завершает вход, а не создаёт обходной API key. Подробности и различия credentials — [авторизация](https://telegafirst.com/docs/authorization). ## Инструменты и бизнес После OAuth обновите `tools/list`. У нового владельца без бизнеса доступны три dedicated-инструмента: `get_onboarding_state`, `check_slug_availability` и `claim_slug`, а также пять scoped meta-tools: `search_admin_tools`, `load_domain`, `describe_tool`, `execute_admin_read` и `execute_admin_write`. До создания бизнеса их targets ограничены состоянием, проверкой адреса и claim своего бизнеса; документационные MCP-инструменты пока недоступны. Сначала прочитайте состояние и `body.entry_context`, согласуйте адрес и язык, затем выполните claim. Следуйте `response.next_action` и проверкам готовности, а после их изменения снова обновите список. До появления бота не требуйте identity или каталог. Полный порядок — [новый бизнес](https://telegafirst.com/docs/getting-started#new-business). Для существующего бизнеса проверьте доступные бизнесы, их `role` (`owner` или `operator`) и активный контекст. Если нужен другой, переключайте общий контекст человека только разрешённым инструментом и снова читайте `tools/list`; это меняет контекст и в других подключениях. API key без человека не переключает этот указатель. Порядок — [существующий бизнес](https://telegafirst.com/docs/getting-started#existing-business). ## Каталог и результат Когда readiness, scope `catalog:read` и тариф допускают чтение, вызовите `get_catalog` с `{"limit":10,"zone":"ru"}`. Результат — страницы вашего каталога с внешними номерами; пустой каталог тоже допустим. Не придумывайте позиции и не считайте схему инструмента успешным вызовом. Если dedicated tool не установлен, discovery через `load_domain`/`describe_tool` не добавляет его автоматически: используйте существующий meta-dispatch согласно [MCP-руководству](https://telegafirst.com/docs/mcp-guide). Подключение подтверждено для вашей сессии только после успешного вызова и проверки нужного бизнеса. Чтение каталога не разрешает денежные операции; для записи нужны отдельные права. Номера объектов принадлежат активному бизнесу и не используются в анонимных публичных ссылках. ### Контрактный пример состояния Сокращённая обезличенная проекция `get_onboarding_state` до первого бизнеса. Это пример серверного контракта, а не запись успешного входа из данного хоста. Текст `response.next_action.say_to_user` и подсказки `hint` опущены; реальный ответ используйте целиком. ```json {"tenant":{"slug":null,"bot_username":null},"active_slug":null,"stage":"address","status":"todo","next_action":{"goal":"address","collect":[{"field":"slug"},{"field":"language"}]},"body":{"entry_context":{"intent":"auto","active_business":null,"owned_businesses":[],"recommended_business_slug":null,"action":"create_business"},"completedSteps":[],"site_operation":null,"language":"ru"}} ``` После `claim_slug` следующий шаг определяется новым ответом; опубликованный сайт сам по себе не означает готовый бот. При попытке сменить уже выданный адрес сервер возвращает `SLUG_IMMUTABLE`; сохраните исходный адрес и продолжайте readiness. ## Если подключение не удалось При HTTP 401 пройдите вход заново; при отказе прав проверьте consent, live роль и выбранный бизнес. При `PLAN_UPGRADE_REQUIRED` проверьте тариф и открытое оплаченное окно. Если инструмента нет, обновите список и readiness; не подменяйте вход токеном другого приложения. Сбой установки на неподдерживающем клиенте не исправляется одним промптом. [Коды ошибок](https://telegafirst.com/docs/errors), [права и scopes](https://telegafirst.com/docs/scopes-and-permissions), [curl-диагностика](https://telegafirst.com/docs/curl-device-grant). ## Продолжение настройки с агентом Полное описание платформы: `https://mcp.telegafirst.com/llms-full.txt`. После подключения прочитайте нужный навык через MCP и подтвердите актуальный пакет через `ack_skills`, когда этого требует сервер. Первое действие агента — `get_onboarding_state` с `intent: auto`. Проверьте выбранный бизнес и используйте текущий `response.next_action`: расскажите человеку `next_action.say_to_user`, запросите только отсутствующие поля из `next_action.collect`, выполните разрешённый `next_action.execution.tool` с известными `next_action.execution.arguments`. Учитывайте `next_action.execution.executor`: агент выполняет только действия для `agent`, для `owner` показывает точную инструкцию человеку, для `server` ждёт по выданным условиям. Продолжайте через `next_action.execution.continue_with`, если оно задано. Если не хватает прав, покажите предусмотренное восстановление доступа. После действия проверьте результат и снова прочитайте состояние; ожидание и повтор выполняются по серверной инструкции. Этот текст не задаёт отдельный порядок шагов. Токен собственного Telegram-бота можно передать агенту для авторизованного `register_existing_bot` через поле `params.arguments.bot_token` его MCP-запроса. Если сервер предлагает продолжить уже начатое подключение, используйте `resume_bot_connection` с пустыми аргументами. Приём токена не доказывает подключение: `connected: true` появляется только после завершения серверного процесса. Учётные данные платёжного провайдера также передаются через предусмотренный типизированный инструмент выбранного бизнеса. Агент не повторяет секреты в ответах и не сохраняет их в документах, URL или отчётах. Авторизация самого MCP-коннектора остаётся в настройках приложения. Для тестового товара нужны полная карточка и отдельное полное сообщение доставки. Поддерживаются текст, фото, видео, PDF, другие допустимые документы, несколько файлов и допустимые альбомы; фото необязательно. Возможность прочитать вложение, получить HTTPS-ссылку или отправить точные байты проверяется в вашем приложении. Импорт через `media_import_files`, загрузка через `media_request_upload` → HTTP PUT → `media_finalize`, проверка `media_get_status` и переход к вебу/Mini App описаны в [руководстве по файлам](https://telegafirst.com/docs/connect-media). В контент передаются только подтверждённые постоянные mediaRefs. Агент не придумывает ссылку и не обещает доставку без проверки. Для первой живой оплаты сервер может предложить `onboarding_prepare_first_payment` и `onboarding_execute_first_payment`; нужны одновременно `catalog:write AND payments:config`. Агент показывает подготовленные условия и получает явное подтверждение владельца перед исполнением. Подтверждение цены активирует существующий товар для покупки; публичная видимость настраивается отдельно. Для нативных Stars/CryptoBot зона покупки `.ru` или `.com` выбирается явно, а не по языку; для PayPal явно выбирается окружение. Минимальную сумму определяет провайдер. Подтверждение владельцем настроек callback и подписи не доказывает доставку настоящего callback, проверку его подписи или живую оплату. Отправленная карточка товара также не означает оплату или начисленный бонус: эти факты проверяются сервером. После короткого отвлекающего вопроса агент возвращается к текущему шагу. По просьбе остановиться он прекращает работу. Для завершения сохраните ответы об устройстве, приложении ИИ и платной или бесплатной подписке, затем выполните доступное отдельное действие `onboarding_complete`. Только подтверждённое сервером `journey.completed` завершает настройку и выключает её сопровождение. Открытие ссылки, копирование промпта и закрытие окна завершением не считаются.