> 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

Connect the platform to external tools used across your Workspace

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, MCP servers and A2A agents, 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 -->A[Agent]
      I -->|connection| T[Tools]
      T --> A
      I -.->|direct use| F[Knowledge / SSO / Voice]


      style I fill:#615DEC,stroke:#615DEC,color:#fff
      style P fill:#f0f0f7,stroke:#615DEC,color:#615DEC
      style T 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](https://docs.helvia.ai/build/plugins.md) or [Tools](https://docs.helvia.ai/build/tools.md) on an agent, or directly to a Workspace feature like Knowledge, SSO, or Voice. Setup needs vary by integration.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><h4><i class="fa-arrows-rotate">:arrows-rotate:</i></h4><h4>Workspace-wide Reuse</h4></td><td>One credential set serves everything. Create an integration once and every plugin or Workspace feature that needs that service can pick it up.</td></tr><tr><td><h4><i class="fa-puzzle-piece">:puzzle-piece:</i></h4><h4>Agent Access</h4></td><td>Agents reach the integration through a plugin or Tools. Turn them on for an agent to use your integration.</td></tr><tr><td><h4><i class="fa-lock">:lock:</i></h4><h4>Secret Handling</h4></td><td>Saved secrets are write-only: anyone with edit access can replace them, but no one can view them in the Console</td></tr><tr><td><h4><i class="fa-circle-exclamation">:circle-exclamation:</i></h4><h4>No Automatic Validation</h4></td><td>Credentials are not tested on save. A wrong key or expired token only surfaces when the integration is actually used, so always test it end-to-end.</td></tr></tbody></table>

### 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.

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FhC7tBZwgcdI0wl1XxHSj%2FSCR-20260814-madv.png?alt=media&amp;token=8a170144-3b14-47f0-a973-6d295188d816" alt="" width="563"><figcaption></figcaption></figure></div>

#### 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 %}

#### Give It a Name

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 write-only, so you can't view them after saving. See [#integration-categories](#integration-categories "mention") for provider-specific setup notes.

{% hint style="warning" %}
**No automatic validation:** Your credentials are not validated 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 available across the Workspace and can be linked to plugins or features.
{% endstep %}
{% endstepper %}

#### Editing an Integration

Select any integration, or use the edit icon <i class="fa-pen">:pen:</i> in its **Actions** column, to open it. Secret fields open empty: leave one blank to keep the stored value, or type a new value to replace it. If you change the endpoint, base URL, or region, enter the secret, such as the API key, again. You can't save while a required field is empty. Once saved, every plugin or feature using the integration picks up the change automatically.

#### Deleting an Integration

To remove an integration, use the delete action <i class="fa-trash-can">:trash-can:</i> 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. Pick a category when creating an integration, then choose the specific provider.

<table data-view="cards"><thead><tr><th></th><th></th><th data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-microchip">:microchip:</i></h4><h4>AI Models</h4></td><td>Connect LLM providers to power the LLM node, semantic search, language detection, and session analytics</td><td><a href="#ai-models-1">#ai-models-1</a></td></tr><tr><td><h4><i class="fa-toolbox">:toolbox:</i></h4><h4>Tools</h4></td><td>Connect MCP servers and A2A agents that LLM nodes can call during a conversation</td><td><a href="https://docs.helvia.ai/administration/integrations.md#tools-1">Integrations</a></td></tr><tr><td><h4><i class="fa-book-blank">:book-blank:</i></h4><h4>Knowledge</h4></td><td>Sync external document libraries into your agents' retrieval index (RAG)</td><td><a href="#knowledge-1">#knowledge-1</a></td></tr><tr><td><h4><i class="fa-microphone">:microphone:</i></h4><h4>Voice</h4></td><td>Power speech-to-text and text-to-speech on voice-enabled deployments</td><td><a href="#voice-1">#voice-1</a></td></tr><tr><td><h4><i class="fa-address-card">:address-card:</i></h4><h4>CRM</h4></td><td>Pull customer records from your CRM into agent and LiveChat sessions for context</td><td><a href="#crm-1">#crm-1</a></td></tr><tr><td><h4><i class="fa-ticket">:ticket:</i></h4><h4>Ticketing</h4></td><td>Create and update support tickets directly from agent conversations and LiveChat sessions</td><td><a href="#ticketing-1">#ticketing-1</a></td></tr><tr><td><h4><i class="fa-headset">:headset:</i></h4><h4>Live-chat</h4></td><td>Route conversations to a third-party live chat platform when a human takes over from your agent</td><td><a href="#live-chat-1">#live-chat-1</a></td></tr><tr><td><h4><i class="fa-shield-halved">:shield-halved:</i></h4><h4>SSO</h4></td><td>Let your team sign in to the platform with your own identity provider</td><td><a href="#sso-1">#sso-1</a></td></tr><tr><td></td><td></td><td></td></tr></tbody></table>

{% hint style="info" %}
**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](https://docs.helvia.ai/resources/support.md).
{% endhint %}

### AI Models

AI Models are the most important integration category: they connect the large language models (LLMs) that power your agents. 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.

An AI model integration can serve several features across the Console, such as:

* LLM nodes
* Semantic Search (RAG)
* Language Detection
* Session Analysis
* Automated Testing

<details>

<summary><strong>OpenAI</strong></summary>

Standard OpenAI API access.

**Required fields:**

* **API Key**: Your OpenAI API key

</details>

<details>

<summary><strong>Azure</strong></summary>

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

</details>

<details>

<summary><strong>Gemini</strong></summary>

Google's Gemini family of models via the Gemini API.

**Required fields:**

* **API Key**: Your Google AI Studio API key

</details>

<details>

<summary><strong>OpenAI Compatible</strong></summary>

Any endpoint that speaks the OpenAI API, such as vLLM, Ollama, OpenRouter, or your own gateway. The endpoint must serve the API each feature calls, such as chat completions for LLM nodes or embeddings for Semantic Search.

**Required fields:**

* **Base URL**: The endpoint's base URL, including the version segment (for example, `https://my-gateway.example.com/v1`)
* **API Key**: The endpoint's API key, required when **Authentication** is set to **API Key**

</details>

#### 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 integration 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. Each fallback you add needs its own API key.

### Tools

Tools integrations connect your agents to MCP servers and A2A agents, so LLM nodes can call them during a conversation. Register each one here once. Then, in Designer, choose which agents can reach it and which nodes call it, as described in [Tools](https://docs.helvia.ai/build/tools.md).

Every Tools integration has an **Enabled** switch, on by default. Turn it off to stop offering the server or agent to every agent without deleting the integration.

<details>

<summary><strong>MCP Server</strong></summary>

A remote server that exposes a set of tools over the Model Context Protocol. Add **Custom headers** if the server needs extra ones, each with a **Header name** and **Header value**.&#x20;

Run **Test connection** to confirm the server responds and to list the tools it exposes. A failed test shows the reason.

**Required fields:**

* **Server URL**: The server's endpoint, using the `/mcp` path for Streamable HTTP or `/sse` for SSE
* **Transport**: **Streamable HTTP** (the default) or **SSE**, matching what the server supports
* **Method**: How the integration authenticates with the server. See [Authentication](#authentication).

</details>

<details>

<summary><strong>A2A Agent</strong></summary>

An external agent reached over the Agent2Agent protocol. Its Agent Card describes the agent, its endpoint, its skills, and the security it requires. The agent is added as a single tool that routes each call to the skill that fits, so the skills are for reference only.

Run **Fetch card** to confirm the agent responds and to read its name, description, endpoint, and advertised skills.&#x20;

**Required fields:**

* **Agent Card URL**: The public URL of the agent's Agent Card, typically ending in `/.well-known/agent-card.json`. Authentication is read from the card; see [Authentication](#authentication).

</details>

{% hint style="info" %}
**Public https\:// URLs only** MCP servers and A2A agents must be reachable at a public `https://` address. Any on `http://`, private, or local addresses can't be reached.
{% endhint %}

#### Authentication

Tools integrations authenticate as a service account: you set one credential on the integration, every agent in the Workspace uses it, and end users are never prompted. To pass the user's own identity to an MCP server, see [forwarding](https://docs.helvia.ai/build/tools.md#forwarding-the-users-identity) on the Tools page.

| Method                             | What you enter                                             | MCP Server | A2A Agent |
| ---------------------------------- | ---------------------------------------------------------- | ---------- | --------- |
| **Service token (Bearer)**         | A token sent with every request                            | ✅          | ✅         |
| **Basic authentication**           | A **Username** and **Password**                            | ✅          | ❌         |
| **OAuth 2.1 (client credentials)** | A **Client ID**, **Client secret**, and **Token endpoint** | ✅          | ❌         |
| **No authentication**              | —                                                          | ✅          | ✅         |

For an MCP server, you pick the method in the integration. For an A2A agent, the method comes from its Agent Card when you run **Fetch card**. Cards that require OAuth, OpenID Connect, or mTLS aren't supported, and the integration saves without a credential.

### Knowledge

Knowledge integrations sync your internal documents, files, and other knowledge sources into [Knowledge Bases](https://docs.helvia.ai/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.

<details>

<summary><strong>Dynamics 365 KB</strong></summary>

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

</details>

<details>

<summary><strong>SharePoint KB</strong></summary>

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

</details>

<details>

<summary><strong>Azure Blob Storage KB</strong></summary>

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

</details>

#### 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:

<table data-column-title-hidden data-view="cards"><thead><tr><th>Control</th><th>Description</th></tr></thead><tbody><tr><td><h4><i class="fa-file-lines">:file-lines:</i></h4><h4>File Types</h4></td><td>Choose which formats to pull from the source</td></tr><tr><td><h4><i class="fa-wand-magic-sparkles">:wand-magic-sparkles:</i></h4><h4>Additional Instructions</h4></td><td>Natural-language guidance for the AI-Powered segmenter</td></tr><tr><td><h4><i class="fa-tags">:tags:</i></h4><h4>Tags</h4></td><td>Applied to every article the integration generates, feeding RAG retrieval tag filtering</td></tr></tbody></table>

### Voice

Voice integrations power speech-to-text and text-to-speech on voice-enabled deployment channels, so your agents can hold spoken conversations.

<details>

<summary><strong>Azure Speech</strong></summary>

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

</details>

### CRM

CRM integrations pull existing customer records into agent and LiveChat sessions, so conversations start with full context about who the user is.

<details>

<summary><strong>Dynamics 365 CRM</strong></summary>

Read customer records from your Dynamics 365 instance.

**Required fields:**

* **Minor Version**: The minor version of your Dynamics 365 deployment

</details>

### Ticketing

Ticketing integrations let LiveChat human agents create and update support tickets directly from a conversation.

<details>

<summary><strong>Zendesk Ticketing</strong></summary>

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

</details>

### 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.

<details>

<summary><strong>Cisco Customer Collaboration</strong></summary>

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

</details>

<details>

<summary><strong>Zendesk Live Chat</strong></summary>

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

</details>

<details>

<summary><strong>Genesys</strong></summary>

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

</details>

{% 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.

<details>

<summary><strong>OpenID</strong></summary>

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

</details>

### 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 %}
