AI Provider Setup (BYOK)
Threadline is bring-your-own-key: you connect your own OpenAI, Anthropic, or Google Gemini account, and Threadline talks to that provider directly on your behalf. There's no subscription to us and no markup on your AI usage — you pay the provider directly, at their published rates, for exactly what you use.
Two separate roles
Threadline uses AI for two different jobs, and you choose a provider for each independently under Configuration → Integrations → AI:
| Role | What it does | Available providers |
|---|---|---|
| Chat provider | Writes the actual reply sent to your customer | OpenAI, Anthropic, or Google Gemini |
| Embedding provider | Turns your knowledge base content and each incoming question into vectors, so Threadline can find the most relevant chunks to answer from | OpenAI or Google Gemini only |
Why can't I use Anthropic for embeddings? Anthropic (Claude) doesn't offer an embeddings API at all. If you want Claude for chat, you still need an OpenAI or Gemini key for embeddings — Threadline's settings page enforces this and won't let you pick a provider for either role until it has a working key.
Changing your Chat or Embedding provider/model later
Switching your Chat provider or model any time is completely safe — every reply uses whichever one is currently active, with nothing pinned from before.
Your Embedding choice works differently, because it's baked into how every Knowledge Base's content is stored and searched:
Existing Knowledge Bases are not affected by this change. Each Knowledge Base permanently remembers the embedding provider/model it was created with, and keeps using that one forever for both new content and answering questions — regardless of what you later pick here. Changing this setting only decides which provider/model a brand-new Knowledge Base gets when someone creates one after the change.
There is exactly one way an existing Knowledge Base stops accepting new content after this: if you remove (or never configure) the API key its own original provider needs. In that case it shows as Frozen on the Knowledge Base list — everything already in it keeps answering questions normally on every channel, but no new document, text, URL, photo, or table can be added until that provider's key is restored. Keep the key for any provider an existing Knowledge Base still depends on, even after you've moved your default to something else.
Want to actually move an existing Knowledge Base onto a different embedding model on purpose (e.g. a cheaper or more accurate one)? That means re-embedding every document in it from scratch, which is billed again at the new model's rate — it's not free and not automatic just because you changed this setting.
Voice notes
Customers can send voice notes on WhatsApp, Telegram, Messenger and Instagram. Voice notes (below the chat provider) chooses who listens and writes down what was said, so the AI and your team can read it.
- Automatic (default): your chat provider when it is OpenAI or Google Gemini, otherwise whichever of the two has a key.
- OpenAI or Google Gemini: always that one. Anthropic and OpenRouter cannot transcribe.
- Off: the audio is kept and playable, and the customer is asked to type.
Each call is logged under AI Usage as transcription, with its tokens. Its cost is not priced, because providers bill audio by length. Notes longer than about five minutes are kept but not transcribed.
Getting an API key
| Provider | Where to get a key |
|---|---|
| OpenAI | platform.openai.com/api-keys — you'll need billing set up on the account (a card on file); OpenAI doesn't run API usage on a free trial balance indefinitely. |
| Anthropic | console.anthropic.com/settings/keys — also requires billing/credits on the account. |
| Google Gemini | aistudio.google.com/apikey — Google AI Studio offers a free tier with rate limits before you need to enable billing. |
Entering your key in Threadline
Configuration → Integrations → AI has two tabs. Providers and models has one card per provider with everything about it: its key, the Allow this provider switch, its last error and its models. What answers is where you choose which provider and model do the work. Each AI row on the Integrations page opens its provider's card directly.
- Go to Configuration → Integrations → AI, tab Providers and models.
- On the provider's card, paste the key into API key and click Save on that card.
- Open What answers, choose your Chat provider, Embedding provider and models, and click Save. Only providers with a key that are switched on can be chosen.
Once saved, a key is never shown again in full — the field shows only its last 4 characters (e.g. "Currently ••••a1b2") so you can confirm which key is active without it being readable by anyone who glances at your screen. Leaving a key field blank on a later visit keeps the existing key; you only need to type into a field when you're actually changing that key.
Don't remove a provider's key once it's set. If you want to try or switch to a different provider, save its key alongside the one(s) you already have — don't clear an existing key first. Every provider's key is stored independently, so having more than one saved at a time is completely normal, not something to clean up. Removing a key that's no longer your active Chat/Embedding choice can still break things quietly: any existing Knowledge Base created under that embedding provider depends on its key forever (see Changing your Chat or Embedding provider/model later), and you'd also lose the option to switch back without re-entering it. If you're testing a new provider, just add its key and switch the dropdown — leave the old key exactly where it is.
The "this key failed on its last use" banner
If a real chat request to a provider fails because the key was rejected (revoked, mistyped, or removed on the provider's side), Threadline records that and shows an amber warning right on this settings page, next to the affected key — you don't have to go digging through logs to find out your bot stopped answering because of a bad key. Saving a new key for that provider, or any later request that succeeds, clears the banner automatically. See Troubleshooting & FAQ for what else can go wrong here (quota exceeded, provider outages).
Cost control
Reports → Usage shows token usage and an estimated cost breakdown by provider and day, computed from each provider's published pricing at the time of your last update. Set your own spending limits/alerts directly on your OpenAI/Anthropic/Google account — Threadline doesn't cap spending itself, since it never sees your billing details, only the API responses.
Models and your own providers
Each provider's card on Providers and models lists every model it offers. The models that come with the app are kept up to date by each update; your own additions are kept separately and survive every update.
-
Add model: type the model ID exactly as the
provider names it (a newer model, or a fine-tune such as
ft:gpt-4o-mini:acme). It is tried with a real request before it is saved. Whether a chat model can see images is measured (it is shown a red square and must say "red"), and an embedding model's size is read from its answer, so neither is ever guessed. A model the provider rejects is not saved. Enter its prices so cost estimates and each plan's AI cost limit stay right. - Offered: switch a model off to remove it from every picker (yours and workspaces'). Anything already using it keeps working. The model you answer with cannot be hidden.
- Connect a provider: any provider whose API works like OpenAI's Chat Completions (Groq, DeepSeek, Mistral, xAI, Together, Fireworks, or your own Ollama or vLLM server). Give it a name, a short ID (fixed once saved), its base URL and key, then add its models. It then appears in every provider list, including workspaces' own-key settings.
- A model or provider still in use (by your settings, the translation tool, a workspace's own key or a knowledge base) cannot be removed; the page says where it is used.
Letting workspaces use their own key
The keys on this page are yours, and by default every workspace answers with them. A plan can instead let (or require) its workspaces to add their own key under Settings → AI: set AI keys on the plan (see Subscription Plans). Only the providers you allow here can be chosen by a workspace. A workspace's own key, its errors and its spending never touch your keys or your cost cap.