> For the complete documentation index, see [llms.txt](https://docs.helvia.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helvia.ai/administration/integrations.md). # Integrations Integrations are the credentials layer of your Workspace. They store the API keys, endpoints, and OAuth credentials Helvia.ai uses to reach external providers: AI models (LLMs), knowledge sources, live chat platforms, CRMs, and identity providers. Set them up here once and reuse them across multiple agents. ```mermaid graph LR I[Integration] -->|credentials| P[Plugin] P -->|capability| A[Agent] I -.->|direct use| F[Knowledge / SSO / Voice] style I fill:#615DEC,stroke:#615DEC,color:#fff style P fill:#f0f0f7,stroke:#615DEC,color:#615DEC style A fill:#f0f0f7,stroke:#615DEC,color:#615DEC style F fill:#f0f0f7,stroke:#615DEC,color:#615DEC,stroke-dasharray: 5 5 ``` ### How Integrations Work Integrations enhance your AI agents with additional functionality by connecting them to external tools and services. Configure your credentials once, then link the integration to a [plugin](/build/plugins.md) on an agent, or directly to a Workspace feature like Knowledge, SSO, or Voice. Setup needs vary by integration.

:arrows-rotate:

Workspace-wide reuse

One credential set serves everything. Create an integration once and every plugin or Workspace feature that needs that service can pick it up.

:puzzle-piece:

Plugin activation

Agents reach the integration through a plugin. Turn the plugin on for an agent and point it at your integration.

:lock:

Secret handling

Credentials stay masked once saved. Anyone with edit access to the Workspace, however, can view and change the secrets.

:circle-exclamation:

No automatic validation

The platform does not test your credentials on save. A wrong key or expired token only surfaces when the integration is actually used, so always test it end-to-end.
### Managing Integrations All integrations live in **Workspace > Integrations**. The table lists every integration with its type and category, so you can quickly find the one you need and open it to edit or manage.
#### Adding an Integration {% stepper %} {% step %} #### Find the Integration Select **Add Integration**, then pick a **Category** (for example **AI Models** or **CRM**) to find the integration you need. {% endstep %} {% step %} #### Name the Integration Enter a **Name**, optional **Description**, and any **Tags**. These fields are common to every integration and used mainly for organizing them. {% endstep %} {% step %} #### Configure the credentials Enter the credentials and configuration for your provider. Required fields are marked, and secret fields like API keys are masked. See [#integration-categories](#integration-categories "mention") for provider-specific setup notes. {% hint style="warning" %} **No automatic validation:** The platform does not validate your credentials when you save the integration. Double-check the values, and test the integration end-to-end before relying on it in production. {% endhint %} {% endstep %} {% step %} #### Create the Integration Click **Create Integration**. The integration is now available across the Workspace and can be linked to plugins or features. {% endstep %} {% endstepper %} #### Editing an Integration Click any integration or use the edit icon :pen: in its **Actions** column, to open it. Secret fields stay masked: type a new value to overwrite them, or leave them as-is to keep the existing one. You can't save while a required field is empty. Once saved, every plugin or feature using the integration picks up the change automatically. {% hint style="danger" %} Anyone with [edit access](/administration/users-and-roles.md#workspace-access-roles-1) to the Workspace can view, modify, or reuse stored integration credentials in the Workspace. Granting edit access means trusting that user with every credential stored here. {% endhint %} #### Deleting an Integration To remove an integration, use the delete action :trash-can: in its **Actions** column and confirm. Once deleted, any plugin still linked to the integration stops working, and the agents that depend on those plugins might break. Make sure nothing is using the integration before deleting. ### Integration Categories Each category groups providers that serve the same purpose in the platform. Pick a category when creating an integration, then choose the specific provider.

:microchip:

AI Models

Connect LLM providers to power the LLM node, semantic search, language detection, and session analytics./pages/OtcDYSj75LLHNgHnB5mz#llm-1

:book-blank:

Knowledge

Sync external document libraries into your agents' retrieval index (RAG)./pages/OtcDYSj75LLHNgHnB5mz#knowledge-base-1

:microphone:

Voice

Power speech-to-text and text-to-speech on voice-enabled deployments./pages/OtcDYSj75LLHNgHnB5mz#speech-1

:address-card:

CRM

Pull customer records from your CRM into agent and LiveChat sessions for context./pages/OtcDYSj75LLHNgHnB5mz#crm-1

:ticket:

Ticketing

Create and update support tickets directly from agent conversations and LiveChat sessions./pages/OtcDYSj75LLHNgHnB5mz#ticketing-1

:headset:

Live-chat

Route conversations to a third-party live chat platform when a human takes over from your agent./pages/OtcDYSj75LLHNgHnB5mz#livechat-1

:shield-halved:

SSO

Let your team sign in to the platform with your own identity provider./pages/OtcDYSj75LLHNgHnB5mz#sso-1
{% hint style="success" %} **Setup varies by provider** Each integration has its own configuration form. If you encounter any problem with a setup, you can reach out to [Support](/resources/support.md). {% endhint %} ### AI Models AI Models integrations are the most important integrations on the platform: they connect the large language models (LLMs) that power your AI agents themselves. Without one configured, your agents have no model to reason with, so set up an LLM integration as one of the first steps in a new Workspace. A single AI model integration is used across the platform in: * LLM nodes * Semantic Search (RAG) * Language Detection * Session Analysis * Automated Testing
OpenAI Standard OpenAI API access. **Required fields:** * **API Key**: Your OpenAI API key
Azure Azure deployments through Microsoft AI Foundry. **Required fields:** * **API Key**: The API key from your Azure resource * **Endpoint**: The host endpoint from your Azure resource * **Deployment Name**: The name of your Azure deployment, required when the LLM plugin uses the Responses endpoint
Gemini Google's Gemini family of models via the Gemini API. **Required fields:** * **API Key**: Your Google AI Studio API key
{% hint style="info" %} **OpenAI-compatible providers** Connect any OpenAI-compatible provider such or Mistral AI or DeepSeek through an OpenAI integration. Set the **Custom Base URL** field to the provider's endpoint and use their API key; the integration then behaves like a standard OpenAI integration everywhere it's used. {% endhint %} #### Primary and Fallback Configurations An LLM outage is a single point of failure on the platform: without a working model, agent replies, session analysis, and language detection all stop. Each LLM integration mitigates this by holding an ordered list of configurations. When a request fails, the platform automatically retries it against the next configuration in the list until one succeeds. {% columns %} {% column %} #### Primary The first configuration in the list. Every request goes to the primary first, and every consumer of the integration uses it by default. {% endcolumn %} {% column %} #### Fallback Any configuration below the primary. Each fallback is tried in order when the previous entry fails, up to the last one on the list. {% endcolumn %} {% endcolumns %} An LLM integration holds up to 5 configurations in total: 1 primary and up to 4 fallbacks. Add a fallback with **Add fallback** inside the integration form, reorder rows by dragging them, and remove a row with its delete action. ### Knowledge Knowledge integrations sync your internal documents, files, and other knowledge sources into [Knowledge Bases](/knowledge/knowledge-base.md), so you don't have to upload them one by one. Once connected, agents can retrieve passages from the synced content at runtime, powering RAG search across the platform.
Dynamics 365 KB Knowledge articles published in your Dynamics 365 instance. Because the content is article-based rather than document-based, this integration doesn't expose processing options; articles are imported as-is. **Required fields:** * **Minor Version**: The minor version of your Dynamics 365 deployment
SharePoint KB Microsoft 365 document libraries. Access is granted in two steps: a one-time tenant authorization for your Workspace, then a per-site approval that your SharePoint admin completes for each site you connect. After saving the integration, follow the guide in the access panel to complete the per-site approval. The sync starts once access is verified. With **Sync Permissions (RBAC)** on, SharePoint permissions resync daily; retrain affected knowledge pipelines to apply the changes. **Required fields:** * **Site URL**: The URL of the SharePoint site holding your documents * **Document Libraries**: The libraries within that site to include in the sync
Azure Blob Storage KB Container-based document storage. The form displays a read-only **Webhook URL**: configure it in your Azure Blob Storage account so changes to your container trigger an immediate sync into the knowledge base. **Required fields:** * **Account Name**: Your Azure storage account name * **Container Name**: The blob container holding the documents * **SAS Token**: A shared access signature (SAS) with read access to the container
#### Configuring Processing Options Document-based connectors, such as SharePoint KB and Azure Blob Storage KB, expose processing options that control how documents are parsed, chunked, and indexed for retrieval. These shared controls shape what gets ingested and how the resulting articles behave, so you can tune each source:
ControlDescription

:file-lines:

File types

Choose which formats to pull from the source

:wand-magic-sparkles:

Additional Instructions

Natural-language guidance for the AI-Powered segmenter

:tags:

Tags

Applied to every article the integration generates, feeding RAG retrieval tag filtering
### Voice Voice integrations power speech-to-text and text-to-speech on voice-enabled deployment channels, so your agents can hold spoken conversations.
Azure Speech Microsoft Azure speech-to-text and text-to-speech services. **Required fields:** * **Region**: The Azure region of your Speech resource * **Subscription Key**: The subscription key from your Azure Speech resource
### CRM CRM integrations pull existing customer records into agent and LiveChat sessions, so conversations start with full context about who the user is.
Dynamics 365 CRM Read customer records from your Dynamics 365 instance. **Required fields:** * **Minor Version**: The minor version of your Dynamics 365 deployment
### Ticketing Ticketing integrations let LiveChat human agents create and update support tickets directly from a conversation.
Zendesk Ticketing Create and update tickets in Zendesk Support. **Required fields:** * **Base URL**: The base URL of your Zendesk instance * **Username**: The Zendesk user account the integration acts as * **Token**: An API token from Zendesk paired with the username
### Live-chat Live-chat integrations route conversations to a third-party live chat platform when a human takes over from your AI agent. The handoff carries the session context across so the human picks up where the agent left off.
Cisco Customer Collaboration Hand off conversations to a Cisco contact center. **Required fields:** * **Client ID**: OAuth client ID for your Cisco app * **Client Secret**: OAuth client secret for your Cisco app * **CCX Queue Tag**: Tag identifying the Cisco CCX queue to route chats to * **Chat ID**: Identifier of the chat application in Cisco * **Endpoint**: The Cisco service endpoint URL
Zendesk Live Chat Route conversations into Zendesk via the Sunshine Conversations API. **Required fields:** * **Zendesk Base URL**: The base URL of your Zendesk instance * **Sunshine App ID**: The Sunshine Conversations app ID * **Sunshine Conversations Key ID**: API key ID from Sunshine Conversations * **Sunshine Secret**: API secret paired with the key ID * **Webhook ID**: The webhook ID registered in Sunshine Conversations * **Webhook Key**: The secret used to validate webhook callbacks
Genesys Hand off conversations to a Genesys contact center. **Required fields:** * **Genesys OAuth app client ID**: Client ID of your Genesys OAuth app * **Genesys OAuth app client secret**: Client secret of your Genesys OAuth app * **Genesys organization region**: The domain only (for example, `mypurecloud.ie`) * **Genesys Open Messaging integration ID**: The Open Messaging integration ID in Genesys * **Webhook Key**: The secret used to validate webhook callbacks
{% hint style="success" %} Helvia LiveChat does not require an integration. It works out of the box with no Workspace setup. {% endhint %} ### SSO SSO integrations let your team sign in to the platform with your identity provider instead of email and password.
OpenID Any OpenID Connect-compatible identity provider. **Required fields:** * **OpenID Configuration URL**: The discovery document URL of your identity provider * **Grant Type**: The OAuth grant type used to obtain tokens (for example, `authorization_code`) * **Client ID**: The client ID registered for the platform in your identity provider
### Best Practices * **Tag your environments**: Apply tags like `prod`, `sandbox`, or a team name to keep credentials organized as your Workspace grows * **Set up integrations first**: Plugins won't show available providers until at least one matching integration exists * **Reuse, don't duplicate**: A single integration can serve multiple plugins across multiple agents * **Rotate credentials in place**: Update the existing integration rather than creating a new one, so every plugin linked to it picks up the new credentials automatically * **Pick LLM fallbacks from different failure domains**: Point fallbacks at a different tenant, subscription, or region so a provider incident does not take them down together {% hint style="success" %} You now know what integrations do, how to create and manage them, and how they connect to plugins and other Workspace features. {% endhint %}