#Integrations

The Integrations area covers partner-controlled connection points such as API keys and webhook/API contracts. Some integration contracts are exposed through direct API routes even when a portal UI panel is not yet visible for every action.

The workspace is at /integrations. It uses a client selector and a data-environment selector (prod, staging, dev) for the visible integration areas. Each area is shown as a separate tab so it keeps its own readiness state, empty state, and safe next actions without mixing unrelated controls on one long page. The tabs are Plugins & tools, API Keys, Webhooks, Single Sign-On, SCIM, and Provider connections; API Keys, Webhooks, Single Sign-On, and SCIM are live scoped tabs, while Plugins & tools and Provider connections are marked coming soon. The page opens on API Keys, and the selected client, environment, and tab are reflected in the client_id, data_env, and tab query parameters so a view can be bookmarked or shared. /plugins and /provider-connections are convenience routes that redirect to the matching tab. Create, test, enable, and save actions stay unavailable until the selected client scope and required fields are valid.

Portal screens call same-origin BFF route handlers under /api/**. Those handlers validate the signed-in next-auth/Zitadel session, enforce route-level auth/RBAC and selected-client or selected-project scope, then call aidial_api server-side with a bearer token. Browser code must not send X-API-Key; direct API-key integration is for trusted server-side systems using the maintained AiDial API reference.

#Who Can Use It

Manage actions across API keys, webhooks, SSO, and SCIM are limited to partner_admin and aidial_admin. Internal roles must select a tenant before any integration area loads; there is no all-tenant view.

Customer roles do not access the Integrations workspace. Navigation visibility is not a security boundary; non-API routes are checked by middleware, and each /api/** route handler enforces its own auth, RBAC, and scope checks. Middleware applies no auth to /api paths; the route handlers are the only gate there.

#API Keys

The current Integrations page exposes selected-client API-key management for partner and internal roles according to their permissions. See API Keys & Partner API for creation, one-time reveal, rotation, revocation, and direct API usage.

Partner roles also see a Developer setup card above the tabs. It links to the published API reference and authentication pages, jumps to the API Keys and Webhooks tabs, and shows placeholder request examples for the selected client and environment. The examples are illustrative only: real keys belong in your own server-side systems, not in browser code.

#Core Runtime Surfaces Versus Plugins

AiDial separates core runtime surfaces from plugins.

Core project surfaces include agent orchestration, RAG/knowledge bases, transfer routing, outbound compliance, governance, recording/transcript controls, transcript email delivery, webhook delivery, email, sms, identity_verification, caller_info, speech, testing controls, release governance, secret references, and provider domains such as providers.telephony, providers.stt, providers.tts, and providers.llm.

Plugins are external service integrations. The supported plugin kinds are FluentCRM (CRM), Amelia (booking), Google Calendar (calendar), and n8n (workflow). Do not treat RAG as a plugin: RAG is the core knowledge-base/runtime surface used for approved content grounding and retrieval.

Plugin enablement is per project and lives in the project workspace, not on the Integrations page. The Plugins & tools tab is reserved for an organisation-level catalog view and is not built yet. See Projects for the per-project plugin, tool-capability, and secret-reference controls.

Some controls are visible in the portal, some are direct API/reference contracts, and some remain escalation-only. When a control is not visible for your organisation, do not infer that a hidden configuration-file edit path is partner self-service.

#Outbound Campaigns

Outbound campaign management is a dedicated partner operational surface at /outbound-campaigns (/campaigns redirects there). It covers campaign creation and editing, CSV contact import, DNCR/registry wash evidence, launch validation, run/pause/resume/cancel controls, and reporting over the existing outbound runtime. There is no hard delete for campaigns; cancelling preserves campaign, audit, and reporting history.

Use Outbound Campaigns for campaign workflows. Use the Integrations area for supporting connection points: the Integrations workspace tabs cover API keys, webhooks, SSO, and SCIM. Knowledge bases and phone numbers have their own read-only partner inventory pages at /knowledge-bases and /telephony, and catalogs are a lookup contract rather than a page.

#Webhooks

The Webhooks tab is a live selected-client surface covering the full endpoint lifecycle: list, create, edit, delete, rotate secret, and send test. The same operations are available to trusted server-side systems through the partner webhook routes in the public API reference. Partner admins and AiDial admins can make changes; partner users and AiDial operators see the tab in read-only mode.

Choose the project whose runtime configuration should receive the endpoint before creating or changing anything. Webhook changes are guarded by the current project revision; if another operator changes the same project configuration, reload the tab and retry from the latest revision. The tab also shows the current propagation status for the selected project.

Each endpoint carries:

• an HTTPS endpoint URL on a publicly resolvable host. Private, loopback, and link-local addresses are rejected, as are URLs that embed credentials, fragments, or token-like query parameters.
• one or more event types, using canonical AiDial runtime names: call_started, call_ended, call_analyzed, and transfer_initiated.
• a transcript delivery mode of none, redacted, or original. Original-transcript delivery is intended only for trusted systems and stays subject to backend compliance checks.
• retry attempts (0-5), retry backoff in seconds (5-300), and a request timeout in seconds (1-30).

The signing secret is shown once, when the endpoint is created and again after each rotation. Store it immediately; it is not shown again. Test deliveries use the same signed delivery headers as runtime deliveries and carry a synthetic metadata-only payload under the webhook_test event.

The delivery log is metadata-only and can be filtered by endpoint, event, status, source (runtime or test), and date range on top of the selected client, project, and environment. It returns delivery status, attempt counts, status codes, latency, error codes, endpoint host, and troubleshooting guidance, over a visible retention window that the tab states. Raw payloads, transcripts, response bodies, signing secrets, bearer tokens, API keys, ciphertext, and secret-backend references are not returned.

Webhook secrets must be handled like credentials and should never be pasted into support tickets or screenshots.

#Single Sign-On

The Integrations page includes tenant SSO governance for assigned clients where your role allows it.

Partner admins can maintain SAML/OIDC configuration and client-role mapping rules. Partner users can view SSO state in read-only mode. AiDial admins handle runtime-enforcement status and break-glass recovery authorisations.

Status wording separates three states:

• saved provider configuration
• policy enabled or disabled
• runtime enforcement state: not enforced, pending activation, enforced, or failed

Mapping rules match on group, claim, email domain, or attribute. Role mappings assign only client roles: Client admin, Client manager, or Client staff; a mapping that targets any other role is rejected by the server. Users without a matching active mapping receive no role assignment. Lower priority numbers are evaluated first, and active mappings are evaluated ahead of disabled ones.

Break-glass records authorise emergency recovery work only. They do not create portal sessions, impersonate a user, or bypass sign-in. Each grant, revoke, and use attempt requires a justification and is audited.

Do not paste IdP client secrets, SAML metadata XML, private certificates, screenshots of secret values, or raw audit logs into support tickets. The portal writes sensitive provider material once and later displays safe summaries only.

#SCIM Provisioning

The Integrations page includes tenant SCIM provisioning status for assigned clients where your role allows it.

Partner admins can enable or disable the provisioning intake for the selected client and data environment. Partner users can view the status in read-only mode. AiDial admins can manage selected-client SCIM configuration, and AiDial operators have read-only internal access. AiDial operations issues and rotates the provisioning API key separately; the portal never displays the key value.

Provisioning events are accepted only from trusted server-to-server delivery using an API key with the scim_provisioning scope. Browser requests and portal BFF routes do not send X-API-Key.

Group-to-role mapping is not configured separately for SCIM. It reuses the SSO role mappings for the same client, so the Single Sign-On tab is the single place to change who gets which client role.

Role assignment is deny-by-default. A user upsert grants a tenant-scoped portal assignment only when the supplied group matches an active SSO group mapping, and a matched upsert is still denied when the client's member quota is already full. User deactivation and no-match upsert events remove only the scoped tenant assignment and active sessions; they do not affect the user's access to other tenants.

Duplicate event ids replay the stored safe outcome. Recent event summaries and observed groups are shown for operational awareness, without exposing secret material or raw provider payloads.

#Catalogs

The catalog route provides controlled lookup data for two catalog types: voices and models. Catalog data is read-only, available to partner roles, and should be used to populate supported configuration choices rather than free-form provider settings.

#Knowledge Bases

/knowledge-bases is a partner inventory page. Select a client and project, and it lists that project's knowledge bases with their linkage and last-updated state. It is a read-only library view for every partner role: creating knowledge bases, adding sources, attaching agents, and rebuilding all happen in the project's workspace. The underlying knowledge-base, source, RAG-state, rebuild, and agent-attachment routes support the core rag runtime surface; they are not plugin configuration.

Use approved content workflows only. Do not upload customer secrets, private credentials, raw call transcripts, or unapproved personal information. Source access failures that involve private storage, crawling permissions, or customer-sensitive content should be escalated.

#Phone Numbers And Telephony

/telephony is a partner inventory page. Select a client and project, and it lists that project's numbers with assignment, provider, and registration state, plus totals for assigned, unassigned, and validated numbers. The inventory itself is read-only: number purchase, porting, carrier provisioning, and direct assignment changes are not available from it.

Phone-number lifecycle routes exist for list, import, update, assignment, unassignment, telephony registration, and deletion, with mutations restricted to partner_admin. These actions relate to providers.telephony and can affect live calling behaviour, so use the approved portal/API workflow and escalate anything involving production routing uncertainty.

#Messaging And Identity Integrations

email, sms, identity_verification, and caller_info can involve external provider accounts, customer contact data, or privacy-sensitive runtime context. Their portal controls live in the project workspace under email delivery, SMS policy, and identity verification, not on the Integrations page. Treat those controls as bounded customer-safe settings. Provider account setup, delivery investigation, verification-provider errors, and caller-data uncertainty should be escalated rather than handled through support-ticket screenshots or raw payload sharing.

#Unsupported Or Escalated Work

Use Escalation Boundaries for:

• plugin credentials or provider account setup
• webhook delivery failures that require service logs
• production phone-number routing changes outside the portal/API workflow
• campaign launch blockers caused by runtime capacity, phone routing, provider setup, or unclear DNCR/compliance evidence
• knowledge-base source failures involving private storage or crawling access
• email, sms, identity verification, or caller-info provider issues involving customer data or credentials
• catalog changes, model enablement, or provider availability questions
• emergency disabling of an integration after a suspected secret exposure

#Related Pages

• API Keys & Partner API
• Projects
• Escalation Boundaries
• API Authentication
• The published AiDial API reference, linked from the Developer setup card on the Integrations page, for direct integration contracts.