Для 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» открывает согласие в отдельном окне браузера, а фрейм ждёт результат от вашего сервера.
Как это устроено
- Кнопка во фрейме открывает окно на адресе вашего сервера и передаёт в нём одноразовый идентификатор попытки
ticket. - Сервер запоминает попытку и перенаправляет окно на
/v1/connect/authorizeс правомvibe:ai. - Пользователь выбирает портал и подтверждает доступ. Вайбкод возвращает окно на ваш
redirect_uri. - Сервер обменивает код на ключ, отмечает попытку завершённой и закрывает окно.
- Фрейм опрашивает сервер по
ticketи показывает результат.
Код во фрейме приложения
<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 должно входить в права клиента — см. Платформенные права.
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, фрейм показывает код причины как есть. Разбор кодов — Отказ после экрана согласия.