> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sigmamind.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Vicidial Integration Guide
> This guide walks you through every configuration step needed to connect Vicidial to the SigmaMind Voice AI platform. Once complete, Vicidial will dial your customers through your existing carrier and automatically bridge each answered call to a SigmaMind AI agent in real time — with no manual agent intervention required.
## How It Works
```text theme={null}
Vicidial Campaign dials customer
│
Customer answers
│
Vicidial routes call to Remote Agent
│
Remote Agent dials SigmaMind SIP server
(+1XXXXXXXXXX@28y698lhv2f.sip.livekit.cloud)
│
SigmaMind receives inbound SIP call
│
SigmaMind Voice AI Agent speaks with the customer
```
Behind the scenes, two calls are created — one from Vicidial to the customer, and one from the Remote Agent to the SigmaMind SIP server — but these are transparently bridged into a single conversation. On the SigmaMind side, only one inbound SIP call is ever visible.
The number used in the Vicidial dial string is your existing outbound carrier number — no new number is created. On the SigmaMind side, you register this number under **Phone Numbers → Connect via SIP Trunking**, entering your carrier's SIP termination URI in the **Terminal URI** field and mapping an AI agent against it.
***
## SigmaMind SIP Server Details
All calls from Vicidial to SigmaMind are directed to the following SIP server:
| Field | Value |
| ------------------------- | -------------------------------------------- |
| **SIP Server URI** | `28y698lhv2f.sip.livekit.cloud` |
| **Full Dial Destination** | `+1XXXXXXXXXX@28y698lhv2f.sip.livekit.cloud` |
| **Transport** | UDP, TCP, or TLS |
| **Media Encryption** | SRTP supported |
Replace `+1XXXXXXXXXX` with your Vicidial outbound carrier number — the same number your Vicidial system already uses to make calls. This is the number you register in SigmaMind under **Phone Numbers → Connect via SIP Trunking**, where:
* **Phone Number** = your Vicidial outbound carrier number
* **Terminal URI** = your carrier's SIP termination URI (e.g. `f111.dialmake.com`) — this points **back to your telephony provider**, not to SigmaMind
The SigmaMind SIP server (`28y698lhv2f.sip.livekit.cloud`) is what **Vicidial dials into** — it belongs in the Vicidial Remote Agent dial string only, not in this SigmaMind dashboard field. SigmaMind identifies the correct tenant and AI agent by matching the incoming call's number against the number you registered.
SigmaMind does **not** support static IP whitelisting. If your carrier or PBX requires IP whitelisting to allow outbound SIP, this must be resolved at the carrier level before proceeding. See the [SIP Trunking page](/documentation/phone-number/sip-integration/sip-trunking) for full SIP server requirements.
***
## Prerequisites
Before starting, confirm you have the following ready:
* Admin access to your Vicidial instance
* A SigmaMind account with at least one AI agent configured and published
* Your **Vicidial outbound carrier number** registered in SigmaMind under **Phone Numbers → Connect via SIP Trunking** — this is the same number your Vicidial system dials out from. When registering it in SigmaMind, the **Terminal URI** field must contain your carrier's SIP termination URI (e.g. `f111.dialmake.com`), and an AI agent must be mapped against it
* The **SigmaMind SIP server**: `28y698lhv2f.sip.livekit.cloud` — this is what Vicidial dials into via the Remote Agent, not what goes in the SigmaMind dashboard Terminal URI field
* Your **Vicidial outbound carrier** already configured and tested for outbound calls
* Your Vicidial **dial prefixes** confirmed with your Vicidial admin:
* Auto-dial prefix (e.g. `9797`)
* Manual dial prefix (e.g. `8787`)
* Your Vicidial **server number** (e.g. `103`) confirmed with your admin
**Testing from outside the US:** If you are testing from India or any region with strict telecom geofencing rules, your local carrier may block calls to or from US numbers. Use a softphone (such as Zoiper) connected directly to your Vicidial SIP server to bypass carrier-level restrictions during testing. See [Testing with a Softphone](#testing-with-a-softphone) below.
***
## Before You Begin: Register Your Number in SigmaMind
Before configuring Vicidial, you need to register your Vicidial outbound carrier number in SigmaMind so that SigmaMind can receive the inbound SIP call and know which AI agent to connect.
In your SigmaMind dashboard, navigate to **Phone Numbers** and click **Add Phone Number**.
In the **Add Phone Number** dialog, select the **Connect via SIP Trunking** tab.
Enter the following:
| Field | Value |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Phone Number** | Your Vicidial outbound carrier number (e.g. `+13453453453`) |
| **Terminal URI** | Your carrier's SIP termination URI (e.g. `f111.dialmake.com`) — this is provided by your telephony carrier, not by SigmaMind |
| **SIP Trunk User Name** | Optional — enter only if your carrier requires SIP authentication |
| **SIP Trunk Password** | Optional — enter only if your carrier requires SIP authentication |
The **Terminal URI** points back to your telephony carrier — it is the address your carrier uses to terminate SIP calls. It is **not** the SigmaMind SIP server. The SigmaMind SIP server (`28y698lhv2f.sip.livekit.cloud`) is what Vicidial dials into via the Remote Agent — it belongs in the Vicidial configuration only.
Click **Save**. Once the number is registered, assign an AI agent to it. SigmaMind will use this mapping to identify which agent to connect whenever a call arrives on this number from your Vicidial system.
***
## Step 1: Create a Vicidial User for the SigmaMind Agent
The Remote Agent in Vicidial must be linked to a Vicidial user account. You can create a dedicated user or reuse an existing one.
In the Vicidial Admin panel, navigate to **Admin → Users**.
Use your browser's search (Ctrl+F) to find an existing user designated for SigmaMind (e.g. a user named `SigmaPhone`). Note the **Extension** number assigned to this user — you will need it in Step 2.
If no suitable user exists, create one:
* Set a recognisable **Username** such as `sigma_agent`
* Assign it to the correct **Server** (confirm the server number with your Vicidial admin — e.g. server `103`)
* Save the user and note the assigned **Extension** (e.g. `5565`)
***
## Step 2: Create the Remote Agent
A Remote Agent in Vicidial routes an answered customer call to an external destination — in this case, the SigmaMind SIP server. The key field is the **Remote Extension**, which is the full dial string Vicidial will use to reach SigmaMind.
In the Vicidial Admin panel, navigate to **Admin → Remote Agents**.
Click **Add New Remote Agent** and fill in the following fields:
| Field | Value |
| -------------------- | --------------------------------------------------- |
| **User** | The Vicidial user from Step 1 (e.g. `5565`) |
| **Remote Extension** | The full dial string to reach SigmaMind — see below |
| **Server IP** | **All Servers** |
| **Campaign** | Your SigmaMind campaign (e.g. `Sigma Voice Agent`) |
| **Active** | `Y` |
The **Remote Extension** field must contain the **full dial string** — your carrier's outbound prefix combined with your Vicidial outbound carrier number (the same number you have registered in SigmaMind under **Phone Numbers → Connect via SIP Trunking**). Vicidial will dial this string exactly as entered when routing an answered call to SigmaMind.
The format is:
```text theme={null}
[carrier-prefix][SigmaMind-SIP-number]
```
For example, if your auto-dial carrier prefix is `9797` and your Vicidial outbound carrier number is `+19895551234`, the Remote Extension would be:
```text theme={null}
97919895551234
```
Do not enter just the SigmaMind number alone (e.g. `19895551234`). Without the carrier prefix, Vicidial cannot route the call through the correct carrier and the Remote Agent will fail to dial out. Confirm your carrier prefix with your Vicidial admin.
Click **Submit** to create the Remote Agent.
***
## Step 3: Create the SigmaMind Carrier in Vicidial
In Vicidial's **Carriers** section, create an entry that associates a dial prefix with the SigmaMind routing. This carrier entry is what Vicidial uses to know how to handle outbound calls through this path.
Navigate to **Admin → Carriers**.
Click **Add New Carrier** and configure the following:
| Field | Value |
| ---------------- | ---------------------------------- |
| **Carrier Name** | `Sigma` (or any recognisable name) |
| **Server IP** | All Servers |
| **Active** | `Y` |
In the **Dial Prefix** field, enter the prefix your Vicidial server uses to route outbound calls through this carrier (e.g. `9797` for auto-dial). This must match the prefix prepended in the Remote Extension you set in Step 2, and must match the trunk routing configured on your Vicidial server.
Confirm the correct prefix with your Vicidial admin.
Browse your existing carriers and verify that no other carrier is using the same dial prefix. Duplicate prefixes will cause routing conflicts.
Click **Submit**.
***
## Step 4: Configure the Campaign
Connect all the pieces inside your Vicidial campaign — the carrier, the Remote Agent routing, caller ID, and dial settings.
Go to **Admin → Campaigns** and click into your SigmaMind campaign (e.g. `T-Sigma VA`). Click **Detail** to expand the full settings view.
Scroll down to the **Dial Prefix** field and enter the carrier prefix for auto-dial calls (e.g. `9797`). For manual dials, find the **Manual Dial Prefix** field and set it separately (e.g. `8787`).
These must match the dial prefix set in Step 3.
Find the **Routing Extension** field and enter the same Remote Extension value you used in Step 2 (the full dial string including carrier prefix):
```text theme={null}
97919895551234
```
When a customer answers, Vicidial routes the call to this string, which reaches SigmaMind via the carrier.
Set the **Campaign Caller ID** — the number your customers see when called. Enter your actual outbound number, for example:
```text theme={null}
+13038142839
```
If you plan to use manual dials, find the **Manual CID** field and set it to the same outbound caller ID number.
For initial testing, use conservative settings:
| Field | Value |
| ---------------- | ----- |
| **Dial Level** | `1` |
| **Hopper Level** | `1` |
Increase the dial level only after confirming the end-to-end flow works correctly.
Go to **Real-Time Screen** within the campaign. Confirm the SigmaMind Remote Agent user appears with a **Ready** status. If it is not in Ready state, Vicidial will not route answered calls to it.
Scroll to the bottom and click **Submit**.
***
## Step 5: Prepare the Call List
From within your campaign, scroll down to the **Lists** section and click **Modify** next to your active list.
Ensure at least one lead record exists. To add one:
* Click into the existing record or select **Add Lead**
* Set **Phone Number** to your test number (e.g. `3035500914`)
* Leave **Country** blank (or set to `1` — confirm with your admin)
* Set **Status** to `NEW`
* Save the record
Vicidial only dials records whose current status is marked as dialable. After each call attempt, Vicidial assigns a new status to the record. During testing you will encounter statuses such as `DROP`, `XFER`, and `DNC`. Add all of these upfront so you can re-test without manually editing each record.
In the List settings, find **Dial Statuses** and add:
```text theme={null}
NEW
DROP
DNC
XFER
```
After each test call, check what status the record was set to and add it to the dialable list if it is not already there.
Scroll up in the List Modify screen and click **Reset**, then confirm. Vicidial will immediately begin dialling all records with a dialable status.
***
## Step 6: Test the Integration End-to-End
Before triggering a dial, go to the campaign's **Real-Time Screen** and confirm the SigmaMind Remote Agent user shows **Ready** status.
Follow the reset steps in Step 5. Vicidial will dial the number in your list.
Answer the call on your test phone. Your SigmaMind AI agent should begin speaking within approximately one second.
Allow the AI agent to complete its opening. Speak a response. Confirm the conversation flows naturally in both directions.
While the call is live, check the campaign's **Real-Time Screen**. You should see the Remote Agent user showing a call in progress.
After the call ends, go to **Conversations** in your SigmaMind dashboard. The call should appear with:
* Call status
* Full transcript of the conversation
* Recording (available within a few minutes of the call ending)
Vicidial creates its own recording of the call from the moment the campaign dialled out. This is separate from the SigmaMind recording. Reviewing both helps diagnose any audio or bridging issues.
***
## Step 7: Pass Lead Data via SIP Headers (Optional but Recommended)
You can pass Vicidial lead fields — customer name, city, state, phone number, address — to SigmaMind via custom SIP headers. SigmaMind reads these on the inbound SIP call and makes them available as dynamic variables your AI agent can use in its prompt.
#### How SigmaMind reads SIP headers
SigmaMind automatically processes any inbound SIP header that starts with `X-` or `x-`. It strips the prefix and exposes the remainder as a dynamic variable. For example:
| SIP Header | Variable in SigmaMind |
| --------------------------- | --------------------- |
| `X-customer_name: John Doe` | `{{customer_name}}` |
| `X-city: Denver` | `{{city}}` |
| `X-account_id: 12345` | `{{account_id}}` |
#### Configuring SIP headers in Vicidial
Vicidial can pass custom SIP headers to the outbound SIP leg using its built-in **SIP Header** fields in the carrier configuration, or via the campaign's custom variable passing. The exact mechanism depends on your Vicidial version.
**Part A — Test with a static value first**
Work with your Vicidial admin to add a static custom SIP header to the SigmaMind carrier's outbound SIP configuration. The header name must start with `X-`:
```text theme={null}
X-city: Denver
```
After a test call, go to **Conversations → \[the call] → Dynamic Variables** in SigmaMind. You should see `city: Denver`. If it appears, the pipeline is confirmed.
**Part B — Pass dynamic lead field values**
Once static headers work, replace the static values with Vicidial lead field variables. The variable syntax and available field names depend on your Vicidial version — confirm with your Vicidial admin which lead fields are available and how they are referenced in your setup.
Common lead fields you may want to pass:
```text theme={null}
X-first_name: [value from Vicidial lead field]
X-last_name: [value from Vicidial lead field]
X-city: [value from Vicidial lead field]
X-state: [value from Vicidial lead field]
X-phone_number: [value from Vicidial lead field]
```
Header names must start with `X-`. SigmaMind strips the `X-` prefix to create the variable name — so `X-city` becomes `{{city}}` in your agent prompt. For full details see the [SIP Custom Header guide](/documentation/agents/add-advance-nodes/howto-use-sip-custom-header).
**Part C — Reference variables in your SigmaMind agent prompt**
In your SigmaMind agent's system prompt, reference the variables using double-curly-brace syntax:
```text theme={null}
You are calling {{first_name}} {{last_name}} located in {{city}}, {{state}}.
Their callback number is {{phone_number}}.
```
SigmaMind substitutes these at call time with the values received via SIP headers.
***
## Step 8: Configure AMD (Answering Machine Detection)
For production campaigns, route calls through Vicidial's built-in AMD before handing off to the SigmaMind agent. AMD ensures the AI agent only engages with a live human — not a voicemail system.
In your campaign settings, locate the AMD (Answering Machine Detection) options. Configure routing so that:
* **Live human detected** → Vicidial routes to the Remote Agent → SigmaMind AI agent
* **Answering machine detected** → hang up, or play a pre-recorded voicemail drop
Consult your Vicidial admin for the exact AMD fields in your version, as labels vary between Vicidial releases.
Reset your call list with AMD active and answer the call. With AMD enabled, the SIP call to SigmaMind is only placed after AMD has confirmed a live answer — so the customer will not experience any wait before the AI agent speaks.
Without AMD, there may be a brief moment of ring-back or silence between when the customer answers and when the SigmaMind SIP leg connects. AMD eliminates this from the customer's perspective because the bridge to SigmaMind only begins after pickup is already confirmed.
***
## Testing with a Softphone
If you are testing from a region where carrier-level geofencing prevents calls to or from US numbers (common in India and other countries), use a softphone registered directly to your Vicidial SIP server. This bypasses the carrier and lets you dial the SigmaMind bridge from inside the Vicidial environment.
**Recommended softphone:** [Zoiper](https://www.zoiper.com) (free tier is sufficient for testing)
Download and install Zoiper on your test device.
In Zoiper, add a SIP account pointing to your Vicidial/Asterisk server:
| Field | Value |
| ----------------------- | ------------------------------------------------------------ |
| **Domain / SIP Server** | Your Vicidial server IP or hostname |
| **Username** | The extension of the Vicidial user from Step 1 (e.g. `5565`) |
| **Password** | The SIP password for that user (from Vicidial user settings) |
Once registered, dial the full dial string (carrier prefix + your Vicidial outbound carrier number) directly from Zoiper. This lets you confirm SigmaMind picks up and the AI agent responds, without needing a real outbound carrier call to a customer.
***
## Troubleshooting
### 1. The call is not reaching the Remote Agent
* Verify the Remote Agent user status is **Ready** on the campaign's **Real-Time Screen** before dialling begins — Vicidial will not route to an agent that is not Ready.
* Confirm the campaign's **Routing Extension** field exactly matches the Remote Extension set on the Remote Agent.
* Check that the lead record's current status is in the campaign's **Dialable Statuses** list (see Step 5).
* In Vicidial, click on the Remote Agent user and check **User Stats** — this shows whether a routing attempt was made and what the result was.
### 2. The call reaches the Remote Agent but SigmaMind does not answer
* Confirm the Remote Extension in Step 2 includes the full carrier prefix + your outbound carrier number in the correct format, and that the dial string ends with `@28y698lhv2f.sip.livekit.cloud`.
* Confirm the SigmaMind SIP server hostname (`28y698lhv2f.sip.livekit.cloud`) is correctly included in the Remote Agent dial string.
* Go to **Conversations** in the SigmaMind dashboard. If the call appears there, the SIP connection is working and the issue is on the SigmaMind agent configuration side.
* Confirm the number in your Remote Extension exactly matches the number registered in SigmaMind under **Phone Numbers → Connect via SIP Trunking**, and that it has an active, published AI agent mapped against it.
### 3. The customer hears ringing before the AI speaks
A brief ring-back between the customer answering and the SigmaMind SIP leg connecting is expected in some Vicidial configurations. It occurs while Vicidial establishes the outbound SIP call to SigmaMind.
* **Use AMD in production.** With AMD active, the SIP call to SigmaMind is only placed after the customer has already answered and been confirmed as a live human, so the customer does not experience any wait before the agent speaks.
* If ring-back persists with AMD enabled, raise it with your Vicidial admin — the source may be in how the carrier is generating ring-back signals on the SIP leg between Vicidial and SigmaMind.
### 4. Dynamic variables are not appearing in SigmaMind
* Test with a **static header value first** — if the static value does not appear in SigmaMind Dynamic Variables, the SIP header is not being sent correctly from Vicidial.
* Confirm the header name starts with `X-` — SigmaMind only processes headers with this prefix.
* The variable name in SigmaMind will be the header name with `X-` stripped (e.g. `X-city` → `{{city}}`).
* In SigmaMind, variables only appear in **Conversations → Dynamic Variables** if they are referenced in the agent prompt. Add `{{city}}` to the agent prompt and re-test.
### 5. Call status stays as `AGENT NOT AVAILABLE`
* Confirm the Remote Agent user is in **Ready** status on the campaign's **Real-Time Screen**.
* Verify the Remote Agent is assigned to this specific campaign, not a different one.
* Confirm the **Routing Extension** in the campaign settings matches the **Remote Extension** on the Remote Agent exactly.
### 6. Call completes but no record appears in SigmaMind Conversations
* Confirm the number in your Remote Extension matches the number registered in SigmaMind under **Phone Numbers → Connect via SIP Trunking**.
* Confirm that number has an active, published AI agent mapped against it in SigmaMind.
***
## How Call Transfers Work
When the SigmaMind AI agent transfers a call, no additional Vicidial configuration is required. SigmaMind handles the transfer natively:
* The AI agent drops out of the conversation
* The customer is connected directly to the transfer destination (a human agent, queue, or external number)
* From the customer's perspective, the call continues without interruption
Your existing carrier and caller ID remain in the path for the transfer. No Twilio or third-party bridge is introduced.
***
## How Multiple Agents Work
To route different Vicidial campaigns to different SigmaMind AI agents:
1. In SigmaMind, go to **Phone Numbers → Connect via SIP Trunking** and register each Vicidial outbound carrier number separately, entering the carrier's Terminal URI for each, and mapping each to the correct AI agent
2. In Vicidial, create a separate Remote Agent for each number, using the corresponding full dial string (carrier prefix + carrier number + `@28y698lhv2f.sip.livekit.cloud`) as the Remote Extension
3. Assign each Remote Agent to the relevant campaign
Each campaign routes through its own Remote Agent, which dials its own carrier number into SigmaMind, which connects the corresponding AI agent.
***
## Architecture Reference
### Component Map
| Component | Role |
| ------------------------ | ---------------------------------------------------------------------------------------- |
| **Vicidial Campaign** | Manages the call list, dial pace, AMD, and routing |
| **Vicidial Carrier** | Holds the dial prefix for routing outbound calls |
| **Remote Agent** | Routes the answered customer call to the SigmaMind SIP server using the full dial string |
| **SigmaMind SIP Number** | Inbound entry point — mapped to a specific AI agent |
| **SigmaMind Agent** | The AI voice agent that speaks with the customer |
| **SIP Headers (X-)** | Carry lead data from Vicidial to SigmaMind as dynamic variables |
### Reference Values
| Value | Purpose |
| ------------------------------- | ------------------------------------------------------------- |
| `28y698lhv2f.sip.livekit.cloud` | SigmaMind SIP server hostname |
| `9797` | Example auto-dial prefix — confirm with your Vicidial admin |
| `8787` | Example manual dial prefix — confirm with your Vicidial admin |
| `5565` | Example Vicidial user extension for the Remote Agent |
All prefix and extension values are examples. Your actual values depend on your Vicidial configuration. Always confirm with your Vicidial administrator before applying.
### Call Recording
| Side | What is recorded | When recording starts |
| ------------- | ------------------------------------- | -------------------------------------------- |
| **Vicidial** | Full call from the moment of dialling | When the campaign places the outbound call |
| **SigmaMind** | Agent conversation only | When the SigmaMind AI agent connects via SIP |
Both recordings are independent. Vicidial's recording is useful for diagnosing ring-back or bridging issues. SigmaMind's recording shows exactly what the AI agent heard and said.