Skip to content

Bring Your Own Gemini Key (BYOK)

Use your organization's own Google Gemini API key instead of ConnectGain AI for any or all AI features.

Why BYOK?

  • Zero ConnectGain AI cost — Google bills you directly.
  • Data residency / compliance — calls go from our edge functions straight to Google.
  • Higher quota if your Google account has a paid Gemini plan.

1. Get a key

  1. Go to Google AI Studio.
  2. Click Create API key and copy the value (it starts with AIza…).

2. Paste it in ConnectGain

  1. Navigate to Settings → AI & Automation → AI Provider.
  2. Select My Google Gemini key (BYOK).
  3. Paste the key, choose a model (gemini-2.5-flash recommended).
  4. Pick a scope:
  5. All AI features — chatbots, classification, internal assistant, web assistant, translations, auto-tag, call analysis, re-engagement.
  6. Re-engagement only — only the AI Re-Engagement add-on uses your key; everything else stays on ConnectGain AI.
  7. Decide on the fallback toggle:
  8. On (default): if your key returns 401 / 403 / 429, ConnectGain AI handles that request so your operations don't stop. You see a warning banner.
  9. Off: the AI feature returns an error and the UI explains what to fix. Use this if you must guarantee that data only ever leaves through your key.
  10. Click Test key. A green badge confirms it works.

3. Supported models

  • gemini-2.5-flash (default — best price/perf, recommended)
  • gemini-2.5-pro (heavier reasoning)
  • gemini-2.5-flash-lite (cheapest, simple classification)

Gemini 3.x models (3.5-flash, 3.5-pro, 3.1-flash-lite) are intentionally not supported. They are agentic/thinking models that don't reliably follow the JSON-output prompts our AI features (re-engagement, classification, auto-tag, analyze-conversation, etc.) rely on.

Security model

  • The key is encrypted at rest using AES-GCM with a per-deployment BYOK_ENCRYPTION_KEY.
  • It is never returned to the browser. The UI only shows a masked preview (AIza••••1234).
  • Only OWNER / ADMIN can set, change, or clear the key.
  • Every set / clear / scope-change / validation is audited.
  • Sentry breadcrumbs scrub the key and message body.

Billing

  • Google bills the account that owns the key.
  • The ConnectGain AI Re-Engagement add-on ($20/mo) is unaffected — it's an orchestration fee, not an AI fee.
  • Cancelling the add-on stops the scanner; your key remains configured for other AI features.

Troubleshooting

Symptom Cause Fix
invalid badge Key revoked or typo Generate a new key and paste again
quota badge Free tier rate-limited Upgrade Google billing or enable fallback
network badge Transient Google outage Retry; fallback handled it if enabled
Re-engagement uses ConnectGain AI even though BYOK is on Scope set to "Re-engagement only" — that's correct, but check the right feature n/a
AI feature errors after key revoked + fallback off Expected Re-enable fallback or paste a new key

How to switch back

Settings → AI & Automation → AI Provider → ConnectGain AI (default) → Save. Your key is cleared from the encrypted store.