Skip to content
MeridFlow AiFlow v8.x • self-hosted

Credentials

AiFlow is self-hosted, so there's nothing to sign up for with us. Your deployment still talks to a handful of outside services on your behalf, each under your own account and your own credentials. This page walks through getting every one of them, so you have everything ready before, or while, your deployment gets set up. It doesn't matter which deployment method you use (Docker Compose, Coolify, or a bare VPS): all of them read the same credentials from the same environment variables.

What you'll need

Credential Unlocks Required
Gemini API key The voice, video, and text conversation engine itself Yes
Twilio Inbound and outbound phone calls Only for the phone channel
WhatsApp WhatsApp messaging (builds on Twilio) Only for WhatsApp
Resend The send_email tool and email-action triggers Only for email
Mailbox connections An agent watching a real inbox and reacting to new mail Only for a Resend-inbound mailbox
CRM connectors Salesforce or HubSpot tools Only if agents act on a CRM
SSO Team sign-in via your own identity provider Only if you want SSO

Only the first one is required. Everything else is optional: skip what your agents don't need, and add it later without redeploying anything.

These provider consoles change without much notice

Menu labels below match each provider's console as of this writing. If a step doesn't match what you see, follow the official doc linked at the start of that section instead, it's the source of truth.

Gemini API key

Official doc: Using Gemini API keys (Google AI for Developers).

Every agent's conversation runs on Gemini Live, Google's realtime multimodal model. It's the one credential every AiFlow deployment needs, and it requires no Google Cloud account or setup beforehand.

  1. Go to Google AI Studio and sign in with a Google account. If this is your first visit, accept AI Studio's terms first.
  2. Click Create API key, then choose Create API key in a new project (the simplest option) or an existing Google Cloud project if you already have one you'd rather use.
  3. Copy the key (it starts with AIzaSy...). This is your GEMINI_API_KEY. Unlike some providers, AI Studio keeps the full key visible afterward too, on the Get API key page, so it isn't a shown-once secret.

Enable billing before going live

A freshly created project can call Gemini at low, free-tier volume, enough to confirm everything's wired up. But the Gemini Live API's realtime audio and video quota is billing-gated: open the linked Google Cloud project's Billing page and attach a billing account before you expect real call volume, or requests will start failing once you exceed the free tier. See Google's Gemini API pricing for current rates.

Already standardized on Vertex AI? AiFlow supports that instead of an AI Studio key: set GOOGLE_GENAI_USE_ENTERPRISE=true plus GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION (leaving GEMINI_API_KEY unset), and Google's own Application Default Credentials on your deployment host authenticate instead. This is worth it if you're already on GCP and want Vertex's enterprise support, quota, and data-residency terms. Otherwise, the AI Studio key above is the faster path.

GEMINI_LIVE_MODEL (default gemini-3.1-flash-live-preview) picks which Gemini Live model variant your agents use. The default is a sensible starting point: change it later if you need a different latency and capability trade-off. No other setting depends on it.

Twilio (phone calling)

Official doc: API keys overview (Twilio).

Skip this section if your agents only need the website widget. Twilio is what gives an agent a real phone number, for inbound and outbound calls.

  1. Create a Twilio account. A trial account works fine for testing, but upgrade before real call volume: trial accounts have usage caps, and every recipient hears a "this call is from a trial account" announcement first.
  2. Account SID and Auth Token need no digging: the Twilio Console shows both on its dashboard home page, in the Account Info panel, as soon as you log in.
    • Account SID → TWILIO_ACCOUNT_SID
    • Auth Token → TWILIO_AUTH_TOKEN. Keep this one even after you create an API key below. Twilio signs inbound webhook requests with the account's Auth Token specifically, never an API key secret, so this is what lets AiFlow confirm an inbound call really came from Twilio and not a forged request.
  3. Create an API key too: Console → Settings (left sidebar) → Account settings → API keys & auth tokens → Create API key → type Standard → Next. Twilio recommends this over using the Auth Token directly for outbound REST calls, because a Standard key can be scoped and revoked independently of the whole account.
    • SID → TWILIO_API_KEY_SID
    • Secret (shown once at creation, so copy it immediately) → TWILIO_API_KEY_SECRET
  4. Buy a phone number: Console → Develop (left sidebar) → Phone Numbers → Manage → Buy a number. A first-time trial account may instead show a one-click Get a Twilio phone number button right on the dashboard, that works too. Pick a number with Voice capability, and add SMS and MMS if you plan to use those channels.
  5. Note the phone number itself (E.164 format, e.g. +15551234567). It isn't a credential: you'll assign it to an agent later, inside AiFlow, once your deployment is running.

Twilio's own webhook configuration, pointing your number's "a call comes in" event at your running deployment, happens after deployment, since it needs your instance's real public URL. See your deployment method's own instructions for that step.

Optional Twilio voice add-ons

None of these need a new credential; each is an environment toggle or a Console-provisioned SID, all off or unset by default.

  • Lookup screening (TWILIO_LOOKUP_ENABLED, TWILIO_LOOKUP_FIELDS, TWILIO_LOOKUP_BLOCKED_LINE_TYPES): checks a number before an outbound dial and tags inbound calls with a line type. The carrier data packages are billed per lookup.
  • Answering Machine Detection: a per-agent toggle in the dashboard, no env var. An outbound call that reaches voicemail is hung up instead of running a full session.
  • Voice Insights (TWILIO_VOICE_INSIGHTS_ENABLED): per-call audio quality on the call detail page. Enable Voice Insights Advanced on the Twilio account first.
  • verify_caller_identity tool: create a Verify → Services entry in the Console and paste its SID into the tool's config on an agent.
  • TaskRouter transfers (licensed taskrouter feature): create a TaskRouter Workspace and Workflow in the Console, then set their SIDs on the transfer_to_human tool's config.

Telegram

Official doc: Telegram Bot API.

Needed only for the send_telegram tool. Telegram is the quickest outbound channel to set up, because it has no template approval: a bot may message any chat that has already started a conversation with it, in whatever wording the agent chooses.

  1. Message @BotFather in Telegram and send /newbot. Follow the prompts to name the bot. It replies with a token that looks like 123456789:AAH.... Put that in TELEGRAM_BOT_TOKEN.
  2. Decide where messages should go. For a group or channel, add the bot to it and read the chat id, which for a supergroup looks like -1001234567890. For a direct message, the person has to message the bot first. Put the value in TELEGRAM_CHAT_ID.
  3. Enable Send Telegram on the agent. Either value can be overridden in the tool's own config when one agent needs its own bot or destination.

A bot cannot message someone first

Telegram requires the other side to open the conversation. A bot cannot cold-message a user who has never contacted it, which is Telegram's rule rather than an AiFlow limitation.

Telegram cannot place calls

The Bot API has no method for starting, receiving, or joining a voice or video call. Use the phone channel for live audio.

WhatsApp

Official doc: Register WhatsApp senders using Self Sign-up (Twilio).

This builds on the Twilio account above: same credentials, no separate AiFlow API key. WhatsApp adds two things beyond a phone number: registering that number as a WhatsApp sender, and getting at least one message template approved. WhatsApp and Meta require every business-initiated message to use an approved template, there's no freeform-text option.

Registering a real sender needs an upgraded account

A trial Twilio account can use the shared Sandbox number for testing (see the end of this section), but it can't register your own number as a production WhatsApp sender. Upgrade the account (add a payment method) before you start sender registration below.

1. A Meta Business Portfolio

WhatsApp sending is tied to a Meta Business Portfolio (formerly "Business Manager"), a free Meta account that groups your business's assets together. A WhatsApp Business Account (WABA) lives inside it and is what actually holds your sender.

You don't need a Meta Developer App or direct access to the WhatsApp Cloud API: Twilio acts as your WhatsApp Business Solution Provider and handles the Meta integration for you. You can create the Portfolio yourself first, at business.facebook.com, which is useful if you want Business Verification (required before production-volume sending and can take several days, so start it early and run it in parallel with the rest of this setup). Or you can let Twilio's own flow create one inline in the next step.

2. Register your number as a WhatsApp sender

In the Twilio Console, go to Messaging → Senders → WhatsApp Senders → Create new sender, select your number, and click Continue with Facebook to connect your Meta Business Portfolio and WABA. Twilio walks you through verifying the number (for a Twilio-owned, SMS-capable number this happens automatically, with no code for you to hunt down) and filling in a customer-visible display name and category. Registration itself finishes in a few minutes, but a brand-new Business Portfolio still needs Meta's separate business verification before it can send at production volume.

3. Create and approve a message template

Console → Messaging → Content Template Builder → Create new. Write your message using {{1}}, {{2}}, and so on for variables, for example Hi {{1}}, this is a reminder about your appointment on {{2}} at {{3}}.. Save it to get a Content SID (HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx), then submit it for approval with a category (UTILITY, MARKETING, or AUTHENTICATION) and sample values. Approval usually completes within an hour, occasionally up to 24.

That Content SID is what you'll hand to AiFlow later: the send_whatsapp tool's content_sid config field for agent-initiated messages, or a trigger's whatsapp_template_sid for event-fired ones (see Triggers). Create as many templates as you need, one for each distinct message shape.

Testing before your sender finishes approval: Console → Messaging → Try it out → Send a WhatsApp message gives you a sandbox number and a join code, enough to confirm your AiFlow configuration works end to end without waiting on Meta.

Resend (email)

Official doc: Create an API key (Resend).

Only needed for the send_email tool or an email-action trigger.

  1. Create a Resend account and verify a sending domain: Domains → Add Domain, then add the DNS records Resend shows you at your DNS provider. Verification can take anywhere from a few minutes to a few hours, so start it early.
  2. API Keys → Create API Key. Give it a name and set its permission to Sending access (not Full access): AiFlow only ever sends mail through this key, it never reads or manages anything else in your Resend account, so the narrower permission is both sufficient and the safer default. Optionally restrict it to the domain you just verified. Copy the key → RESEND_API_KEY.
  3. Decide the address mail should appear to come from, for example AiFlow <no-reply@your-domain.com> → RESEND_FROM_ADDRESS. The domain here must be the one you just verified: an unverified sending domain gets emails rejected or sent straight to spam.

Mailbox connections (Resend inbound)

Official doc: Receiving emails (Resend).

This is only needed if an agent will watch a real inbox for new mail through Resend's own inbound receiving, the recommended way to connect a mailbox: no separate mailbox account to pay for, and mail arrives as a webhook instead of AiFlow having to poll anything. If you'd rather use an existing IMAP and SMTP mailbox instead, skip this section entirely: that credential is entered directly on the agent's mailbox connection, not as an environment variable.

  1. In Resend, open the domain you already verified for sending above and turn on Receiving.
  2. If that root domain has no mail service of its own today (no existing MX record for your-domain.com itself, and no Google Workspace or Hostinger mailbox already live on it), point receiving at the root domain directly. Mail addressed to support@your-domain.com then just works: no subdomain, nothing to forward.
  3. If the root domain already receives mail somewhere else, use a subdomain dedicated to receiving instead (e.g. inbound.your-domain.com), so Resend's inbound MX record doesn't replace whatever's already handling the root domain's mail. The address you'll actually use becomes support@inbound.your-domain.com. If you'd rather publish the nicer address, you can forward support@your-domain.com to it from wherever the root domain's mail already lives.
  4. Add the MX record Resend shows you (on the root domain or the subdomain, matching what you picked above) at your DNS provider, then confirm it in the Resend dashboard. Verification takes anywhere from a few minutes to a few hours, same as sender verification above.
  5. Webhooks → Add Webhook. Point the endpoint at your own deployment, https://api.your-domain.com/api/v1/mailbox-webhooks/resend, and subscribe it to the email.received event only.
  6. Copy the webhook's signing secret (it starts with whsec_) → RESEND_WEBHOOK_SECRET.
  7. In the AiFlow admin dashboard, open the agent's Tools tab → Mailbox connection, choose Resend (inbound), and enter the exact address mail actually arrives at: support@your-domain.com for the root domain, or support@inbound.your-domain.com for the subdomain. This is also the address you publish anywhere you want people to write in, Resend doesn't create a separate "pretty" alias on your behalf.

RESEND_API_KEY (from above) is reused to send replies through this same mailbox, no separate sending credential needed.

CRM connectors

Lets an agent create or update Salesforce or HubSpot records mid-conversation. Each provider needs its own OAuth2 app credentials, enough setup that it gets its own dedicated walkthrough: see CRM connectors → Activating a provider for the exact console steps per provider.

SSO

Lets your team log into the admin dashboard through your own identity provider (Okta, Auth0, Microsoft Entra ID, Google Workspace, or any other standards-compliant OIDC provider), instead of an AiFlow-specific password. Like CRM connectors, this gets its own dedicated walkthrough: see SSO → Activating it for the exact registration steps per provider.

Next

Keep these somewhere safe, a password manager or your deployment host's own secrets store. You'll enter them as environment variables during setup, regardless of which deployment method you use. See Authentication for the two credential types AiFlow itself issues once your deployment is running, its admin login and API keys, a separate concern from everything on this page.