> ## Documentation Index
> Fetch the complete documentation index at: https://documents.xobito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Integration

> Connect your OpenAI account so Xobito's AI Prompts and AI composer can draft replies on your behalf.

Xobito doesn't ship its own AI model. To use [AI Prompts](/ai-features/ai-prompts) or the AI composer inside chat, you connect **your own OpenAI account**. You bring the key, Xobito calls OpenAI with it, and your agents get AI-drafted replies inside the inbox.

<Note>
  If you only plan to use [Canned Replies](/ai-features/canned-replies), you can skip this page — Canned Replies don't call an AI provider.
</Note>

## What's supported today

* **Provider:** OpenAI only. The settings page accepts an OpenAI secret key and talks to OpenAI's public API.
* **Models:** whichever models OpenAI returns for your account, filtered by the server-side `aimodel.models` allow-list. Model choice is a dropdown that only appears after your key has been verified.
* **Not supported right now:** Anthropic, Azure OpenAI, Google Gemini, Groq, Together AI, or any other OpenAI-compatible gateway. If you've seen older docs that said these were supported, those are out of date — the current Settings page only supports OpenAI's own API.

<Warning>
  **Your OpenAI API key is stored as plaintext** inside your workspace settings. Anyone with Owner/Admin-level database access to your workspace can read it. Treat this key like a password: scope it to this integration, set a low monthly usage cap on your OpenAI account, and rotate it if a staff member with that level of access leaves.
</Warning>

## Before you start

You'll need:

1. **An OpenAI account** — sign up at [platform.openai.com](https://platform.openai.com).
2. **Billing enabled** on that account — OpenAI rejects requests from accounts without a payment method or remaining credit.
3. **An API secret key** — create one at [platform.openai.com/api-keys](https://platform.openai.com/api-keys). Keep it visible in a password manager; OpenAI only shows the full key once.

<Warning>
  AI usage is billed by OpenAI directly, not by Xobito. Xobito does not meter, cap, or bill for AI calls. Set a **hard monthly usage limit** in your OpenAI dashboard before you connect — a bad prompt that calls the model in a loop can rack up cost quickly otherwise.
</Warning>

## Connect your OpenAI account

Go to **Settings → AI Integration**.

<Steps>
  <Step title="Enable AI in chat">
    Toggle **Enable OpenAI in chat** on. Until this is on, the AI composer button and AI Prompts are hidden from agents.
  </Step>

  <Step title="Paste your OpenAI secret key">
    In the **OpenAI Secret Key** field paste the key you created at platform.openai.com. Keys typically start with `sk-...`.
  </Step>

  <Step title="Save">
    Xobito immediately calls OpenAI's `GET /v1/models` endpoint with the key to verify it. If the call succeeds, your key is marked verified and the model dropdown populates.
  </Step>

  <Step title="Pick a chat model">
    The **Chat Model** dropdown lists the models your OpenAI account has access to (filtered to those Xobito's server config allows). Pick one. Common choices: `gpt-4o-mini` (cheap, fast), `gpt-4o` (higher quality, pricier).
  </Step>

  <Step title="Save again">
    Your chosen model is now used by AI Prompts and the AI composer across the workspace.
  </Step>
</Steps>

## Configuration fields

<ParamField path="enable_openai_in_chat" type="boolean" default="false">
  Master toggle. When off, AI features are hidden in the chat UI and AI Prompts cannot be run.
</ParamField>

<ParamField path="openai_secret_key" type="string">
  Your OpenAI API key (max 255 chars). Stored as plaintext in workspace settings — see the [security note](#security-considerations) below.
</ParamField>

<ParamField path="chat_model" type="string">
  The OpenAI model Xobito calls. Validated against the server's `config('aimodel.models')` allow-list — the dropdown only offers models that appear in both OpenAI's response and that list.
</ParamField>

## What happens when you save

On every save of the form, Xobito's `AiIntegrationSettings` Livewire component runs `listModel()`:

1. Calls OpenAI `GET /v1/models` using the key you provided.
2. If the response is a `200 OK` with a model list:
   * Sets `is_open_ai_key_verify = true` on your workspace.
   * Refreshes the **Chat Model** dropdown with the intersection of (models OpenAI returned) and (models allowed by Xobito's server config).
3. If the response is anything else (401, 403, 429, network error):
   * Leaves `is_open_ai_key_verify = false`.
   * Shows an error. The Chat Model dropdown stays empty.

<Note>
  Saving an **empty** or whitespace key disables AI for the workspace — the toggle is effectively forced off until a valid key is re-entered.
</Note>

## If key verification fails

| Symptom                                      | Likely cause                                                                 | Fix                                                                                             |
| -------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `401 Unauthorized`                           | Key is invalid, revoked, or missing a scope                                  | Create a fresh key at platform.openai.com/api-keys and paste again                              |
| `429 Too Many Requests` on save              | Your OpenAI account has hit a rate limit (unusual during save, but possible) | Wait a minute and save again                                                                    |
| Empty model dropdown after a successful save | Your account has no models in the Xobito server allow-list                   | Contact your Xobito administrator — the allow-list is in the server config `config/aimodel.php` |
| "Billing not active" type errors             | OpenAI account has no payment method, or monthly cap reached                 | Fix billing in your OpenAI dashboard, then save again                                           |
| Network / timeout on save                    | Outbound internet from the Xobito server can't reach `api.openai.com`        | Ask your administrator to check egress firewall rules                                           |

## Where your key is used

The saved key is used in two places:

* **[AI Prompts](/ai-features/ai-prompts)** — each prompt you build calls `openai_secret_key` + `chat_model` when an agent runs it from the composer.
* **AI composer in chat** — the inline "Draft with AI" control on a conversation uses the same key and model.

That's it. The key is **not** used for campaigns, templates, bots, or webhooks.

## What is *not* configurable here

Unlike some AI platforms, Xobito's AI Integration page has a deliberately small footprint. The following are **not available** on this settings page:

* **Temperature / creativity slider** — Xobito does not expose a workspace-wide temperature setting. Each AI Prompt runs with the model's defaults.
* **System prompt / persona field** — there's no global "you are a helpful support agent" field. Persona is authored **per prompt** in [AI Prompts](/ai-features/ai-prompts).
* **Fallback model** — if your chosen model is unavailable, the request fails. There is no automatic failover to another model.
* **Rate limits / cost guardrails** — Xobito does not cap, count, or bill AI calls. Use OpenAI's usage dashboard and monthly limits for guardrails.
* **Provider choice** — OpenAI only, as noted above.

If you need any of these, combine OpenAI's own controls (project-scoped keys, spending limits, organisation policies) with careful [AI Prompts](/ai-features/ai-prompts) authoring.

## Security considerations

<Warning>
  The OpenAI key is stored in plaintext in your tenant settings table. This is a product constraint you should plan around, not a bug.
</Warning>

Practical mitigations:

<AccordionGroup>
  <Accordion title="Use a dedicated, project-scoped OpenAI key">
    In the OpenAI dashboard, create a **project** just for Xobito and generate the key under that project. That way:

    * The key can't touch your other OpenAI workloads.
    * You can cap spend per project.
    * If the key leaks, revoking it doesn't break other integrations.
  </Accordion>

  <Accordion title="Set a monthly usage limit at OpenAI">
    In **OpenAI Dashboard → Limits**, set a hard monthly spend. This is your last line of defence against runaway prompts.
  </Accordion>

  <Accordion title="Rotate when database-privileged staff leave">
    Anyone with direct database access (DBA, hosting admin, root on the server) can read the plaintext key. When such a person leaves or changes role, generate a new OpenAI key, paste it in Xobito, save, and revoke the old one at OpenAI.
  </Accordion>

  <Accordion title="Restrict dashboard access">
    Only your workspace Owner / Admins can open **Settings → AI Integration**. Keep that role list short.
  </Accordion>

  <Accordion title="Audit OpenAI usage regularly">
    OpenAI's usage dashboard shows per-key calls. Review monthly for unexpected spikes.
  </Accordion>
</AccordionGroup>

## Rotating your key

<Steps>
  <Step title="Create a new key at OpenAI">
    platform.openai.com/api-keys → **Create new secret key**.
  </Step>

  <Step title="Paste it into Xobito">
    **Settings → AI Integration** → replace the OpenAI Secret Key value → **Save**.
  </Step>

  <Step title="Confirm verification">
    The page should show the model dropdown populated — that's your sign the new key works.
  </Step>

  <Step title="Revoke the old key at OpenAI">
    Back in OpenAI, delete the old key. AI Prompts and the AI composer continue running without a hiccup for your agents.
  </Step>
</Steps>

## Disabling AI

You have two options, depending on how hard the shut-off needs to be:

* **Soft disable** — toggle **Enable OpenAI in chat** off. The AI button disappears from the chat UI. The key is still stored; re-enabling restores AI immediately.
* **Hard disable** — clear the OpenAI Secret Key field and save. The key is removed from your workspace. Re-enabling AI means pasting a fresh key.

Canned Replies keep working in both cases.

## Troubleshooting

<AccordionGroup>
  <Accordion title="I saved a valid key but the model dropdown is empty">
    Your OpenAI account probably doesn't have access to any model that's also on Xobito's server allow-list. Check:

    1. In the OpenAI dashboard, confirm your project has at least one chat model enabled (e.g. `gpt-4o-mini`).
    2. Ask your Xobito administrator what's in `config/aimodel.php` — if it's restrictive, they may need to add the model.
  </Accordion>

  <Accordion title="Agents see 'AI unavailable' in the composer">
    Either the master toggle is off, the stored key failed verification (`is_open_ai_key_verify=false`), or no `chat_model` is saved. Open **Settings → AI Integration** and re-save to re-verify.
  </Accordion>

  <Accordion title="AI Prompts fail with 401 after working fine yesterday">
    Your OpenAI key was revoked, rotated elsewhere, or exceeded a usage cap. Check the OpenAI dashboard first, then paste a fresh key.
  </Accordion>

  <Accordion title="AI Prompts fail with 429">
    OpenAI is rate-limiting you. Either wait it out, upgrade your OpenAI usage tier, or switch `chat_model` to a less-saturated model (e.g. from `gpt-4o` to `gpt-4o-mini`).
  </Accordion>

  <Accordion title="My bill at OpenAI spiked">
    Check **AI Prompts → Usage** in Xobito for a prompt that's being run far more than others. Buggy prompt logic (e.g. one that recurses into long outputs) is the usual cause. Disable the suspect prompt and investigate.
  </Accordion>

  <Accordion title="I want to use a different provider (Anthropic, Azure, etc.)">
    Not supported in the current build. The AI Integration settings form hard-codes an OpenAI flow. If the product adds multi-provider support, you'll see new fields on this page.
  </Accordion>
</AccordionGroup>

## What to read next

<CardGroup cols={2}>
  <Card title="AI Prompts" icon="sparkles" href="/ai-features/ai-prompts">
    Build the prompts that your OpenAI key powers.
  </Card>

  <Card title="Canned Replies" icon="clipboard" href="/ai-features/canned-replies">
    The non-AI alternative — no key, no cost, no provider.
  </Card>
</CardGroup>