Configure AI and the data assistant

On this page

Give the organization an AI connection, a fallback for when it fails, and control which data the chat assistant is allowed to talk about.

For: organization owners and admins. Before you start: you hold the manage_ai capability, which owners and admins carry by default.

Steps#

Open Settings > AI ("Cài đặt > AI") at /settings/ai.
Choose the AI source: inherit the platform's shared configuration, or use the organization's own API key. An organization key only takes effect once a valid configuration has been saved and tested.
Set the provider and model, then run Test connection before saving.
Add a backup connection under Backup connection. Connections are tried in order — the top one is primary, the ones below are fallback — and the platform automatically moves to the next one in the list when a connection or model fails or times out.
Open Settings > AI assistant ("Cài đặt > Trợ lý AI") at /settings/chat-assistant to name the assistant, write its greeting, and choose up to eight starter questions, plus a separate set for market-intelligence questions. Every choice here is scoped explicitly to one brand or to the whole organization; leaving a field blank always means the assistant infers it, never that nobody configured it.
Which data planes and measures the assistant may answer on is not a setting: it is inferred automatically from what the organization actually has connected, and narrows or widens itself as connectors are added or removed. A super admin can additionally set the organization's industry vocabulary — the advisory language and playbook the assistant draws from — at /admin/orgs/<slug>/chat-assistant; this is a platform-side default, not something an org owner or admin sets themselves.

Test connection succeeds for the primary connection.
The data assistant answers a question at /chat instead of showing "AI not ready".

Symptom	Likely cause	Fix
An insight card or the assistant shows "AI not ready"	The saved key can no longer be decrypted, usually after a machine change or an encryption-key rotation	Re-open Settings > AI and save the key again; the system recovers on the next run.
An insight job shows a waiting or retrying state instead of a result	The AI provider is slow or unresponsive	This is expected: a job has a time cap and is recreated instead of hanging forever; it clears once the provider responds.
The assistant will not answer about a data plane you know the organization has	The assistant only speaks to planes with actual data flowing in, resolved fresh on every request	Confirm the plane's connector is syncing; see Troubleshooting.
Nobody in the organization can reach `/settings/ai` or `/chat`	The role lacks `manage_ai`	A super admin can grant it to another role at `/admin/orgs/<slug>/roles`.
The briefing or an insight looks wrong and the cause is unclear	The underlying AI pipeline needs inspection	A super admin can use AI Debug at `/admin/ai/debug` to preview the exact prompt sent and run it manually against the configured model.