Для AI-агентов: markdown этой страницы — /docs-content/partner-connect/ai-in-app.md индекс документации — /llms.txt

Подключение AI из приложения внутри Битрикс24

Приложение, которое открывается во фрейме портала Битрикс24, не может показать у себя страницу согласия: страница согласия запрещает встраивание в чужие сайты заголовками X-Frame-Options: SAMEORIGIN и Content-Security-Policy: frame-ancestors 'self'. Так её нельзя подменить или спрятать под чужим интерфейсом. Поэтому кнопка «Подключить AI» открывает согласие в отдельном окне браузера, а фрейм ждёт результат от вашего сервера.

Как это устроено

  1. Кнопка во фрейме открывает окно на адресе вашего сервера и передаёт в нём одноразовый идентификатор попытки ticket.
  2. Сервер запоминает попытку и перенаправляет окно на /v1/connect/authorize с правом vibe:ai.
  3. Пользователь выбирает портал и подтверждает доступ. Вайбкод возвращает окно на ваш redirect_uri.
  4. Сервер обменивает код на ключ, отмечает попытку завершённой и закрывает окно.
  5. Фрейм опрашивает сервер по ticket и показывает результат.

Код во фрейме приложения

html
<button id="connect-ai" type="button">Подключить AI</button>
<p id="connect-ai-status" role="status"></p>

<script>
  const button = document.getElementById('connect-ai')
  const statusLine = document.getElementById('connect-ai-status')

  button.addEventListener('click', () => {
    // Окно открывается прямо в обработчике клика: окно, открытое после await, браузер блокирует
    const ticket = crypto.randomUUID()
    const popup = window.open(
      `/connect/ai/start?ticket=${ticket}`,
      'vibe-connect-ai',
      'popup,width=640,height=760',
    )
    if (!popup) {
      statusLine.textContent = 'Разрешите всплывающие окна для этого приложения и нажмите кнопку ещё раз'
      return
    }
    statusLine.textContent = 'Подтвердите доступ в открывшемся окне'
    waitForResult(ticket)
  })

  async function waitForResult(ticket) {
    const deadline = Date.now() + 10 * 60 * 1000 // 10 минут на согласие
    while (Date.now() < deadline) {
      await new Promise((resolve) => setTimeout(resolve, 2000))
      const res = await fetch(`/connect/ai/status?ticket=${ticket}`)
      const result = await res.json()
      if (result.status === 'ok') {
        statusLine.textContent = 'AI подключён'
        return
      }
      if (result.status === 'denied') {
        statusLine.textContent = `AI не подключён: ${result.reason}`
        return
      }
    }
    statusLine.textContent = 'Подключение не завершено. Нажмите кнопку ещё раз'
  }
</script>

Код сервера

Сервер приложения делает тот же обмен кода, что в полном примере, и хранит состояние попытки для фрейма. db и encrypt — ваши хранилище и шифрование. Адрес https://yourapp.com/connect/ai/callback зарегистрируйте у клиента как redirect_uri, а право vibe:ai должно входить в права клиента — см. Платформенные права.

javascript
import express from 'express'
import crypto from 'node:crypto'

const app = express()
const attempts = new Map() // ticket → результат попытки; в продакшене — Redis или БД
const states = new Map() // state → ticket

const CLIENT_ID = process.env.PARTNER_CLIENT_ID
const CLIENT_SECRET = process.env.PARTNER_CLIENT_SECRET
const REDIRECT_URI = 'https://yourapp.com/connect/ai/callback'
const TICKET_RE = /^[0-9a-f-]{36}$/

// 1. Окно, открытое кнопкой, приходит сюда и уходит на страницу согласия
app.get('/connect/ai/start', (req, res) => {
  const { ticket } = req.query
  if (typeof ticket !== 'string' || !TICKET_RE.test(ticket) || attempts.has(ticket)) {
    return res.status(400).send('Некорректная попытка подключения')
  }
  attempts.set(ticket, { status: 'pending' })

  const state = crypto.randomBytes(16).toString('hex')
  states.set(state, ticket)

  const params = new URLSearchParams({
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    scope: 'vibe:ai',
    state,
  })
  res.redirect(`https://vibecode.bitrix24.tech/v1/connect/authorize?${params}`)
})

// 2. Вайбкод возвращает окно сюда после согласия или отказа
app.get('/connect/ai/callback', async (req, res) => {
  const { code, state, error, error_description: reason } = req.query
  const ticket = states.get(state)
  if (!ticket) return res.status(400).send('Неизвестный state')
  states.delete(state)

  if (error) {
    // error_description несёт машинный код причины — см. «Отказ после экрана согласия»
    attempts.set(ticket, { status: 'denied', reason: reason ?? error })
    return res.send(closeWindowPage('Доступ не выдан. Окно можно закрыть'))
  }

  const tokenRes = await fetch('https://vibecode.bitrix24.tech/v1/connect/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'authorization_code',
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      code,
      redirect_uri: REDIRECT_URI,
    }),
  })
  const data = await tokenRes.json()
  if (!tokenRes.ok) {
    attempts.set(ticket, { status: 'denied', reason: data.error })
    return res.send(closeWindowPage('Ключ не получен. Окно можно закрыть'))
  }

  await db.connections.upsert({
    portalDomain: data.portal.domain,
    apiKey: encrypt(data.api_key), // секрет, шифруем перед хранением
    scopes: data.granted_scopes ?? data.scopes,
  })
  attempts.set(ticket, { status: 'ok' })
  res.send(closeWindowPage('AI подключён. Окно можно закрыть'))
})

// 3. Фрейм спрашивает результат попытки
app.get('/connect/ai/status', (req, res) => {
  res.json(attempts.get(req.query.ticket) ?? { status: 'unknown' })
})

function closeWindowPage(text) {
  return `<!doctype html><meta charset="utf-8"><p>${text}</p><script>window.close()</script>`
}

Что важно

  • Окно открывается синхронно в обработчике клика. Окно, открытое после await, браузер блокирует как всплывающее.
  • Результат фрейм берёт у своего сервера по ticket, а не у окна: окно уходит на другие сайты, и опрос своего сервера не зависит от того, что с окном происходит по дороге.
  • ticket — не секрет: по нему видно только состояние попытки. Ключ остаётся на сервере и во фрейм не попадает.
  • Опрос ограничен по времени: пользователь может закрыть окно, не ответив, и тогда на redirect_uri не придёт ничего.
  • Отказ приходит в error и error_description, фрейм показывает код причины как есть. Разбор кодов — Отказ после экрана согласия.

Смотрите также