Skip to content

Connections (setup guide) ​

Asha has built her agents for Acme Support. The last step is connecting the accounts those agents use to send and receive messages: her Plivo number, her Telegram bot, her support mailbox, her Google Sheet. That's what Connections is for.

Go to Admin → Connections (/credentials). Everything you connect here is your own account with that provider. Your agents use it on your behalf, and your keys stay private to your workspace.

The AI is already included

You don't connect an AI model here. The language models, voice, file storage, knowledge-base search and web-voice infrastructure your agents run on are included and managed by Perfox. There's nothing to configure and no key to paste. You choose a model per agent on its Chat Model sub-node, and usage is paid from your credits.

How the page is laid out ​

Admin → Connections: every provider has its own slot and Connect button

The page opens with "Connect the providers that power your channels, storage and AI. Each provider below has its own Connect button." Every provider you can connect has its own slot, grouped into sections:

SectionProviders
Telephony & MessagingPlivo (WhatsApp, SMS, Voice)
Messaging appsTelegram bot, Slack app, Facebook Messenger, Instagram Direct, Microsoft Teams bot, Discord app, Google Chat app, RCS Business Messaging
EmailResend, AWS SES, SendGrid, Postmark, Mailjet, Mailgun, Gmail / Google Workspace, SMTP / IMAP, Microsoft 365 (Email)
AI & SearchNo slots, just a note: AI model keys are managed by Perfox (see below)
StorageAWS S3, Microsoft 365 (OneDrive / SharePoint), Google Drive. These are knowledge-base sources
DatabasesPostgreSQL, MySQL (MySQL / MariaDB), MongoDB. Your own database, queried by an agent tool
IntegrationsGoogle Sheets

The AI & Search heading shows a short note instead of slots: AI model keys are managed by the Perfox platform team and your agents already run on them, so there's nothing to connect there. If you want your agents to run on your own provider account (for example your own Gemini or OpenAI key), contact Perfox support.

The Search providers... box filters slots as you type (by provider name, type or description). A section with no matches disappears. If nothing matches, the page says "No providers match your search".

Each slot shows its state:

  • Not connected: a dashed row with the provider's logo, "○ Not configured" and a button. It reads Connect, Connect with Google for Google Sheets and Gmail, or Connect Microsoft for the two Microsoft 365 slots.
  • Connected: one card per connection, plus an Add another <provider> link. You can connect several accounts of the same provider. They stack in the slot.

Clicking the slot's button opens a form already set to that provider, so there's no provider drop-down to mis-pick.

Messaging apps ​

The Messaging apps section is where you connect the bot or app your customers message on Telegram, Slack, Facebook Messenger, Instagram, Microsoft Teams, Discord, Google Chat or RCS. Each field's label says where in that platform's console to find the value. The full step-by-step for every app is on Messaging apps.

These cards behave a little differently from the others:

  • Test Connection connects the app. Save the form, then click Test Connection. For Telegram, that's the whole setup: Perfox learns your bot and registers its own webhook. For apps whose webhook you set in their own console, the test result shows a Webhook URL with a Copy button. Paste it into the app's settings.
  • The card names the account. Under the card title you see which account is connected, for example Bot @acme_support_bot, Page Acme Support or Instagram @acme. Until you've tested, it reads "Not connected yet — Save, then press Test."
  • RCS Business Messaging is billed per message by Google to your own RCS account.
  • Deleting a messaging-app connection first disconnects it, so the platform stops sending messages to Perfox.

Status badges ​

BadgeColourMeaning
ConnectedgreenThe last Test Connection succeeded
ErrorredThe last Test Connection failed, or the provider refused a live send
Pending verificationyellowWaiting on a verification step at the provider
Not testedgreySaved, but not verified yet, or the provider has no live test

Perfox tests a connection automatically every time you create it or save a change to it, so the badge shows the real state straight away. Changing which channels a Plivo number serves doesn't re-run the test.

A card in Error says why. Under its title, in red, you see the reason followed by "— fix it under Edit, then press Test Connection." That covers a failed test, and also a messaging app whose token the provider stopped accepting while your agent was replying.

Microsoft 365 cards also show their access mode: Delegated or App-only.

Card actions ​

Each connection card has these actions in its header:

  • Test Connection: a real, live check against the provider (see below).
  • Edit: opens Edit Credential, where you change the name, description and provider fields, then Save Changes. A secret you've already saved shows as dots with a Replace link ("Saved. Replace it only if it changed.") instead of an empty box. Anything you don't touch is kept exactly as stored, so saving a new description never wipes a token. Every save re-runs the test. Plivo edits inline in the expanded card instead. See Plivo.
  • Delete (trash icon): asks for confirmation: "Are you sure you want to delete this credential? This action cannot be undone. Any workflows or MCP servers referencing this credential will lose their connection."
  • Expand (chevron, or click the card): shows the saved fields, where the connection is used, and Last tested.

OAuth providers add a button on the card so you can re-authorise in place without deleting the connection. Agents wired to it stay wired. Google Sheets and Gmail show Connect Google, and Microsoft 365 connections that sign in as a user show Connect Microsoft. Either button reads Reconnect once the card is connected.

If a save, edit or delete is refused, Perfox shows you the reason: inside the Connect form, or as a red message at the bottom right of the page. A button that does nothing is never the answer.

Test Connection ​

  1. Checks the required fields. If any are missing it fails straight away with "Missing required fields: …".

  2. Calls the provider: for example a Plivo account check, a mailbox login, a database query of SELECT 1, or connecting a messaging app.

  3. Shows the result with one of three headlines and the provider's own message:

    • ✓ Connected (green): it worked.
    • ✕ Connection failed (red): it didn't. The badge turns red and the card shows the reason.
    • • Saved — not verified (neutral): this provider has no live test, so the connection is saved but unchecked.

    The badge and Last tested date update.

Some providers (Microsoft 365, several email providers) also return a checklist, one ✓ or ✕ line per permission or capability, so you can see exactly what's missing. Messaging apps can also return the Webhook URL to copy.

The Connect form ​

Connect Postmark: name and description on the left, provider fields on the right

  • The title reads Connect <provider>, with the provider's logo and description.
  • Name (pre-filled with the provider name) and an optional Description sit on the left. The provider's own fields sit on the right, grouped where it helps (for example Email and Inbound). Secret fields are masked.
  • Create saves the connection and tests it straight away.

OAuth providers use a different button:

ProviderButton
Google Sheets, Gmail / Google WorkspaceSave & Connect Google
Microsoft 365 / Microsoft 365 (Email), DelegatedSave & Connect Microsoft
Microsoft 365 / Microsoft 365 (Email), App-onlySave

Expanded card details ​

  • Saved values are shown read-only. Secrets are masked with a Reveal / Hide toggle, and an empty field reads "Not set".
  • Where it's used: see Usage and detach.
  • AWS SES shows a note: these keys are used to send email, the From address must be verified in SES, and receiving is managed by Perfox, so there's no webhook to set up. See AWS SES.
  • Plivo's webhook URLs live in its editor's Integration tab, each built for your workspace's API address (https://<your-workspace>-api.perfox.ai/...) with a Copy button. See Point Plivo at Perfox.

Plivo inline editor ​

The Plivo number list: channel tags, Set up voice & SMS, and the required manual WhatsApp step with its Webhook URL

Plivo is edited directly in its expanded card. Its Edit button just expands it.

  • Name / Description and Auth ID / Auth Token. A saved Auth Token (and SIP Password) shows as dots with Replace. It's stored encrypted and never shown again, so replace it only if it changed.
  • Two tabs:
    • Numbers & templates: the numbers on your Plivo account load automatically when you open the card. Tag each number with the channels it serves (Voice, SMS, WhatsApp). One number can serve several. Tag changes save automatically. There's no default number: each agent sends only from a number it picks. Each number has its own Set up voice & SMS button: Perfox sets up the Plivo application and points that number at it. WhatsApp numbers also show a required manual step for receiving WhatsApp, and a Show templates button. The Advanced section holds SIP Domain / Username / Password and India SMS DLT fields (DLT Entity ID, Template ID, Template Category).
    • Integration: the per-channel webhook URLs to paste into Plivo.
  • One Save changes button for the rest of the form.

The tagged inventory is what the number pickers in your agents offer. See Plivo for the full walkthrough.

Connecting OAuth providers ​

Google Sheets and Gmail (your own Google app) ​

Google Sheets (and Gmail) connect through your own Google Cloud OAuth app. The form walks you through it:

  1. In Google Cloud Console, create or pick a project.
  2. Enable the APIs the form lists. For Sheets that's the Google Sheets API and the Google Drive API (skipping one causes an "API … is disabled" error). For Gmail it's the Gmail API.
  3. Configure the OAuth consent screen, add the scopes shown in the copyable block (for Gmail, https://mail.google.com/), and add yourself as a test user.
  4. Create an OAuth client ID (Web application) and register the exact Redirect URI shown in the form.
  5. Paste the Client ID and Client Secret, then click Save & Connect Google.

Google asks you to approve access and then returns you to Connections with the card connected. Reconnect re-authorises the same connection later (for expired or revoked access) without breaking any agent that uses it. See Google Sheets.

Microsoft 365 (your own Entra app) ​

There are two Microsoft 365 slots, which can share the same Entra app:

  • Microsoft 365 under Storage: OneDrive / SharePoint knowledge-base sources.
  • Microsoft 365 (Email) under Email: send and receive mail through Microsoft Graph. See Email Providers.

Connect Microsoft 365 (Email): access mode and the one-time Entra setup

Choose an Access mode:

ModeHow it worksButton
App-only (tenant app)No user sign-in. Storage: pick a user by email later on the Knowledge Base page. Email: enter the mailbox to send/receive as.Save (checked by requesting a token)
Delegated (as a user)A user signs in once, and the connection acts as that user (for storage, including files shared with them).Save & Connect Microsoft (opens a sign-in window)

The form describes the one-time setup:

  1. Register an app in the Microsoft Entra admin center.
  2. For Delegated, add the Redirect URI shown in the form under Authentication → Web.
  3. Add the Microsoft Graph permissions from the copyable block and click Grant admin consent.
  4. Create a client secret.
  5. Paste the Directory (tenant) ID, Application (client) ID and Client Secret.
SlotModeGraph permissions
Microsoft 365 (storage)Delegatedoffline_access, User.Read, Files.Read.All, Sites.Read.All, Group.Read.All
Microsoft 365 (storage)App-onlyFiles.Read.All, Sites.Read.All, Group.Read.All, User.Read.All
Microsoft 365 (Email)Delegatedoffline_access, User.Read, Mail.Send, Mail.Read
Microsoft 365 (Email)App-onlyMail.Send, Mail.Read

App-only mail access

App-only Mail.Send / Mail.Read reach every mailbox in your Microsoft organisation until an Exchange admin restricts the app with an application access policy to a group containing only the mailbox you use.

Usage and detach ​

The expanded card shows where a connection is used, so you know the impact before you rotate or delete it:

  • Numbers: each phone / SMS / WhatsApp number shows whether it's assigned to an agent (with a link), not assigned, or used as the outbound caller ID.
  • Other connections: the agent that uses it ("Used by workflow: …").
  • Assigned numbers have a Detach button. Its confirmation shows the current binding and what happens after you detach (for example inbound calls to that number are no longer answered, or messages sit unhandled) and links to the agent.
  • Detaching takes the affected agent back to draft. Publish it again for the change to take effect.

Before you rotate a key

Check the usage list first, so you know which agents to re-test afterwards.

What isn't on this page ​

  • AI models, voice, file storage, knowledge-base search, web voice: included and managed by Perfox.
  • MCP server connections: set up on Integrations, not here.

Next steps ​