# VICIdial Integration
Source: https://docs.sigmamind.ai/VICIdial
#### AI-Powered Call Center Automation for Scalable Customer Engagement
### **Overview of VICIdial**
VICIdial is a widely adopted open-source contact center solution designed to manage high-volume inbound and outbound calling operations. It is commonly used by sales teams, support centers, and contact centers to run efficient communication workflows at scale.
With capabilities such as predictive dialing, automated call distribution, IVR systems, and real-time reporting, VICIdial provides a flexible and cost-effective foundation for modern call center operations.
### Why Integrate VICIdial with Sigmamind AI
Integrating VICIdial with Sigmamind AI enhances traditional call center workflows with AI-powered automation and intelligence. This enables businesses to handle more conversations, improve efficiency, and deliver better customer experiences without increasing operational overhead.
This integration is ideal for:
* Outbound sales and lead generation teams
* Customer support and service operations
* Contact centers handling high call volumes
* Businesses adopting AI-driven communication
***
### Key Capabilities
#### 1. AI-Powered Voice Agents
Automate inbound and outbound calls using conversational AI agents that can engage customers 24/7.
#### 2. Intelligent Lead Qualification & Routing
Use AI to qualify leads in real time and route high-value prospects to the right teams.
#### 3. Enhanced Predictive Dialing
Boost VICIdial’s dialing efficiency with AI-driven decision-making and prioritization.
#### 4. Real-Time Agent Assist
Provide human agents with live suggestions, summaries, and contextual insights during calls.
#### 5. Advanced Call Analytics
Analyze conversations to extract insights, track performance, and optimize campaigns.
#### 6. Workflow Automation
Automatically sync call data with CRMs and internal systems for seamless operations.
***
### Key Benefits
* Reduce operational costs through automation
* Increase conversion rates and campaign performance
* Improve customer experience with AI-driven conversations
* Enhance agent productivity and efficiency
* Scale call center operations without additional infrastructure
***
### How VICIdial Works with Sigmamind AI
#### End-to-End Call Flow
The integration between VICIdial and Sigmamind AI enables a seamless transition from outbound dialing to AI-driven conversations and human agent handoff.
***
### Step-by-Step Flow
#### 1. Outbound Call Initiated (VICIdial)
Vicidial initiates outbound calls using customer data from its internal lists or connected data sources via predictive or auto-dialing campaigns.
#### 2. Customer Connects
Once the customer answers the call, VICIdial detects a successful connection and triggers the next step in the call flow.
#### 3. Call Routed to Sigmamind AI (Inbound)
The active call is transferred to Sigmamind AI as an inbound call, where the AI system takes control of the interaction.
#### 4. AI Agent Handles the Conversation
Sigmamind AI engages the customer to:
* Qualify the lead
* Collect key information
* Answer common questions
* Guide the interaction based on predefined workflows
#### 5. Conditional Human Handoff
Based on predefined conditions (such as user intent, interest level, or escalation triggers), the system determines whether a human agent is required.
#### 6. Call Transfer to Human Agent
If needed, the call is seamlessly transferred to a live agent without losing conversation context, ensuring a smooth customer experience.
#### 7. Call Completion & Outcome Logging
The agent completes the interaction, and the outcome is logged for reporting, analytics, and future follow-ups.
***
### Call Flow Summary
```text theme={null}
VICIdial (Outbound Dialing)
↓
Customer Answers
↓
Call Routed to Sigmamind AI (Inbound)
↓
AI Agent Conversation
↓
(Conditional)
↓
Transfer to Human Agent
↓
Call Completion & Logging
```
***
## Setup Guide:
***
### 📸 Screenshots & Walkthrough
> Placeholder for setup screenshots
# Add Integation Tool
Source: https://docs.sigmamind.ai/add-integation-tool
The **Add Integration Tool** lets your AI agent call external apps and APIs during a live conversation. Use it to look up customer records, update CRM contacts, create bookings, trigger webhooks, or perform any real-world action exposed by a connected integration — all without interrupting the call.
***
## When to Use
Configure this tool when your agent needs to:
* Look up a customer's record in HubSpot, Salesforce, or your own CRM
* Retrieve a policy status, account balance, or order history in real time
* Update a contact's information based on what the customer says
* Create a support ticket, booking, or record mid-conversation
* Trigger any external API action based on conversation context
***
## Prerequisites
Before adding an integration tool to your agent, your integration must already be connected and authenticated.
> See [How to add an Integration](/documentation/tools/add-a-custom-tool) and [How to Configure Authentication](/documentation/tools/authentication) for setup steps.
Once the integration is connected and shows **Auth connected**, you can add its tools to any agent.
***
## Steps to Add via Agent Builder
Adding an integration tool is a **3-step wizard** inside the Agent Builder.
### Step 1: Select the Tool
1. Open the **Agent Builder**
2. Click **+ Add Tool**
3. Select **Add Integration Tool**
4. Choose your connected integration from the list (e.g., HubSpot)
5. The wizard shows all available tool actions for that integration
Each tool action displays:
* The **action name** (e.g., `get_customer_list`, `update_customer_info`)
* The **HTTP method** badge (e.g., `GET`, `PATCH`, `POST`)
* The **endpoint URL** the action calls
Click the tool action you want to add to the agent. If your integration has multiple tools, you can add them one at a time.
**Example — HubSpot tools:**
| Action | Method | Endpoint |
| ---------------------- | ------- | --------------------------------------------------------------- |
| `get_customer_list` | `GET` | `https://api.hubapi.com/contacts/v1/lists/all/contacts/all` |
| `update_customer_info` | `PATCH` | `https://api.hubapi.com/crm/v3/objects/contacts/{{contact_id}}` |
***
### Step 2: Configure the Instruction
After selecting the tool, the wizard moves to the configuration screen.
#### Instruction *(When this tool should be invoked)*
Write a clear, specific instruction that tells the AI agent when to trigger this API call during the conversation.
```text theme={null}
Invoke this tool after the customer provides their name, to look up their
contact record in HubSpot before proceeding.
```
```text theme={null}
Call get_customer_list when the customer asks about their account status
or when you need to retrieve their contact details.
```
```text theme={null}
Use update_customer_info after the customer confirms a change to their
email address or phone number.
```
The agent uses this instruction alongside the live conversation to decide when to make the API call. A vague instruction causes the tool to fire at the wrong time or not at all.
***
### Step 3: Map Response Values as Dynamic Variables
The final step lets you extract values from the API response and save them as `{{variable_name}}` variables for use in subsequent prompts or tool inputs.
#### View Sample Response
After the tool has been run at least once, click **View sample response (from last run)** to see the actual JSON returned by the API.
**Example — HubSpot `get_customer_list` response:**
```json theme={null}
{
"is-primary": true,
"1": {
"value": "53630cb5-e398-4c5c-978e-97b5c87f688c",
"timestamp": 1764927922684,
"saved-at-timestamp": 1764927922687,
"deleted-changed-timestamp": 0
},
"has-more": false,
"vid-offset": 341631764191
}
```
Use **Copy JSON** to copy the full response structure for reference when setting up your mappings.
***
#### Root Path
The **Root path** defines the base key in the response from which field mappings are extracted. It is auto-populated based on the tool name.
```text theme={null}
Root path: hubspot_get_customer_info
```
This scopes all variable names under a consistent namespace so they don't conflict with variables from other tools.
***
#### Add Mapping
Click **+ Add Mapping** to define which fields from the API response should be saved as variables.
Each mapping row has two parts:
* **Response field path** — the key from the JSON response you want to capture (e.g., `1.value`, `vid-offset`)
* **Variable name** — the `{{variable_name}}` the value will be stored as
**Example mappings for HubSpot response:**
| Response Field | Saved as Variable |
| -------------- | ----------------------- |
| `1.value` | `{{contact_guid}}` |
| `1.timestamp` | `{{contact_timestamp}}` |
| `vid-offset` | `{{vid_offset}}` |
| `has-more` | `{{has_more_contacts}}` |
Once mapped, these variables are immediately available in all subsequent prompts and tool inputs within the same agent:
```text theme={null}
"I found your account, {{customer_name}}. Your contact ID is {{contact_guid}}."
```
```text theme={null}
https://api.hubapi.com/crm/v3/objects/contacts/{{contact_guid}}
```
> Reference these variables as `{{variable_name}}` in any subsequent prompt or tool input field.
***
## Full Example: HubSpot Lookup + Update Flow
**Scenario:** An insurance renewal agent looks up the customer in HubSpot, then updates their renewal status after confirmation.
### Tool 1 — `get_customer_list`
| Field | Value |
| ----------- | ---------------------------------------------------------------------------------------------- |
| Instruction | Look up the customer in HubSpot after they provide their name and confirm their email address. |
| Root path | `hubspot_get_customer_info` |
| Mapping | `1.value` → `{{contact_guid}}` |
### Tool 2 — `update_customer_info`
| Field | Value |
| ----------- | ------------------------------------------------------------------------------------------------- |
| Instruction | Call this tool after the customer confirms they want to renew, to update their record in HubSpot. |
| Endpoint | `https://api.hubapi.com/crm/v3/objects/contacts/{{contact_guid}}` |
| Body | `{ "renewal_status": "confirmed", "renewal_date": "{{renewal_date}}" }` |
The `{{contact_guid}}` extracted from the first tool flows directly into the endpoint URL of the second tool — no manual copying or re-entry needed.
***
## Using Dynamic Variables in Integration Tools
Variables from **Extract Dynamic Variables** or from a previous integration tool's response mapping can be used anywhere in your tool configuration:
**In endpoint URLs:**
```text theme={null}
https://api.hubapi.com/crm/v3/objects/contacts/{{contact_id}}
```
**In request body:**
```json theme={null}
{
"email": "{{customer_email}}",
"policy": "{{policy_number}}",
"status": "{{renewal_status}}"
}
```
**In headers:**
```text theme={null}
Authorization: Bearer {{access_token}}
```
***
## Best Practices
* Write **specific Instructions** for each tool — if two tools have similar descriptions, the agent may call the wrong one
* Always check **Auth connected** is showing before adding a tool to your agent — unauthenticated tools will fail silently
* Use **response mapping** to extract IDs and keys from the first API call, so subsequent calls can reference them without re-asking the customer
* Add mappings only for fields you will actually use — unnecessary variables add noise to the agent context
* Test each tool independently using the **Test** button in the Tool Library before combining them in a live agent flow
* Combine with **Extract Dynamic Variables** to capture customer-provided values before making API calls that need them
***
## Troubleshooting
| Issue | Fix |
| --------------------------------------- | -------------------------------------------------------------------------------- |
| Auth connected not showing | Re-authenticate the integration in the Integrations section |
| API call returning an error | Use the sample response viewer to check the endpoint and payload format |
| Variable not resolving in next tool | Confirm the mapping is saved and the variable name matches exactly |
| Wrong tool being triggered | Rewrite the Instruction to be more specific and distinct from other tools |
| Response fields not appearing in sample | Run the tool at least once via the Test button to populate the last run response |
# Manage Members
Source: https://docs.sigmamind.ai/add-members
The **Members** page allows workspace administrators to manage team access and collaboration within the platform. From this section, admins can view all existing members, invite new users to the workspace, and remove members when needed.
### Navigate
Go to:\
**Settings → Members**
#### You Can View
* Member Name
* Email ID
* Role
* Status
* Created Date
***
## Invite a Team Member
## Steps
1. Go to the **Dashboard**
2. Click on **Settings**
3. Click on **Members**
4. Click **“Invite a new member”**
1. Enter:
* **Member’s Name**
* **Member’s Email ID**
2. Click **“Send Invite”**
***
## What Happens Next
* The invited user receives an email invitation
* After accepting, they are added to the workspace
* The member appears in the **Members list**
***
# Delete (Remove) a Member
## Steps
1. Go to **Settings**
2. Click on **Members**
3. Find the member you want to remove
4. Click the **three-dot menu (⋯)** on the right side
5. Click **“Delete”**
6. Confirm the action
# Amazon Connect
Source: https://docs.sigmamind.ai/amazon-connect
# Create Agent
Source: https://docs.sigmamind.ai/api-reference/agents/create-agent
post /v1/agents
Creates a new single prompt agent with the specified configuration, including system prompt and agent settings. Returns the created agent including its agentId, which is required for all subsequent update, call, and simulation operations.
# Update Agent
Source: https://docs.sigmamind.ai/api-reference/agents/update-agent
patch /v1/agents/{agentId}
Partially updates an existing agent by agentId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated agent record.
# Create Batch Run
Source: https://docs.sigmamind.ai/api-reference/batch-runs/create-batch-run
post /v1/batch-runs
Triggers a new batch run by executing the specified test cases in parallel against the selected agent. Returns the created batch including its batchId, which is required for subsequent get and list test-run calls.
# Get Batch Run
Source: https://docs.sigmamind.ai/api-reference/batch-runs/get-batch-run
get /v1/batch-runs/{batchId}
Retrieves the full details of a batch run by batchId, scoped to the specified agent. Returns overall batch status, test case count, pass/fail summary, and individual run results.
# List Batch Runs
Source: https://docs.sigmamind.ai/api-reference/batch-runs/list-batch-runs
get /v1/batch-runs
Returns a paginated list of batch runs for the specified agent, sorted by most recently created first. Use page and size to navigate through results.
# Create Batch Run
Source: https://docs.sigmamind.ai/api-reference/batch/create-batch-run
post /v1/batch-runs
Triggers a new batch run by executing the specified test cases in parallel against the selected agent. Returns the created batch including its batchId, which is required for subsequent get and list test-run calls.
# Get Batch Run
Source: https://docs.sigmamind.ai/api-reference/batch/get-batch-run
get /v1/batch-runs/{batchId}
Retrieves the full details of a batch run by batchId, scoped to the specified agent. Returns overall batch status, test case count, pass/fail summary, and individual run results.
# List Batch Runs
Source: https://docs.sigmamind.ai/api-reference/batch/list-batch-runs
get /v1/batch-runs
Returns a paginated list of batch runs for the specified agent, sorted by most recently created first. Use page and size to navigate through results.
# Create Phone Call
Source: https://docs.sigmamind.ai/api-reference/calls/create-phone-call
post /v1/calls
Initiates an outbound call with the specified agent, caller, and destination numbers. Supports dynamic variables for personalization. Returns the created call record, including the callId for future retrieval or cancellation.
# Delete Phone Call
Source: https://docs.sigmamind.ai/api-reference/calls/delete-phone-call
delete /v1/calls/{callId}
Permanently deletes a call record by callId. Cannot be undone. Returns 204 No Content on success.
# Get Phone Call
Source: https://docs.sigmamind.ai/api-reference/calls/get-phone-call
get /v1/calls/{callId}
Retrieves the full details of a single call record by callId. Returns call status, direction, assigned agent, phone numbers, duration, and transcript metadata.
# List Phone Calls
Source: https://docs.sigmamind.ai/api-reference/calls/list-phone-calls
get /v1/calls
Returns a paginated list of call records for the account, sorted by most recently created first. Use the status parameter to filter by call state. Use page and size to navigate through results.
# Create Campaign
Source: https://docs.sigmamind.ai/api-reference/campaigns/create-campaign
post /v1/campaigns
Creates an outbound call campaign with the specified agent, caller number, and CSV contact list. Set isScheduled=true with scheduledDate, scheduledTime, and scheduledTimezone to defer launch. Returns the created campaign, including its campaignId.
# Delete Campaign
Source: https://docs.sigmamind.ai/api-reference/campaigns/delete-campaign
delete /v1/campaigns/{campaignId}
Permanently deletes a campaign by campaignId. Cannot be undone — the campaign must have no associated calls before deletion. Returns 204 No Content on success.
# Get Campaign
Source: https://docs.sigmamind.ai/api-reference/campaigns/get-campaign
get /v1/campaigns/{campaignId}
Retrieves the full details of a single campaign by campaignId. Returns current status, schedule configuration, assigned agent, caller number, and any CSV upload errors.
# List Campaigns
Source: https://docs.sigmamind.ai/api-reference/campaigns/list-campaigns
get /v1/campaigns
Returns a paginated list of campaigns for the account, sorted by most recently created first. Use the status parameter to filter by lifecycle state. Use page and size to navigate through results.
# Update Campaign
Source: https://docs.sigmamind.ai/api-reference/campaigns/update-campaign
patch /v1/campaigns/{campaignId}
Partially updates an existing campaign by campaignId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated campaign record.
# Chat Completion
Source: https://docs.sigmamind.ai/api-reference/chats/chat-completion
post /v1/chats/response
Submits a new customer message to an in_progress chat session and returns the agent's reply. The session must be active — calls against an ended session will be rejected. Returns the agent's response and updated session state.
# Create Chat
Source: https://docs.sigmamind.ai/api-reference/chats/create-a-chat
post /v1/chats
Creates a new chat session with the specified agent and sends the initial message. Returns the agent’s reply along with the chatId for subsequent completion, update, and end-session calls.
# Create Chat
Source: https://docs.sigmamind.ai/api-reference/chats/create-chat
post /v1/chats
Creates a new chat session with the specified agent and sends the initial message. Returns the agent’s reply along with the chatId for subsequent completion, update, and end-session calls.
# End Chat
Source: https://docs.sigmamind.ai/api-reference/chats/end-chat
patch /v1/chats/{chatId}/end-session
Ends an in_progress chat session by chatId, marking it as completed. No further messages can be submitted after a session is ended. Returns the final session record.
# Get Chat
Source: https://docs.sigmamind.ai/api-reference/chats/get-chat
get /v1/chats/{chatId}
Retrieves the full details of a single chat session by chatId. Returns the session status, assigned agent, message history, and dynamic variables.
# List Chats
Source: https://docs.sigmamind.ai/api-reference/chats/list-chats
get /v1/chats
Returns a paginated list of chat sessions for the account, sorted by most recently created first. Use the status parameter to filter by session state. Use page and size to navigate through results.
# Update Chat
Source: https://docs.sigmamind.ai/api-reference/chats/update-chat
patch /v1/chats/{chatId}
Partially updates an in_progress chat session by chatId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated session record.
# Create Integration Auth
Source: https://docs.sigmamind.ai/api-reference/integration-auth/create-integration-auth
post /v1/integrations/{integrationId}/auth
Creates and stores authentication credentials for an integration. Supports three auth types: API Key, Basic auth, and Bearer token. Returns the created auth record including its authId, which is required for subsequent get, update, and delete calls.
# Delete Integration Auth
Source: https://docs.sigmamind.ai/api-reference/integration-auth/delete-integration-auth
delete /v1/integrations/{integrationId}/auth/{authId}
Permanently deletes an auth record by authId. Cannot be undone — any tools referencing this auth record will lose the ability to authenticate. Returns 204 No Content on success.
# Get Integration Auth
Source: https://docs.sigmamind.ai/api-reference/integration-auth/get-integration-auth
get /v1/integrations/{integrationId}/auth/{authId}
Retrieves the full details of a single auth record by authId. Returns the auth type, credential metadata, and associated integration. Sensitive credential values are not returned after creation.
# List Integration Auth
Source: https://docs.sigmamind.ai/api-reference/integration-auth/list-integration-auth
get /v1/integrations/{integrationId}/auth
Returns a paginated list of auth records for a given integration, sorted by most recently created first. Use the authType parameter to filter by credential type. Use page and size to navigate through results.
# List Integration Auth
Source: https://docs.sigmamind.ai/api-reference/integration-auth/list-integration-auth-records
get /v1/integrations/{integrationId}/auth
Returns a paginated list of auth records for a given integration, sorted by most recently created first. Use the authType parameter to filter by credential type. Use page and size to navigate through results.
# Update Integration Auth
Source: https://docs.sigmamind.ai/api-reference/integration-auth/update-integration-auth
patch /v1/integrations/{integrationId}/auth/{authId}
Partially updates an existing auth record by authId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated auth record.
# Create Tool
Source: https://docs.sigmamind.ai/api-reference/integration-tools/create-tool
post /v1/integrations/{integrationId}/tools
Creates a new API tool under the specified integration. Define the HTTP endpoint, method, and parameter schema the agent will use when invoking the tool. Returns the created tool including its toolId, which is required for subsequent get, update, delete, and execute calls.
# Delete Tool
Source: https://docs.sigmamind.ai/api-reference/integration-tools/delete-tool
delete /v1/integrations/{integrationId}/tools/{toolId}
Permanently deletes a tool by toolId — cannot be undone. Any agent using this tool will lose access immediately. Returns 204 No Content on success.
# Execute Tool
Source: https://docs.sigmamind.ai/api-reference/integration-tools/execute-tool
post /v1/integrations/{integrationId}/tools/{toolId}/execute
Executes a tool against its configured third-party API using the supplied placeholder values. Auth credentials are resolved automatically; specify authId to select specific credentials when multiple exist. Returns the raw response from the external API including status code, headers, and body.
# Get Tool
Source: https://docs.sigmamind.ai/api-reference/integration-tools/get-tool
get /v1/integrations/{integrationId}/tools/{toolId}
Retrieves the full configuration of a single tool by toolId. Returns the tool's endpoint, HTTP method, parameter schema, and access type.
# List Tools
Source: https://docs.sigmamind.ai/api-reference/integration-tools/list-tools
get /v1/integrations/{integrationId}/tools
Returns a paginated list of tools registered under an integration, sorted by most recently created first. Use the status parameter to filter by tool state. Use page and size to navigate through results.
# Update Tool
Source: https://docs.sigmamind.ai/api-reference/integration-tools/update-tool
patch /v1/integrations/{integrationId}/tools/{toolId}
Partially updates an existing tool by toolId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated tool record.
# Create Integration
Source: https://docs.sigmamind.ai/api-reference/integrations/create-integration
post /v1/integrations
Registers a new third-party integration for your account. Supply the provider type (e.g. shopify, cal_com) along with an optional friendly name and description. Returns the created integration including its integrationId, which is required for all subsequent auth and tool operations.
# Delete Integration
Source: https://docs.sigmamind.ai/api-reference/integrations/delete-integration
delete /v1/integrations/{integrationId}
Permanently deletes an integration by integrationId, including all associated auth credentials and tools. Cannot be undone. Returns 204 No Content on success.
# Get Integration
Source: https://docs.sigmamind.ai/api-reference/integrations/get-integration
get /v1/integrations/{integrationId}
Retrieves the full details of a single integration by integrationId. Returns the provider type, friendly name, description, and current status of the integration.
# List Integrations
Source: https://docs.sigmamind.ai/api-reference/integrations/list-integrations
get /v1/integrations
Returns a paginated list of integrations registered on the account, sorted by most recently created first. Use the provider parameter to filter by integration type. Use page and size to navigate through results.
# Update Integration
Source: https://docs.sigmamind.ai/api-reference/integrations/update-integration
patch /v1/integrations/{integrationId}
Partially updates an existing integration by integrationId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated integration record.
# Introduction
Source: https://docs.sigmamind.ai/api-reference/introduction
Example section for showcasing API endpoints
If you're not looking to build API reference documentation, you can delete
this section by removing the api-reference folder.
## Welcome
There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification.
View the OpenAPI specification file
## Authentication
All API endpoints are authenticated using Bearer tokens and picked up from the specification file.
```json theme={null}
"security": [
{
"bearerAuth": []
}
]
```
# Create knowledge base
Source: https://docs.sigmamind.ai/api-reference/knowledge-bases/create-knowledge-base
post /v1/knowledge-bases
Creates a knowledge base by providing a name, optional text snippets, URLs, and file attachments. Sources are processed in order: text, URLs, then files. Supported file types include PDF, TXT, HTML, Markdown, and DOCX. Maximum file size is 25 MB.
# Delete knowledge base
Source: https://docs.sigmamind.ai/api-reference/knowledge-bases/delete-knowledge-base
delete /v1/knowledge-bases/{kbId}
Deletes a knowledge base along with all its associated sources. This action is irreversible.
# Delete document
Source: https://docs.sigmamind.ai/api-reference/knowledge-bases/delete-one-document-from-a-knowledge-base
delete /v1/knowledge-bases/{kbId}/documents/{documentId}
Deletes a specific source from a knowledge base. Other sources remain unaffected.
# Get knowledge base
Source: https://docs.sigmamind.ai/api-reference/knowledge-bases/get-knowledge-base-by-kbid
get /v1/knowledge-bases/{kbId}
Retrieves a single knowledge base along with its associated sources and timestamps.
# List knowledge bases
Source: https://docs.sigmamind.ai/api-reference/knowledge-bases/list-knowledge-bases
get /v1/knowledge-bases
Returns a paginated list of knowledge bases for the account, sorted by most recently updated. Each item includes its sources and timestamps. Use page and size for pagination.
# Update knowledge base
Source: https://docs.sigmamind.ai/api-reference/knowledge-bases/update-knowledge-base
patch /v1/knowledge-bases/{kbId}
Updates a knowledge base by adding new sources and/or modifying its name. Supported file types include PDF, TXT, HTML, Markdown, and DOCX. Maximum file size is 25 MB.
# Create Phone Number
Source: https://docs.sigmamind.ai/api-reference/phone-numbers/create-phone-number
post /v1/phone-numbers
Purchases and provisions a new phone number for your account. Provide a specific phoneNumber in +E.164 format, or a countryCode (optionally areaCode) to auto-select one. Returns the provisioned number, including its sipPhoneNumber for subsequent get, update, and delete calls.
# Delete Phone Number
Source: https://docs.sigmamind.ai/api-reference/phone-numbers/delete-phone-number
delete /v1/phone-numbers/{phoneNumber}
Permanently removes a phone number from your account — provisioned numbers are released to the carrier, BYO numbers remain with your telecom provider. Cannot be undone. Returns 204 No Content on success.
# Get Phone Number
Source: https://docs.sigmamind.ai/api-reference/phone-numbers/get-phone-number
get /v1/phone-numbers/{phoneNumber}
Retrieves the full configuration of a single phone number by its +E.164 value. Returns assigned agents, active status, provider, and SIP configuration for BYO numbers.
# Import Phone Number
Source: https://docs.sigmamind.ai/api-reference/phone-numbers/import-phone-number
post /v1/phone-numbers/import
Imports an existing phone number via SIP trunking (BYO). Provide the number in +E.164 format along with SIP credentials (trunkUsername, trunkPassword, terminationSipURI). Returns the imported number, including its sipPhoneNumber.
# List Phone Numbers
Source: https://docs.sigmamind.ai/api-reference/phone-numbers/list-phone-numbers
get /v1/phone-numbers
Returns a paginated list of all phone numbers registered on the account, sorted by most recently added first. Includes both SigmaMind-provisioned numbers and BYO numbers imported via SIP trunking. Use page and size to navigate through results.
# Update Phone Number
Source: https://docs.sigmamind.ai/api-reference/phone-numbers/update-phone-number
patch /v1/phone-numbers/{phoneNumber}
Partially updates the configuration of an existing phone number. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated phone number record.
# Get QA Issue
Source: https://docs.sigmamind.ai/api-reference/qa-issues/get-qa-issue
get /v1/qa-issues/{qaIssueId}
Retrieves the full details of a single QA issue by qaIssueId. Returns the issue record including its associated QA rule, status, reasons, and any metadata captured at detection time.
# List QA Issues
Source: https://docs.sigmamind.ai/api-reference/qa-issues/list-qa-issues
get /v1/qa-issues
Returns a paginated list of QA issues for the specified QA rule, sorted by most recently created first. Use page and size to navigate through results.
# Create QA Rule
Source: https://docs.sigmamind.ai/api-reference/qa-rules/create-qa-rule
post /v1/qa-rules
Creates a new QA rule with the specified configuration. Define the rule's evaluation criteria and expected result. Returns the created QA rule, including its qaRuleId for subsequent get, update, delete, and issue-listing calls.
# Delete QA Rule
Source: https://docs.sigmamind.ai/api-reference/qa-rules/delete-qa-rule
delete /v1/qa-rules/{qaRuleId}
Permanently deletes a QA rule by qaRuleId. Cannot be undone — the rule will no longer be evaluated against future interactions. Returns 204 No Content on success.
# Get QA Rule
Source: https://docs.sigmamind.ai/api-reference/qa-rules/get-qa-rule
get /v1/qa-rules/{qaRuleId}
Retrieves the full details of a single QA rule by qaRuleId. Returns the rule configuration including its evaluation criteria, expected value, and agents it will be applied to.
# List QA Rules
Source: https://docs.sigmamind.ai/api-reference/qa-rules/list-qa-rules
get /v1/qa-rules
Returns a paginated list of all QA rules, sorted by most recently created first. Use page and size to navigate through results.
# Update QA Rule
Source: https://docs.sigmamind.ai/api-reference/qa-rules/update-qa-rule
patch /v1/qa-rules/{qaRuleId}
Partially updates an existing QA rule by qaRuleId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated QA rule record.
# Create Agent
Source: https://docs.sigmamind.ai/api-reference/single-prompt-agents/create-agent
post /v1/agents
Creates a new single prompt agent with the specified configuration, including system prompt and agent settings. Returns the created agent including its agentId, which is required for all subsequent update, call, and simulation operations.
# Delete Agent
Source: https://docs.sigmamind.ai/api-reference/single-prompt-agents/delete-agent
delete /v1/agents/{agentId}
Permanently deletes an agent from your account. Cannot be undone.
# Get Agent
Source: https://docs.sigmamind.ai/api-reference/single-prompt-agents/get-agent
get /v1/agents/{agentId}
Retrieves the full details of a single prompt agent, along with agent settings.
# List Agents
Source: https://docs.sigmamind.ai/api-reference/single-prompt-agents/list-single-prompt-agents
get /v1/agents
Retrieve a paginated list of all single prompt agents available in the account along with their details and configurations.
# Update Agent
Source: https://docs.sigmamind.ai/api-reference/single-prompt-agents/update-agent
patch /v1/agents/{agentId}
Partially updates an existing agent by agentId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated agent record.
# Create Test Case
Source: https://docs.sigmamind.ai/api-reference/test-cases/create-test-case
post /v1/test-cases
Creates a simulation test case for the specified agent. Define the scenario using user persona, goals, and evaluation criteria. Returns the created test case, including its testCaseId for subsequent get, update, delete, and batch-run calls.
# Delete Test Case
Source: https://docs.sigmamind.ai/api-reference/test-cases/delete-test-case
delete /v1/test-cases/{testCaseId}
Permanently deletes a simulation test case by testCaseId. Cannot be undone — the test case will no longer be available for future batch runs. Returns 204 No Content on success.
# Get Test Case
Source: https://docs.sigmamind.ai/api-reference/test-cases/get-test-case
get /v1/test-cases/{testCaseId}
Retrieves the full details of a single simulation test case by testCaseId. Returns the conversation scenario definition, including the user persona, goals, evaluation criteria, and current status.
# List Test Cases
Source: https://docs.sigmamind.ai/api-reference/test-cases/list-test-cases
get /v1/test-cases
Returns a paginated list of simulation test cases for the specified agent, sorted by most recently created first. Use page and size to navigate through results.
# Update Test Case
Source: https://docs.sigmamind.ai/api-reference/test-cases/update-test-case
patch /v1/test-cases/{testCaseId}
Partially updates an existing simulation test case by testCaseId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated test case record.
# Get Test Run
Source: https://docs.sigmamind.ai/api-reference/test-runs/get-test-run
get /v1/test-runs/{jobId}
Retrieves the full details of a single test run by jobId, scoped to the specified batch and agent. Returns the test case name, execution status, expected and actual outcomes, and transcript details.
# List Test Runs
Source: https://docs.sigmamind.ai/api-reference/test-runs/list-test-runs
get /v1/test-runs
Returns a paginated list of test run results for the specified batch, sorted by most recently created first. Use page and size to navigate through results.
# Create Webhook
Source: https://docs.sigmamind.ai/api-reference/webhooks/create-webhook
post /v1/webhooks
Registers a new webhook to receive real-time event notifications on your HTTPS endpoint. The webhook is scoped to a single agent and fires only for the event types you specify. Returns the created webhook including its webhookId and HMAC secret — store the secret securely as it is only returned once.
# Delete Webhook
Source: https://docs.sigmamind.ai/api-reference/webhooks/delete-webhook
delete /v1/webhooks/{webhookId}
Permanently removes a webhook by webhookId. Cannot be undone — no further event deliveries will be attempted to the registered URL. Returns 204 No Content on success.
# Get Webhook
Source: https://docs.sigmamind.ai/api-reference/webhooks/get-webhook
get /v1/webhooks/{webhookId}
Retrieves the full configuration of a single webhook by webhookId. Returns the target URL, scoped agent, subscribed event types, and active status. The HMAC secret is not returned after creation — store it securely when the webhook is first created.
# List Webhooks
Source: https://docs.sigmamind.ai/api-reference/webhooks/list-webhooks
get /v1/webhooks
Returns a paginated list of webhooks for the account, sorted by most recently created first. Use agentId to filter by agent and active to filter by enabled/disabled status. Use page and size to navigate through results.
# SigmaMind AI Integration with Gorgias
Source: https://docs.sigmamind.ai/app-integration/gorgias
This document provides a step-by-step guide for developers on how to integrate the Gorgias customer service platform with the SigmaMind AI platform. This integration allows for seamless synchronization of Gorgias data, such as macros, ticket tags, rules, and helpdesk FAQs, with your SigmaMind AI agents.
## Table of Contents
* [Prerequisites](#prerequisites)
* [Integration Steps](#integration-steps)
* [1. Access Gorgias Settings](#1-access-gorgias-settings)
* [2. Navigate to App Store](#2-navigate-to-app-store)
* [3. Search for SigmaMind AI](#3-search-for-sigma-mind-ai)
* [4. Connect the App](#4-connect-the-app)
* [5. Authorize Permissions](#5-authorize-permissions)
* [6. Confirm Authorization](#6-confirm-authorization)
* [7. Verify Connection](#7-verify-connection)
* [Synchronization Details](#synchronization-details)
* [Troubleshooting](#troubleshooting)
## Prerequisites
* An active Gorgias account.
* Access to the Gorgias dashboard with administrative privileges.
* An active SigmaMind AI account.
## Integration Steps
Follow these steps to integrate Gorgias with SigmaMind AI:
### 1. Access Gorgias Settings
From your Gorgias dashboard, locate and click on "Settings".
### 2. Navigate to App Store
Within the "Settings" menu, select "App Store".
### 3. Search for SigmaMind AI
In the Gorgias App Store, use the search bar to find "Sigma" or "SigmaMind". The "SigmaMind AI" app should appear in the search results.
### 4. Connect the App
Click on the "SigmaMind AI" app from the search results, then select "Connect App".
### 5. Authorize Permissions
A prompt will appear requesting various permissions for SigmaMind AI to access your Gorgias data. These permissions are critical for the synchronization process. The permissions typically include access to:
* Gorgias macros (response templates)
* Ticket tags
* Rules
* Helpdesk FAQs
This synchronization ensures that any changes made in Gorgias are automatically reflected and updated in your SigmaMind AI agents.
### 6. Confirm Authorization
Carefully review the requested permissions to understand the data access being granted. Once reviewed, click "Authorize" to proceed with the integration.
### 7. Verify Connection
To confirm that the integration was successful, perform the following steps:
1. Go back to "Settings".
2. Select "HTTP Integration".
3. Under "HTTP Integration," click on the "Manage" tab.
4. You should see that the "SigmaMind AI" app is listed and "turned on", indicating a successful connection.
## Synchronization Details
The integration facilitates a one-click installation and ensures continuous synchronization of the following Gorgias entities with your SigmaMind AI agents:
* **Macros**: Response templates created in Gorgias are synced to SigmaMind AI.
* **Ticket Tags**: Tags used for categorizing tickets in Gorgias are available in SigmaMind AI.
* **Rules**: Automation rules defined in Gorgias are synchronized.
* **Helpdesk FAQs**: Frequently asked questions and their answers managed in Gorgias are integrated into SigmaMind AI.
This automatic synchronization ensures that your AI agents always have the most up-to-date information from your Gorgias helpdesk.
## Troubleshooting
If you encounter issues during the integration process:
* **Permissions**: Ensure all requested permissions were granted during the authorization step.
* **App Status**: Verify that the "SigmaMind AI" app is "turned on" under "HTTP Integration" -> "Manage" in Gorgias settings.
* **Gorgias/SigmaMind AI Status**: Check the status pages for both Gorgias and SigmaMind AI for any ongoing service disruptions.
* **Contact Support**: If the issue persists, contact the support teams for Gorgias or SigmaMind AI for further assistance.
# Integrating Shopify with SigmaMind AI
Source: https://docs.sigmamind.ai/app-integration/shopify
This guide provides a detailed, step-by-step process for developers to integrate a Shopify store with SigmaMind AI. This integration empowers AI agents to securely access real-time store information and perform automated actions, enhancing customer support and store management capabilities.
***
## Section 1: Prerequisites
Before you begin, ensure you have the following:
* **Shopify Partner Account:** A Shopify Partner account is essential for managing development activities and requesting access to merchant stores. If you don't have one, create it at [partners.shopify.com](https://partners.shopify.com/).
* **Shopify Store URL:** The exact URL of the Shopify store you intend to integrate.
* **Collaborator Request Code (if applicable):** For most merchant stores, a collaborator request code will be required. This code must be obtained directly from the merchant, typically found in the "Security" page of their Shopify Admin.
***
## Section 2: Requesting Access to a Shopify Store
This section details how to gain the necessary permissions for your AI agent to interact with a Shopify store.
### Step 2.1: Initiate Store Access Request
1. Log in to your Shopify Partner account.
2. From the dashboard, navigate to the **"Stores"** section.
3. Click on **"Request access to a store."**
4. In the prompt, enter the **Store URL** of the Shopify store you wish to integrate (e.g., `your-store-name.myshopify.com`).
5. If the merchant store requires a collaborator request code, enter the code provided by the merchant.
### Step 2.2: Define Permissions (Access Scopes)
This is a critical step where you define the scope of access for your AI agent. The permissions you select here will determine what information your AI can fetch and what actions it can perform. You will only be able to select permissions that the store owner grants you.
* **General Permissions:**
* **Manage orders information:** Allows the AI to view and manage order details.
* **Edit orders:** Enables the AI to modify existing orders.
* **Apply discounts:** Grants the AI the ability to apply discounts to orders.
* **Return orders:** Allows the AI to process order returns.
* **Refund orders:** Enables the AI to issue refunds for orders.
* **Cancel orders:** Grants the AI the ability to cancel orders.
* **Administration Permissions (Crucial for App Development):**
* **View apps developed by staff and collaborators:** **This permission is absolutely essential** for the next step of setting up your custom app. Without it, you will not be able to create or manage apps on the store.
* **Enable app development:** This permission is necessary to activate the app development features for the store.
* **Develop apps:** This permission allows you to create and manage custom applications within the Shopify store's environment.
* **Other Relevant Permissions:**
* Review and select any other permissions your AI agent will need based on its intended functionality. This may include:
* **Product Information:** Access to product details, inventory levels.
* **Customer Data:** Access to customer profiles, order history.
* **FAQs/Content:** Access to store content for answering customer queries.
* `read_customer_events`
* `read_customers`
* `read_discounts`
* `read_inventory`
* `read_themes`
* `read_orders`
* `read_products`
* `read_reports`
* `read_locations`
* `read_marketing_events`
### Step 2.3: Submit Request
1. Once all necessary permissions have been carefully selected, submit the access request.
2. The merchant will then receive a request to grant you access with the specified permissions.
***
## Section 3: Setting Up the SigmaMind AI Custom App
After the merchant grants you access to their Shopify store, you can proceed with setting up the custom application that SigmaMind AI will use to interact with the store.
### Step 3.1: Access Shopify Admin and App Development
1. Navigate to the Shopify store's administrative interface (Shopify Admin).
2. From the Shopify Admin sidebar, go to **"Settings."**
3. Within the settings menu, click on **"Apps and sales channels."**
4. Under "Apps and sales channels," locate and click on **"Develop apps."**
### Step 3.2: Create a New Custom App
1. Click on the **"Create an app"** button.
2. **App Name:** Enter a descriptive and easily identifiable name for your application (e.g., "SigmaMind AI Integration," "AI Assistant for Store").
3. **App Developer:** Select your email ID from the dropdown list as the designated app developer.
4. Click **"Create app"** to finalize the app creation.
### Step 3.3: Configure Admin API Scopes
This step is crucial for defining the specific API permissions for your custom app. These permissions dictate what data your app can read and write via the Shopify Admin API.
1. After creating the app, you will be directed to the app's overview page. Click on **"Configure Admin API scopes."**
2. On this screen, you will see a list of available API permissions. **Important:** You will only be able to select permissions that were granted to you in the initial store access request (Section 2.2).
3. Select all the necessary API scopes that your AI agent will require to function effectively. This includes, but is not limited to, the following commonly used scopes:
* `read_customer_events`
* `read_customers`
* `read_discounts`
* `read_inventory`
* `read_themes`
* `read_orders`
* `read_products`
* `read_reports`
* `read_locations`
* `read_marketing_events`
4. After selecting all the required scopes, click **"Save"** to apply your changes.
***
## Section 4: Installing the App and Obtaining the API Token
The final step in the Shopify configuration involves installing your custom app and securely obtaining the Admin API access token.
### Step 4.1: Install the Custom App
1. Navigate back to the **"Overview"** screen of your newly created app within the Shopify Admin.
2. Click on the **"Install app"** button.
3. A confirmation pop-up window will appear. Review the permissions and click **"Install"** to proceed with the installation.
### Step 4.2: Reveal and Secure the Admin API Access Token
1. Once the app is successfully installed, you will be automatically directed to the **"API credentials"** tab.
2. On this tab, you will see an option to reveal your **Admin API access token**. Click **"Reveal token once."**
3. **Critical Security Note:** This token is revealed **only once**. It is a highly sensitive credential that grants extensive access to your Shopify store based on the configured scopes.
* **Immediately copy this token.**
* **Store it securely** in an environment variable, a secrets management service, or a secure configuration file. **Do not hardcode it directly into your application code.**
* If you lose this token, you will need to uninstall and reinstall the app to generate a new one.
***
## Section 5: Connecting to SigmaMind AI Platform
The final step is to configure your SigmaMind AI platform with the obtained Shopify Admin API access token.
1. Log in to your SigmaMind AI account.
2. Navigate to the section dedicated to App integrations - Shopify configurations.
3. Input the **Admin API access token** you obtained in Step 4.2 into the App Integration- Shopify Auth token field.
4. Follow any additional instructions provided by the SigmaMind AI platform for completing the Shopify integration.
Once the token is successfully configured within SigmaMind AI, your AI agents will be authenticated and able to access all the data and perform all the actions permitted by the API scopes you selected during the app setup.
***
## Benefits of this Integration
This robust integration unlocks significant capabilities for your AI agents, including:
* **Real-time Information Fetching:** AI agents can automatically retrieve up-to-the-minute information from your Shopify store, such as current order details, comprehensive customer information, detailed product data, and answers to frequently asked questions.
* **Automated Actions:** Empower your AI agents to perform a variety of automated actions on the Shopify store, either based on customer inquiries/tickets or predefined business rules. This includes:
* Canceling orders
* Applying discounts
* Processing order returns
* Issuing refunds
* Modifying order details
This seamless integration allows for significant automation of customer support and various store management tasks, streamlining operations through the SigmaMind AI platform.
# Billing Logs
Source: https://docs.sigmamind.ai/billing-logs
The Billing Logs page provides a breakdown of platform usage and associated billing details across different channels and agents.
## How to Navigate
1. Go to the Home Dashboard.
2. From the left side panel, click on **Logs**.
3. Open the **Billing** tab at the top of the page.
## Key Insights
* Track billing and usage data in real time.
* View:
* Conversation ID
* Source and channel
* Billing component
* Unit price
* Usage duration
* Total cost
* Analyze usage trends through billing and usage charts.
* Filter data by channel, agent, date range, and timezone.
## Filter & Export Options
* Use the filter option to search and analyze specific billing records.
* Apply filters based on:
* Conversation ID
* Source
* Channel
* Status
* Billing component
* Usage
* Cost
* Download billing data for reporting and record keeping.
* Refresh logs anytime to fetch the latest billing activity.
## Common Use Cases
* Monitor platform spending and usage.
* Analyze agent-level billing details.
* Track usage across chat, email, and phone channels.
* Review cost breakdown for different billing components.
## Status Indicators
* **Billed** → Usage has been successfully charged and recorded.
# Development
Source: https://docs.sigmamind.ai/development
Preview changes locally to update your docs
**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
Please upgrade to `docs.json` before proceeding and delete the legacy `mint.json` file.
Follow these steps to install and run Mintlify on your operating system:
**Step 1**: Install Mintlify:
```bash npm theme={null}
npm i -g mintlify
```
```bash yarn theme={null}
yarn global add mintlify
```
**Step 2**: Navigate to the docs directory (where the `docs.json` file is located) and execute the following command:
```bash theme={null}
mintlify dev
```
A local preview of your documentation will be available at `http://localhost:3000`.
### Custom Ports
By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command:
```bash theme={null}
mintlify dev --port 3333
```
If you attempt to run Mintlify on a port that's already in use, it will use the next available port:
```md theme={null}
Port 3000 is already in use. Trying 3001 instead.
```
## Mintlify Versions
Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI:
```bash npm theme={null}
npm i -g mintlify@latest
```
```bash yarn theme={null}
yarn global upgrade mintlify
```
## Validating Links
The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
```bash theme={null}
mintlify broken-links
```
## Deployment
Unlimited editors available under the [Pro
Plan](https://mintlify.com/pricing) and above.
If the deployment is successful, you should see the following:
## Code Formatting
We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
## Troubleshooting
This may be due to an outdated version of node. Try the following:
1. Remove the currently-installed version of mintlify: `npm remove -g mintlify`
2. Upgrade to Node v19 or higher.
3. Reinstall mintlify: `npm install -g mintlify`
Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
Curious about what changed in the CLI version? [Check out the CLI changelog.](https://www.npmjs.com/package/mintlify?activeTab=versions)
# Tool Action
Source: https://docs.sigmamind.ai/documentation/agents/add-advance-nodes/app-action-node
Tool Actions allow the agent to interact with external applications such as booking systems, CRMs, or databases.
Use Tool Actions when the agent needs to perform operations outside the conversation.
To configure:
1. Select **Tool Action** from the node panel or from the **Response node → Add Function**
2. Select the **App / Tool**
3. Select the **Action**
4. Add a **Description(optional)**
5. Configure the required fields
Example actions:
```text theme={null}
get_available_slots
book_appointment
update_crm
```
***
# Function Description (Optional)
Each function includes a **Description** field that explains when the agent should call the function.
Example:
```text theme={null}
Call this function after collecting the appointment date.
```
This helps the AI agent determine the correct moment to trigger the action.
# Extract Variables
Source: https://docs.sigmamind.ai/documentation/agents/add-advance-nodes/extract-variables
The **Extract Variables** node allows the agent to capture important information from a conversation and store it as variables that can be reused later in the workflow.
These variables can be used in responses, integrations, tool actions, or helpdesk operations.
Extracting structured data from user input is a common capability in AI workflow systems, where natural language is converted into reusable parameters for automation and integrations.
***
# When to Use
Use **Extract Variables** when the agent needs to capture information during an ongoing conversation.
Common examples include:
* Customer name
* Phone number
* Email address
* Appointment date
* Order ID
* Service request
These values can later be used in other nodes such as **Tool Action**, **Helpdesk Action**, or **Response** nodes.
***
# How to Add the Node
In Conversational Flow, you can add **Extract Variables** in two ways:
**Option 1 — From the Node Panel**
1. Select **Extract Variables** from the left node panel
2. The node appears on the workflow canvas
3. Configure the variables to extract
**Option 2 — From a Response Node**
1. Open the **Response** node
2. Select **Add Function**
3. Select **Extract Variables**
4. Configure the variables
Both methods perform the same function.
***
# Defining Variables
Variables must always be written using **double curly braces**.
Example format:
```text theme={null}
{{variable_name}}
```
Example variables:
```text theme={null}
{{customer_name}}
{{phone_number}}
{{appointment_date}}
{{order_id}}
```
During the conversation, the AI agent automatically detects and extracts these values from the user's message.
***
# Example Workflow
Example scenario:
User message:
```text theme={null}
Hi, my name is Rahul Sharma and I want to book an appointment tomorrow.
```
Extracted variables:
```text theme={null}
{{customer_name}} → Rahul Sharma
{{appointment_date}} → Tomorrow
```
These values can now be used in later workflow steps.
***
# Using Extracted Variables
Once extracted, variables can be used in different nodes across the workflow.
Example usage in a response:
```text theme={null}
Thanks {{customer_name}}. Your appointment is scheduled for {{appointment_date}}.
```
Example usage in a tool action:
```text theme={null}
book_appointment
customer_name: {{customer_name}}
date: {{appointment_date}}
```
***
# Best Practices
* Use clear variable names such as `customer_name` or `appointment_date`
* Extract only the information required for the workflow
* Reuse variables across multiple nodes to avoid asking the same question again
* Keep variable names consistent across the agent
# Helpdesk Action
Source: https://docs.sigmamind.ai/documentation/agents/add-advance-nodes/helpdesk-action-node
The **Helpdesk Action** node allows the AI agent to interact with integrated helpdesk systems.
This node can automatically update or manage support tickets during a conversation.
Supported integrations may include platforms such as **Zendesk** or **Gorgias**.
***
## **When to Use**
Use **Helpdesk Action** when the agent needs to:
* Add tags to support tickets
* Update ticket status
* Assign tickets to support teams
* Snooze or delay tickets
* Add internal notes
***
## **How to Configure**
1. Select **Helpdesk Action** from the node panel.
2. Select the action you want the agent to perform.
3. Connect the node to the next step in the workflow.
When the workflow reaches this node, the selected helpdesk operation is executed automatically.
***
## **Example**
Example actions include:
ticket\_add\_tag
ticket\_assign
ticket\_snooze
ticket\_update\_status
These actions help automate customer support workflows.
# How to use SIP Custom Header
Source: https://docs.sigmamind.ai/documentation/agents/add-advance-nodes/howto-use-sip-custom-header
## Custom SIP Headers for Outbound Calls
Custom SIP headers let you attach structured metadata to outbound calls. These headers are sent along with the SIP request and can be used by backend systems, CRMs, or receiving endpoints.
**Key Rules:**
```text theme={null}
Header names must start with X-
Format is key-value pairs
Headers are not visible to the end customer
They are accessible to systems handling the call (e.g., PBX, CRM, agents)
```
***
## Custom SIP Headers for Call Transfers
Custom headers can be included during call transfers.
### Additional capability:
* You can use **dynamic variables** in header values
* This allows passing **real-time data extracted during the call** to the next system or agent
***
## What Custom Headers Do
Custom headers allow you to:
* Send structured metadata along with a call
* Share context between systems
* Improve agent awareness and automation
They are:
* ✅ Hidden from customers
* ✅ Available to backend systems and integrations
* ✅ Useful for routing, tracking, and personalization
***
**Headers are defined as simple key-value pairs:**
```text theme={null}
X-Intent: billing_issue
X-Language: hi
X-Customer-Type: existing
X-Ticket-ID: 12345
X-Call-Source: campaign
```
***
## Mapping Headers to Dynamic Variables
These headers can be mapped and used inside your system or agent workflows:
```text theme={null}
{{ intent }} → billing_issue
{{ language }} → hi
{{ customer_type }} → existing
{{ ticket_id }} → 12345
{{ call_source }} → campaign
```
## When to Use Custom Headers
Use custom SIP headers when you need to:
* Pass metadata between systems
* Integrate with CRM or call center tools
* Track call intent, source, or customer type
* Enable smarter routing or automation
* Send structured (non-conversational) data alongside calls
## Custom SIP Headers for Inbound Calls
For inbound calls, custom SIP headers (headers that start with `X-` or `x-`) can be passed from your telephony system (e.g., VICIdial) and automatically converted into dynamic variables at runtime in SigmaMind AI.
These headers are accessible inside your agent without additional configuration.
## How It Works
When an inbound SIP call is received:
1. SigmaMind reads incoming SIP headers
2. Headers with the prefix `X-` or `x-` are extracted
3. The prefix is removed
4. You can access it within your agent by stripping the `X-` or `x-` prefix from the header name, which is then converted into a dynamic variable.
## Example
### Incoming SIP Headers
```text theme={null}
{
"X-customer_name": "John Doe",
"X-account_id": "12345",
"from": "9876543210",
"to": "1800123456"
}
```
### Runtime Dynamic Variables
These will be available through your agent:
```text theme={null}
{
"customer_name": "John Doe",
"account_id": "12345"
}
```
***
## Usage in Agent
You can directly reference these variables in your flows, prompts, or scripts:
* `{{customer_name}}`
* `{{account_id}}`
Example:
```text theme={null}
Hello {{customer_name}}, I see your account ID is {{account_id}}. How can I assist you today?
```
Only headers starting with `X-` or `x-` are processed\
Header names are normalized by removing the prefix\
Keys are treated as case-insensitive
# Jump Node
Source: https://docs.sigmamind.ai/documentation/agents/add-advance-nodes/jump-node
This document provides a detailed explanation of **Jump Nodes** within the context of conversational AI agents, including their purpose, typical use cases, and configuration.
***
## What is a Jump Node?
A **Jump Node** is a crucial component in conversational AI agent design that enables the handling of non-linear conversational flows. Unlike traditional linear conversational paths, a Jump Node allows the agent to deviate from its predefined sequence of interactions and redirect the conversation based on specific conditions or user intents.
***
## Purpose and Utility
The primary purpose of a Jump Node is to manage unpredictable conversational scenarios where a user's request might necessitate an immediate change in the conversation's direction.
### Key Use Cases:
* **Human Handoff:** A common and highly practical application of a Jump Node is to facilitate the transfer of a conversation (whether chat or voice call) from an AI agent to a human representative. This is particularly useful when a customer explicitly requests to speak to a human at any point during their interaction with the AI.
* **Example Scenario:** A customer is navigating an automated support system, but at an unexpected moment, they type "I want to speak to a person" or "Connect me with an agent." A Jump Node, configured to detect this intent, can immediately intercept the conversation and initiate the transfer process.
* **Emergency Exits/Global Intents:** Jump Nodes can be used to handle "global" intents that should be recognized and acted upon regardless of the current conversational state. This ensures that critical user requests are never missed.
* **Dynamic Topic Changes:** Jump Nodes can also be adapted to allow users to abruptly change topics. If a user expresses an intent to discuss something entirely different, a Jump Node can redirect them to the relevant part of the conversation flow.
***
## Configuration
Configuring a Jump Node involves defining the conditions under which the node should be activated and specifying the subsequent action.
### Steps for Configuration:
1. **Define Conditions:** Within the Jump Node, you specify the conditions that, when met, will trigger the jump. These conditions are typically based on the user's intent, keywords, or phrases.
* **Example Condition:** "If the customer is asking to speak with a human." This condition would be linked to an intent model trained to recognize variations of "speak to an agent," "human help," etc.
2. **Specify Redirection:** After the Jump Node's conditions are met, you define where the conversational flow should be redirected. This often involves linking to another node in the conversation flow.
* **Example Redirection:** After the jump intent is triggered, the flow can be directed to a "Send Response" node.
3. **Craft Response (Optional but Recommended):** It's good practice to provide a clear and helpful response to the user after a Jump Node is activated, informing them of the action being taken.
* **Example Response:** "Sure, let me transfer the call to my colleague."
***
## Evaluation Mechanism
Jump Nodes are designed for continuous evaluation. This means that at every turn of the conversation, whenever the user provides input, the system actively checks if any of the configured Jump Node conditions are met. This constant monitoring ensures that the conversational flow can be dynamically redirected at any moment if a specific, pre-defined condition is detected, providing a highly responsive and user-centric experience.
# Overview
Source: https://docs.sigmamind.ai/documentation/agents/add-advance-nodes/overview
Conversational Flow in SigmaMind AI is built using **nodes**. Each node represents a step in the agent’s workflow and defines how the agent should behave during a conversation.
By connecting nodes together, developers can design structured workflows that control how the AI agent responds, analyzes messages, performs actions, and interacts with external systems.
When a new agent is created, the **Start Trigger** node is automatically added to the canvas. This node acts as the entry point of the workflow. From there, additional nodes can be added and connected to define the full conversation logic.
Each node performs a specific function within the agent workflow.
***
## Available Nodes
SigmaMind currently supports the following nodes in **Conversational Flow**:
**Start Trigger**\
Defines when the agent workflow begins.
**Send Response**\
Sends a message or AI-generated response to the user.
**Analyze Customer Message**\
Analyzes the customer’s message to detect intent or understand the request.
**Wait**\
Pauses the workflow for a defined period or until the next customer message is received.
**Branch**\
Routes the conversation to different paths based on defined conditions.
**Jump**\
Redirects the workflow to another node within the flow.
**Tool Action**\
Allows the agent to interact with external applications and APIs.
**Helpdesk Action**\
Performs actions within connected helpdesk systems such as updating tickets or adding tags.
***
## Function Calls Inside Nodes
Some nodes, such as **Send Response**, allow you to configure **Function Calls** directly inside the node. These function calls enable the agent to perform real-world actions during a conversation.
Supported function call types include:
**Voice Action**\
Control call behavior such as transferring a call or ending a call.
**Extract Variables**\
Capture structured data from the conversation for later use in workflows or integrations.
**Tool Action**\
Allow the agent to interact with external systems such as CRMs, databases, or scheduling platforms.
Refer to the individual node documentation to learn how to configure and use them within your agent workflows.
# Voice Action
Source: https://docs.sigmamind.ai/documentation/agents/add-advance-nodes/voice-action
Voice Actions allow the agent to control the behavior of a phone call, such as transferring the call to a human agent or ending the call automatically.
In **Conversational Flow**, Voice Actions can be added in two ways:
1. **Select Voice Action from the left node panel** and add it to the workflow canvas
2. **Add the function inside a Response node** using **Add Function**
Available actions:
```text theme={null}
IVR_NAVIGATOR
VOICE_TRANSFER_CALL
VOICE_END_CALL
```
***
# IVR Navigator
Enable your AI agent to navigate IVR systems and make outbound calls like a human caller.
The agent sends keypad inputs (DTMF) when required, responds naturally when prompted for speech, and seamlessly continues the interaction if a human agent joins.
***
## How It Works
When an outbound call is placed, the receiving system may respond with:
* A traditional IVR menu
* A conversational AI system
* A live human agent
* Or a combination of all three
IVR Navigator enables the agent to handle these transitions within a single call.
The core decision the agent must make is:
### **Press vs. Say**
* If the IVR says, **"Press 1 for English."**\
→ The agent sends a keypad digit using IVR Navigator
* If the IVR says **"Say 1" or asks a question**\
→ The agent responds using normal speech
This distinction is critical for correct navigation.
***
## Supported IVR Types
**Press-type**\
"Press 1 for X, Press 2 for Y"\
→ IVR Navigator is triggered
**Say-type**\
"Say 1 for English" or open-ended prompts\
→ Handled via normal speech (no tool call)
**Conversational AI**\
Acts like a human and asks questions\
→ IVR Navigator is used only if numeric input is explicitly required
**Mixed (IVR + Human)**\
IVR transitions to a human and may return to keypad input\
→ IVR Navigator is triggered only for digit-based steps
***
## How to Configure
**Step 1:** In Agent Builder, select the **Voice Action** and add `ivr_navigator`**as** an action.
**Step 2:** Add a **Description** to define when the agent should trigger `ivr_navigator`.
**Recommended:**\
Always call this tool only when the IVR explicitly asks for numeric input (e.g., “press” or “enter” a digit/number).\
Do NOT call this method for spoken responses or unclear prompts.
**Step 3:** Set **IVR starts conversation? (Yes / No)**\
Specify whether the IVR system begins speaking at the start of the call.
* **Yes** → Use this when the call starts with an IVR greeting or menu.\
The agent will wait for the configured **Pause Delay** before processing, ensuring the full message is received.
* **No** → Use this when no initial IVR delay handling is needed.\
The agent will begin processing immediately.
**Step 4:** Set **pause\_delay** \
Defines how long (in milliseconds) the agent waits after IVR speech before taking action.
IVR systems often deliver menu options in fragments with short pauses. Without a delay, the agent may act too early.
**Recommended: 2000 ms**
***
### Step 4: Write your agent system prompt
All navigation logic, goals, and behavioral constraints should be defined in the agent’s system prompt.
## Agent Prompt Guide
### Define the goal
Clearly specify what the agent must achieve.
**Example:**\
Navigate the IVR system, retrieve required information, complete necessary inputs, and connect to a human agent if needed.
***
### Provide a navigation path (recommended)
If the IVR structure is known, include the expected flow. This significantly improves reliability.
**Example:**
* Select language
* Select account type
* Select service category
* Proceed to the target function
***
### Pass caller data as dynamic variables
Provide structured data the agent may need during the call:
* Mobile number
* Reference or account number
* Policy or claim ID
* Verification details (e.g., last 4 digits of SSN)
***
### Set the agent persona
Without a defined persona, the agent may behave incorrectly (e.g., like a support agent).
**Recommended instruction:**
The agent should behave as a caller seeking assistance.\
It should not act as a support representative or provide solutions, explanations, or guidance.
***
## Behavioral Guidelines
To ensure reliable IVR navigation:
* Only act when input is explicitly requested
* Do not respond to informational (e.g., hold music, “please wait”)
* Do not guess or assume menu options
* Do not press fallback keys (e.g., 0 or 9) unless explicitly instructed
* Separate **digit input actions** from **spoken responses**
***
## Notes
* Digit inputs are **irreversible** once sent
* Incorrect timing can lead to failed navigation
* IVR systems may change over time—regular testing is recommended
**Example prompt:**
```text theme={null}
## IVR Interaction Rules
### 1. Informational / Transitional Prompts
If the prompt is informational (e.g., hold music, “please stay on the line”, “processing”, ringing):
- Return: `NA`
- Do not press any digits
- Do not speak
- Do not trigger IVR navigation
### 2. Input Mode Decision (Highest Priority)
Speech Input
- If the IVR says “say”, “speak”, “tell me”, or asks a question:
- Respond naturally as a caller
- Do NOT trigger IVR navigation
DTMF Input (Keypad)
- If the IVR says “press”, “enter”, or asks for numbers:
- Trigger IVR navigation with the required digits only
- Do NOT generate a spoken response
## Caller Role
- Act as a normal caller (not a support agent)
- Do not provide explanations, solutions, or guidance
## Goal
- Navigate AutoProtect IVR
- Retrieve claim status
- Provide required inputs correctly
- Connect to a human agent
## Input Data
- Claim Reference Number: `123456`
- ZIP Code: `560001`
- Last 4 Digits of SSN: `1234`
## Preferred Navigation Path
`English → Existing Policyholder → Claims → Existing Claim Status → Enter Details → Get Status → Representative`
## Navigation Constraints
- Only press digits explicitly mentioned
- Do not press `9` (repeat/back) unless instructed
- Do not press unrelated digits
- Do not change menu path
## After Transfer to Agent
- Briefly state you are checking claim status
- Answer questions concisely
- Do not provide extra details unless asked
```
## VOICE\_TRANSFER\_CALL
This action transfers an active call to another agent, team, or phone number.
This feature works only for **phone calls** and is **not supported for web calls**.
***
## When to Use
Use this action when:
* The user asks to speak with a human agent
* The request requires human assistance
* The conversation needs escalation
* The workflow needs to route the call to another department
***
## How to Configure
### Step 1: Select Action
Select the action from the dropdown:
```text theme={null}
voice_transfer_call
```
This enables the transfer configuration settings.
***
### Step 2: Transfer To
Define the phone number or variable where the call should be transferred.
Static example:
```text theme={null}
+919876543210
```
Dynamic example:
```text theme={null}
{{assigned_agent_number}}
```
The phone number must be in **E.164 international format** including the country code.
***
### Step 3: Transfer Types
SigmaMind supports two transfer types:
* **Cold Transfer**
* **Warm Transfer**
***
## Cold Transfer
Cold transfer immediately connects the caller to the destination number.
Behavior:
* AI transfers the call and exits the conversation
* No context is shared with the receiving agent
* Caller hears ringing and connects directly
Use when:
* Context is not required
* Simple routing is needed
* Fast escalation is required
***
## Warm Transfer
Warm transfer connects the receiving agent first, shares context, and then bridges the caller.
This ensures a smoother handoff experience.
Warm transfer includes two stages:
* **Connecting Stage**
* **Bridged Stage**
***
### Stage 1: Connecting Stage
The receiving agent is connected while the caller remains on hold.
#### Whisper Message
A **Whisper Message** is played only to the receiving agent.
The caller cannot hear this message.
You can configure this as:
* **Static message**
* **Prompt-generated message**
Example:
```text theme={null}
You are being connected to {{customer_name}} regarding policy {{policy_id}}.
```
***
### Stage 2: Bridged Stage
In this stage, both the caller and the human agent are connected.
You can optionally enable a **Three-way Message** that is played to both participants.
Example:
```text theme={null}
Thank you for waiting {{customer_name}}. You are now connected to our support specialist.
```
***
### Custom Headers (Optional)
Custom headers allow structured metadata to be sent during the transfer.
Example:
```text theme={null}
X-Intent: billing_issue
X-Language: hi
X-Customer-Type: existing
X-Ticket-ID: 12345
```
These headers can be accessed by backend systems, CRM tools, or call center software.
***
## Execution Flow
```text theme={null}
Customer requests transfer
→ Specialist connected
→ Whisper message played
→ Caller connected
→ Three-way message played
→ Specialist continues conversation
```
***
## VOICE\_END\_CALL
The **VOICE\_END\_CALL** action allows the AI agent to end the call automatically when the conversation is complete.
***
## When to Use
Use this action when:
* The conversation is complete
* The user's request has been resolved
* The user says goodbye
* The user asks to end the call
Example instruction:
```text theme={null}
Call "voice_end_call" when the user confirms the conversation is complete.
```
# Branch Node
Source: https://docs.sigmamind.ai/documentation/agents/add-basic-nodes/branch-node
The **Branch Node** in the SigmaMind AI platform is a fundamental component for constructing advanced and dynamic conversational AI agents. It enables the AI to make decisions and follow specific conversational paths based on various conditions, allowing for complex business logic implementation.
## 1. Purpose of the Branch Node
The primary purpose of the Branch Node is to introduce conditional logic into the conversational flow of an AI agent. This is crucial for building sophisticated agents that can respond intelligently to diverse user inputs and external data. It allows the AI to:
* Handle multiple conditions, both static and dynamic.
* Execute specific instructions based on the evaluation of these conditions.
* Implement complex business rules within the conversational experience.
## 2. Key Use Cases
The versatility of the Branch Node makes it suitable for a wide range of applications across various industries:
* **Customer Support:** Tailoring responses and escalating issues based on the nature of customer queries, customer history, or service level agreements.
* **Sales & Lead Qualification:** Guiding users through sales funnels, providing product recommendations, or qualifying leads based on user responses and profile data.
* **Channel-Specific Logic:** Adapting the AI's behavior and responses depending on the communication channel (e.g., email, live chat, voice, social media). For example, providing shorter, more direct answers on mobile chat versus more detailed explanations via email.
* **Time-Based Logic:** Adjusting conversational flow based on the time of day, day of the week, or specific dates (e.g., business hours vs. after-hours, weekdays vs. weekends, holiday promotions).
* **Order Status Management:** Providing specific updates or actions based on the status of an order (e.g., fulfilled, pending, shipped, cancelled).
* **Appointment Management:** Handling scenarios such as checking appointment availability, scheduling new appointments, rescheduling existing ones, or cancellations.
* **User Personalization:** Delivering personalized content or experiences based on user preferences, past interactions, or demographic data.
## 3. Types of Conditions
The Branch Node supports two primary mechanisms for defining conditions:
### 3.1. Static Conditions
Static conditions are pre-defined, readily available options within the SigmaMind AI platform, ideal for handling simple "if-else" logic.
* **Ease of Use:** Developers can simply select these conditions from a dropdown menu within the Branch Node configuration interface.
* **Multiple Conditions:** On the "if" side of the branch, it's possible to define multiple static conditions. These conditions can be evaluated in two ways:
* **All True (AND logic):** All defined conditions must be met for the branch to be taken.
* **Any True (OR logic):** At least one of the defined conditions must be met for the branch to be taken.
* **Performance:** Static conditions are optimized for rapid evaluation at runtime, ensuring minimal latency in the AI agent's responses.
* **Examples:**
* Checking if the conversation originated from a specific channel (e.g., "Is channel 'Email'?", "Is channel 'Chat'?").
* Verifying if it's currently a weekend.
* Determining if it's within business hours.
### 3.2. Expressions (JavaScript-based)
For scenarios requiring more intricate, custom, or dynamic logic that cannot be covered by static conditions, developers can leverage JavaScript-based expressions. These are designed for **more complex conditions**.
* **Flexibility:** This provides a high degree of control and allows developers to implement virtually any custom logic.
* **Syntax:** Expressions are written using standard JavaScript syntax.
* **Data Access:** Expressions can access and evaluate various data points, including:
* Session variables.
* User input.
* Data retrieved from external APIs.
* Contextual information about the conversation.
* **Example:** To check if a `shopify_order_id` exists and is valid (e.g., has a certain length), you might write an expression like:
```javascript theme={null}
session.shopify_order_id && typeof session.shopify_order_id === 'string' && session.shopify_order_id.length > 5
```
This expression evaluates to `true` if `shopify_order_id` exists in the session, is a string, and its length is greater than 5 characters.
## 4. Benefits of Using the Branch Node
Implementing the Branch Node in your AI agent development offers several significant advantages:
* **Enhanced Flexibility:** Allows for the definition of highly intricate and adaptive business logic, making AI agents more intelligent and capable.
* **Improved Efficiency:** Static conditions are evaluated quickly, contributing to a responsive and seamless user experience.
* **Reduced Coding Effort (for static conditions):** For common conditional scenarios, the no-code selection of static conditions simplifies and accelerates development.
* **Scalability:** Enables the creation of complex conversational flows that can scale with the growing needs of your application.
* **Better User Experience:** By guiding users through relevant paths and providing context-aware responses, the Branch Node helps create more intuitive and satisfying interactions.
# Analyze Customer Message
Source: https://docs.sigmamind.ai/documentation/agents/add-basic-nodes/customer-intent-node
The **Analyze Customer Message Node** allows the AI agent to evaluate the customer’s message and determine what the user is asking for. Based on the detected intent or message content, the agent can route the conversation to different paths in the workflow.
This node is commonly used when the conversation needs to **branch into multiple outcomes depending on what the customer says**.
For example, a customer may want to cancel an order, request support, or ask for more information. The Analyze Customer Message Node helps the agent understand the request and move the conversation to the correct response or action.
***
# How It Works
When the **Analyze Customer Message Node** runs, the agent analyzes the customer's message and checks whether it matches any configured conditions.
If a condition matches, the conversation follows the corresponding path connected to that condition. If none of the conditions match, the flow continues through the **Else** path.
This allows developers to design flexible workflows that respond dynamically to customer messages.
***
# Wait for New Message
The **Wait for new message** toggle determines whether the agent should wait for the customer's next response before analyzing the message.
**Enabled**
The agent pauses and waits for the user to send a message. Once the message is received, the node analyzes it and routes the conversation accordingly.
**Disabled**
The node immediately analyzes the latest available customer message in the conversation.
This option is commonly used when the agent has just asked a question and needs to evaluate the customer's reply.
***
# Defining Message Conditions
Inside the **If the customer message is** field, you can define conditions that represent the possible intents or message types you want the agent to detect.
Each condition represents a possible interpretation of the customer's response.
Example conditions:
Customer wants to cancel the order\
Customer accepts the offered discount\
Customer declines the discount\
Customer requests to speak with a human agent
The agent will compare the customer's message against these conditions and follow the corresponding branch when a match is detected.
***
# Adding Multiple Conditions
You can configure multiple message conditions by clicking **Add Condition**.
Each condition creates a separate branch in the conversation flow.
Example workflow:
Condition 1\
Customer wants to cancel the order
Condition 2\
Customer accepts the discount offer
Condition 3\
Customer declines the discount and still wants cancellation
Each condition can connect to a different **Send Response node, Tool Action, or another workflow node**.
***
# Else Path
The **Else** path is used when the customer's message does not match any of the configured conditions.
This ensures the conversation continues smoothly even when the agent cannot clearly detect the expected intent.
Common uses for the Else path include:
Asking the user to clarify their request\
Repeating the previous question\
Providing additional guidance
Example response:
"Sorry, I didn’t quite understand that. Could you please confirm if you would like to cancel the order or continue with it?"
***
# Example Use Case
A customer wants to cancel their order.
1. The agent asks why the customer wants to cancel.
2. The **Analyze Customer Message Node** evaluates the customer's reply.
Possible outcomes:
If the customer insists on cancellation\
→ Proceed with the order cancellation flow.
If the customer is unsure\
→ Offer a retention discount.
If the customer accepts the discount\
→ Confirm the discount and keep the order active.
If the customer declines the discount\
→ Continue with cancellation.
This allows the agent to handle customer conversations more intelligently instead of following a rigid script.
***
# Best Practices
Define clear and distinct conditions so the AI can accurately interpret customer responses.
Use simple and direct descriptions when defining message conditions.
Always configure an **Else path** to handle unexpected responses.
Test different customer responses in the **Playground** to ensure the correct paths are triggered.
# Send Response Node
Source: https://docs.sigmamind.ai/documentation/agents/add-basic-nodes/response-node
The **Send Response** node allows the AI agent to send messages to the user during a conversation. It is the primary way an agent communicates information, asks questions, confirms actions, or provides updates.
This node can generate either **static responses** or **AI-generated responses using prompts**, depending on how the node is configured.
The **Send Response** node works across all supported channels, including voice calls, chat, and email. SigmaMind automatically delivers the response through the same channel where the conversation started.
***
# Purpose
The Send Response node is used to:
* Send messages to customers during the conversation
* Ask questions and collect information
* Confirm actions or requests
* Provide updates or instructions
* Guide the conversation to the next step in the workflow
It acts as the **main communication layer** between the AI agent and the user.
***
# Response Types
The Send Response node supports two response types.
## Static Response
A **Static Response** sends a predefined message exactly as written.
No AI model is used to generate or modify the message. The response is delivered exactly as configured.
### When to Use Static Response
Use static responses when:
* The message must always remain the same
* You want consistent and predictable responses
* The message contains fixed instructions or confirmations
* No AI generation is required
### Example
Thank you for contacting support.\
How can I assist you today?
If used in a **voice call**, the message will be spoken by the AI.\
If used in **chat or email**, the message will be sent as text.
***
## Prompt Response
A **Prompt Response** uses a Large Language Model (LLM) to generate a response based on the instructions provided in the prompt.
Instead of sending a fixed message, the AI interprets the instructions and produces a **natural, conversational reply**.
This allows responses to adapt dynamically based on the conversation context.
### When to Use Prompt Response
Use prompt responses when:
* The message should sound more natural or conversational
* You want dynamic responses based on context
* The response should include variables or collected information
* The tone or wording may vary slightly
***
# Writing Effective Prompts
When using Prompt Response, write clear instructions that guide the AI on how to generate the message.
A good prompt should define:
* The purpose of the message
* The tone and communication style
* The information that should be included
* Any variables that should appear in the response
***
# Example Prompt
You are a friendly and professional customer support assistant for SigmaMind AI.
```text theme={null}
Your task is to confirm the customer's appointment details clearly and politely.
Instructions:
Thank the customer for scheduling the appointment.
Confirm the appointment date using {{appointment_date}}.
Confirm the appointment time using {{appointment_time}}.
Address the customer by their name using {{customer_name}}.
Ask if the customer needs any additional help.
Tone Guidelines:
Be polite and professional
Keep the message short and clear
Sound friendly and helpful
Example Generated Response:
Thank you {{customer_name}} for scheduling your appointment.
Your appointment is confirmed for {{appointment_date}} at {{appointment_time}}.
If you need to make any changes or require further assistance, please let me know.
```
***
# Using Variables in Responses
Variables allow the agent to personalize responses using information collected earlier in the conversation.
Variables must be written using double curly braces.
Examples:
```
{{ customer_name }}
{{ appointment_date }}
{{ appointment_time }}
{{ order_id }}
```
When the agent collects this information during the conversation, SigmaMind automatically replaces the variable with the actual value.
Example output:
Thank you Rahul. Your appointment is confirmed for March 15 at 3 PM.
***
# Auto Response vs Draft
The Send Response node allows you to control how the response is delivered.
## Auto Response
When **Auto Response** is selected, the AI response is sent immediately to the user.
This is the default behavior for most automated workflows.
## Draft
When **Draft** is selected, the response is prepared but **not sent automatically**.
This option is useful when:
* Human agents need to review the response first
* The system is integrated with a helpdesk
* Manual approval is required before sending the message
***
# Select Macro
Macros allow you to use **predefined message templates** from your system or helpdesk integration.
Instead of writing the message manually, you can select an existing macro and send it as a response.
Macros can also be used as input for **Prompt Response**, allowing the AI to adapt the template based on conversation context.
***
# Advanced Settings
## Switch Channel
The **Switch Channel** option allows the agent to send a response through a different communication channel.
Example:
* A voice call is in progress
* The AI sends an SMS with a booking confirmation link
This enables **multi-channel communication within the same conversation flow**.
***
## Include Brand Persona
When **Include Brand Persona** is enabled, SigmaMind applies your configured brand tone and communication style when generating AI responses.
This ensures all AI responses follow your organization's brand voice, such as:
* Professional
* Friendly
* Empathetic
* Sales-oriented
The LLM combines your prompt instructions with the brand persona settings to generate consistent responses.
***
# Function Calls from Send Response Node
The Send Response node can also trigger **function calls or actions** during a conversation.
This allows the agent to perform real actions such as:
* Transferring a call
* Ending a call
* Extracting variables
* Interacting with external applications
Function calls can be added directly within the Send Response node configuration.
For detailed configuration instructions, refer to the following documentation pages:
* Voice Action
* Extract Variables
* Tool Action
***
# Best Practices
Follow these best practices when using the Send Response node:
* Keep responses clear and concise
* Use prompt responses for natural conversational replies
* Use static responses for fixed messages or confirmations
* Use variables to personalize responses
* Avoid including internal system instructions in prompts
* Ensure prompts clearly define tone and purpose
* Use function calls only when the conversation requires an action
***
# Summary
The **Send Response** node enables the AI agent to communicate with users across all supported channels.
It supports:
* Static responses for fixed messaging
* Prompt responses for AI-generated replies
* Dynamic variables for personalization
* Multi-channel communication
* Integration with macros and brand persona
* Triggering function calls and actions
This node is a core component of conversational flows and is used to guide and manage interactions between the AI agent and the user.
# Start Trigger
Source: https://docs.sigmamind.ai/documentation/agents/add-basic-nodes/trigger-node
The **Start Trigger** defines when an AI agent workflow begins. It acts as the **entry point of every conversational flow**, determining the event that activates the agent.
When a new agent is created using **Conversational Flow**, the **Start Trigger node is automatically generated on the canvas**. This node cannot be removed and always serves as the starting point of the workflow.
All other nodes in the agent flow are connected after the Start Trigger.
***
## Trigger Event
The **Trigger Event** specifies the event that activates the AI agent.
Currently, **SigmaMind supports only one trigger event:**
**Conversation Started**
This event activates the agent whenever a new conversation begins across supported communication channels.
Since this is the only supported trigger at the moment, it is **automatically configured and cannot be changed or deleted**.
***
## Common Use Cases
Using **Conversation Started** allows the AI agent to respond immediately when a user interaction begins.
Examples include:
* A customer starting a conversation through **Helpdesk Chat**
* A support request received through **Helpdesk Email**
* A conversation initiated through **Slack or WhatsApp**
* An **inbound phone call** from a customer
* An **outbound call** initiated by the system (for example, a scheduled callback)
This unified trigger allows developers to build AI agents that work consistently across different communication channels.
***
## Trigger Configuration Options
Although the trigger event itself cannot be changed, developers can configure additional settings within the **Start Trigger node** to control how the workflow begins.
### Add Multiple Trigger Conditions
You can define **additional trigger conditions** using **OR logic**.
This means the agent workflow will start if **any one of the configured conditions is satisfied**.
This flexibility allows a single agent to handle multiple entry scenarios without requiring separate workflows.
***
## Filter by Intent (Inbound AI Agents)
The **Filter by Intent** option allows developers to restrict agent execution to specific types of customer requests.
### How It Works
When enabled, the AI agent will activate only if the customer’s initial message matches one of the **preconfigured intents** available in **AI Studio**.
SigmaMind AI includes **over 200 predefined intents**, trained on millions of real customer queries to accurately detect user intent.
The agent is triggered only when SigmaMind AI has **more than 95% confidence** in the detected intent.
If the confidence score is lower than this threshold, the agent will **not be triggered**, helping prevent incorrect intent classification and improving reliability.
***
## Benefits of Intent Filtering
Intent filtering enables developers to create more targeted and specialized AI workflows.
### Intent-Based Routing
Different agents can handle different customer needs depending on the detected intent.
Examples include:
* Billing inquiries routed to a billing support workflow
* Shipping questions routed to an order tracking workflow
### Workflow Automation
Intent filtering also enables advanced automation such as:
* Offering **discounts before cancellation**
* Confirming **shipping status before processing returns**
* Separating **FAQ responses from transactional support**
***
> ## `Important Note`
>
> `Intent filtering is most useful for inbound text-based conversations, such as chat or email, where the customer’s first message can be analyzed before the agent responds.`
>
> `For voice calls, the AI agent usually speaks first before the customer provides input. In these cases, intent filtering in the Start Trigger may not be necessary.`
>
> `Instead, developers can use the Analyze Customer Message node later in the flow to detect the customer's intent and route the conversation accordingly.`
***
# Wait Node
Source: https://docs.sigmamind.ai/documentation/agents/add-basic-nodes/wait-node
This documentation outlines the functionality and usage of the **Wait Node** in a conversational AI platform, crucial for building asynchronous conversational flows.
## 1. Purpose of the Wait Node
The Wait Node is a fundamental component designed to introduce a pause in a conversational AI flow. This pause allows the system to evaluate specific conditions before processing the next customer response or sending a subsequent reply. It is essential for managing asynchronous interactions and ensuring the AI responds appropriately to various scenarios.
The Wait Node can be configured to wait for two primary types of conditions:
* **An Event:** The system can pause until a specific event occurs, such as "conversation customer message received."
* **A Delay:** The system can pause for a predetermined duration (e.g., 10 minutes, one day).
## 2. Practical Use Cases
The versatility of the Wait Node makes it suitable for both real-time interactions (chat, voice) and asynchronous communication channels like email.
### 2.1. Email Example
Consider a scenario where a customer initiates a subscription cancellation via email:
1. The customer sends an email to cancel their subscription.
2. The AI responds, potentially offering a discount to retain the customer or confirming the cancellation.
3. A Wait Node is then activated, configured to wait for two days.
4. If no further response is received from the customer within these two days, the system automatically proceeds with the subscription cancellation.
### 2.2. Real-time Conversation (Chat/Phone) Example
In real-time conversational contexts, the Wait Node provides mechanisms for handling customer unresponsiveness and post-conversation actions:
* **Customer Unresponsiveness:** If a customer becomes unresponsive during a chat or phone conversation, the Wait Node can be employed to:
* Automatically end the conversation after a specified delay.
* Send a summary of the chat to the customer.
* Trigger other predefined actions after a certain period of inactivity.
* **Post-Conversation Follow-up:** After a call concludes, a Wait Node can be set to trigger a follow-up message after a day. This message could prompt the customer to rate the conversation or provide a conversation summary.
## 3. Configuration and Flexibility
The Wait Node offers robust configuration options to create sophisticated conversational flows:
* **Multiple Conditions:** Developers can add multiple conditions to a single Wait Node. These conditions are evaluated using an "OR" logic. For instance, a Wait Node can be set to "wait for either a new message from the customer OR two days" before proceeding.
* **Robust Scenarios:** This flexibility enables the creation of highly robust and production-ready conversational AI responses that can effectively handle a wide array of user interactions and edge cases.
## 4. Important Considerations
While powerful, the Wait Node is not universally required in all conversational AI agents:
* **Implicit Wait in Real-time Agents:** For real-time agents (chat and voice), a pre-designed, implicit wait for a new message is inherently built into the "Customer Intent" node. This means the system automatically pauses and waits for a new message from the customer without the need for an explicit Wait Node.
* **When the Wait Node is Necessary:** In real-time conversations, the Wait Node is only necessary in specific situations:
* When a defined delay is required before an action is taken.
* When an action needs to be triggered by an event other than a new message from the customer (e.g., a timer expiring, an external system update).
The Wait Node excels in handling "edge case" scenarios where the system needs to pause and wait for specific conditions beyond just a new customer message to trigger the next action in the conversational flow.
# Conversational Flow Agent
Source: https://docs.sigmamind.ai/documentation/agents/agent-builder-overview
Learn how to build custom conversational AI agents using SigmaMind's AI agent builder.
SigmaMind AI enables developers to build intelligent conversational agents using a visual, node-based workflow builder.
Each agent is designed by connecting modular components (nodes) that define how a conversation starts, progresses, makes decisions, and interacts with external systems.
This approach allows you to create:
* Multi-step conversations
* Automated workflows
* Context-aware responses
* Cross-channel support
***
## **How Conversational Flows Work**
A conversational flow follows a structured sequence:
* A conversation begins
* The AI agent is triggered
* The agent responds or asks for input
* The user replies
* The system analyzes the message
* Actions or decisions are executed
* The conversation continues until completion
Each of these steps is powered by specific nodes in the builder.
***
## **1. Start Trigger (Entry Point)**
The **Start Trigger** defines when an AI agent workflow begins. It acts as the entry point of every conversational flow.
When a new agent is created:
* The Start Trigger node is automatically added
* It cannot be removed or replaced
* All other nodes connect after it
### **Trigger Event**
**Conversation Started (Default Event)**
SigmaMind currently supports one trigger event:
* **Conversation Started**
This event activates the AI agent whenever a new conversation begins across any supported channel.
### **Supported Scenarios**
* Chat initiated via helpdesk
* Incoming support email
* Slack or WhatsApp conversation
* Inbound phone call
* Outbound system call (e.g., callback)
### **Configuration Options**
**Multiple Conditions**
* Add multiple conditions using OR logic
* The flow starts if any condition is satisfied
**Filter by Intent (Optional)**
* Restrict agent activation based on user intent
* Uses pre-trained intents from SigmaMind AI
* Requires high confidence (>95%)
Best suited for: chat and email\
Not recommended for: voice-first interactions
### **Important Note**
For voice conversations, intent is typically detected later in the flow using the **Analyze Customer Message** node.
***
## **2. Core Nodes in Conversational Flow**
After the Start Trigger, different nodes are used to design the conversation.
### **Send Response**
The **Send Response** node is used to communicate with users.
It supports:
* Dynamic prompts
* Predefined templates (macros)
* Channel-specific messaging
👉 Used for greetings, confirmations, and replies.
(See [Send Response](/documentation/agents/add-basic-nodes/response-node) documentation for detailed configuration.)
***
### **Analyze Customer Message**
The **Analyze Customer Message** node helps the AI understand what the user is saying and route the conversation accordingly.
It evaluates the customer’s message against defined conditions and directs the flow based on the best match. If no match is found, the conversation follows the Else path.
👉 Used to detect user intent and enable multi-path conversations.
(See [Analyze Customer Message](/documentation/agents/add-basic-nodes/customer-intent-node) documentation for details.)
***
### **Wait**
The **Wait** node pauses the flow until a specific event occurs.
It allows:
* Waiting for user replies
* Adding time delays
* Controlling conversational timing
👉 Essential for enabling back-and-forth conversations.
(See [Wait](/documentation/agents/add-basic-nodes/wait-node) documentation for details.)
***
### **Tool Actions**
The **Tool Actions** node connects the agent to external systems via APIs.
It enables:
* Data retrieval (e.g., order details)
* Performing actions (e.g., updating records)
👉 Used for real-time integrations with CRMs, Shopify, etc.
(See [Tool Action](/documentation/agents/add-advance-nodes/app-action-node) documentation for setup and usage.)
***
### **Branch**
The **Branch** node introduces decision-making into the flow.
It supports:
* Conditional logic (AND/OR)
* Data-based routing (e.g., API responses)
👉 Used to create dynamic and personalized conversation paths.
(See [Branch](/documentation/agents/add-basic-nodes/branch-node) documentation for advanced conditions.)
***
## **3. Designing Conversational Flows**
A complete conversational flow is created by connecting nodes in a logical sequence.
### **Typical Flow Structure**
* Start Trigger
* Send Response (Greeting)
* Wait (User Input)
* Analyze Customer Message
* Tool Actions (Fetch Data / Perform Action)
* Branch (Decision Making)
* Send Response
* Loop back to Wait
This structure enables dynamic and interactive conversations.
***
## **4. Example Use Case: Order Cancellation**
### **Flow Overview**
* Conversation starts
* User requests order cancellation
* Message is analyzed
* Order details are retrieved via App Actions
* Eligibility is checked using Branch
* AI offers a retention discount
* Waits for user response
* Continues based on user decision
***
## **5. Looping Mechanism**
Looping is a key concept in conversational design.
After responding, the flow can reconnect to the **Wait** node, allowing:
* Continuous interaction
* Multi-turn conversations
* Decision-based progression
***
## **6. Testing in Playground**
SigmaMind provides a Playground to test conversational flows.
### **What to Validate**
* Trigger activation
* Node execution flow
* Message analysis accuracy
* API responses
* Final output See [Test Your Agent](/documentation/playground/overview) documentation for detailed info.
***
## **7. Best Practices**
* Keep flows simple and modular
* Use clear and specific conditions in Analyze Customer Message
* Add fallback (Else) responses
* Use branching for personalization
* Always include Wait nodes for interaction
* Test multiple scenarios before deployment
***
## **Conclusion**
SigmaMind’s Conversational Flow Builder allows you to design scalable, intelligent AI agents by combining:
* A fixed entry point (Start Trigger)
* Modular conversation nodes
* Message-based routing (Analyze Customer Message)
* API integrations (Tool Actions)
* Conditional logic (Branch)
* Continuous interaction (Wait + looping)
By structuring flows effectively, you can deliver seamless, automated, and human-like conversational experiences across multiple channels.
***
# Dynamic variables
Source: https://docs.sigmamind.ai/documentation/agents/agent-variables
Learn how to use dynamic variables in SigmaMind to personalize responses, campaigns, and conversations.
Dynamic Variables enable real-time personalization across every interaction in SigmaMind. Instead of static, hardcoded messages, you define named placeholders in your agent prompts, email templates, and workflow logic. At runtime, those placeholders are resolved with live values sourced from APIs, campaign files, webhooks, headers, or the conversation itself producing responses that feel specific and contextual to each individual customer.
**Dynamic variables use double curly brace syntax throughout the platform:**
```text theme={null}
{{ variable_name }}
```
For example, if you want to include a customer’s name in a message:
```text theme={null}
Hello {{ customer_name }}, thanks for reaching out!
```
**Behavior when a variable is undefined at runtime**
If a variable is referenced in a node but no value has been provided, the platform renders an empty string by default.
## Where Dynamic Variables Are Supported
### Dynamic variables can be used in any nodes inside SigmaMind:
* **Agent Responses** – Personalize replies with customer details.
* **Email Templates** – Insert variables like `{{ customer_email }}` or `{{ order_id }}`.
* **Campaigns** – Pass variables from campaign uploads or APIs to customize conversations.
* **Webhooks and Integrations** – Include context-specific variables in outbound data.
Dynamic variables make your AI agent feel more personal and context-aware without requiring manual customization for each interaction.
## Sources of Dynamic Variables
### Dynamic variables can come from multiple sources:
Variables can be populated from different sources. Use the table below to select the right source for your integration pattern, then refer to the corresponding section for implementation details.
| Source | Trigger | Best for | Real-time? |
| ---------------------------------------- | ------------------------------------------- | --------------------------------------------------------------- | --------------- |
| API | API request containing a variables object | Backend-driven personalization for calls, chats, or workflows | Yes |
| Campaign CSV Upload | Batch campaign creation via CSV or API | Large-scale outreach with pre-defined contact data | No (pre-loaded) |
| Inbound Webhook | Customer initiates an inbound call | Real-time CRM lookup and dynamic routing for inbound calls | Yes |
| Custom Headers | Call creation or transfer with metadata | Passing structured, non-conversational metadata between systems | Yes |
| Conversation Extraction(Extract Varable) | Agent captures data during the conversation | Collecting user-provided data naturally during interaction | Yes (live) |
#### 1. [Create Call API](/api-reference/calls/create-phone-call)
When creating a call via the API, you can pass custom variables in the `variables` object.
```json Example API Create Call with Variables theme={null}
{
"fromPhoneNumber": 14155552671,
"toPhoneNumber": 14155552671,
"agentId": "D5D0p7TUs66TTAEAx",
"variables": {
"customer_name": "Michael"
}
}
```
#### 2. [Campaign Uploads](/api-reference/campaigns/create-campaign)
When uploading a CSV file for a campaign, include columns for any variables you want to use.
```sh Create Campaign with Variables theme={null}
curl --request POST \
--url https://api.sigmamind.ai/v1/campaigns \
--header 'Content-Type: multipart/form-data' \
--header 'X-API-Key: ' \
--form 'campaignName=' \
--form sipPhoneNumber=14155552671 \
--form agentId=D5D0p7TUs66TTAEAx \
--form isScheduled=true \
--form scheduledDate=2023-11-07T05:31:56Z \
--form scheduledTime=12:00:00 \
--form scheduledTimezone=America/Los_Angeles \
--form concurrentCalls=5 \
--form 'variables={
"customer_name": "Michael"
}' \
--form file=@example-file
```
```csv Example Create Campaign uploading CSV with Variables theme={null}
Phone Number,Customer Name,Order ID
+14155552671,Michael,12345
+14155552672,Sarah,67890
```
These values will be injected into your campaign messages automatically in lowercase with underscores.
#### 3. [Inbound Webhooks](documentation/calls/receive-calls) (Receive Calls)
When a user calls your number, you can dynamically inject variables using an **Inbound Webhook**.
### Request Payload
```json theme={null}
{
"event": "inbound_call",
"agent_id": "shvb5xs5fo2D2222",
"from_number": "+12345678912",
"to_number": "+12345678913"
}
```
## **Response**
Your endpoint should return a JSON response with a 2xx status code, containing upto 2 optional fields. The following fields are available:
* `dynamic_variables`: use this to define dynamic variables specific to this inbound call.
* `override_agent_id`: if you want to override the agent id, you can set it here.
Here’s a sample response for inbound call:
```json theme={null}
{
"dynamic_variables": {
"first_name": "Jim",
"last_name": "Smith"
},
"override_agent_id":"shvb5xs5fo2D2225"
}
```
### **End-to-end flow**
1. Customer dials your SigmaMind number.
2. SigmaMind sends the inbound\_call payload to your webhook URL.
3. Your system performs a CRM or database lookup using from\_number.
4. Your system returns dynamic\_variables
5. SigmaMind connects the agent with all returned variables pre-loaded.
6. The agent begins the conversation with full customer context already available.
### Use when:
* Handling inbound calls
* Fetching real-time customer data
* Routing calls dynamically
#### 4. [Custom Headers](/documentation/agents/add-advance-nodes/howto-use-sip-custom-header)
Custom Headers allow you to send structured metadata along with a call or call transfer.
They are:
* Not visible to the customer
* Available to backend systems, CRMs, and receiving agents
Learn more about Custom Headers [here](/documentation/agents/add-advance-nodes/howto-use-sip-custom-header)
#### 5. Conversation Extracted Variables
Some variables are automatically captured from the conversation itself. For example:
* If the agent asks for the customer’s email, it can be extracted and stored as `{{ customer_email }}`.
* If the agent identifies an order number, it can be stored as `{{ order_id }}`.
Conversation variables are context-aware and evolve as the interaction progresses.
### Example Usage
* In an Agent Response
```text theme={null}
Hi {{ customer_name }}, your order {{ order_id }} is confirmed and will be delivered by {{ delivery_date }}.
```
* In an Email Template
```text theme={null}
Subject: Order Confirmation for {{ customer_name }}
Dear {{ customer_name }},
Thank you for your purchase! Your order ID is {{ order_id }}.
We will notify you at {{ customerEmail }} once your order ships.
Best regards,
Team SigmaMind
```
Lifecycle of a Dynamic Variable
**Step 1: Define**
```text theme={null}
Hi {{ customer_name }}
```
**Step 2: Populate (Runtime)**
Value comes from:
* API
* Campaign (CSV)
* Webhook
* Custom Headers
* Conversation
**Step 3: Use**
**Used in:**
* Agent responses
* Tool execution
* Workflow logic
**Step 4: Observe**
You can view variable values in:
* Conversation logs
* Node logs
* System logs
* Post-conversation analysis
* Webhook outputs
## View Dynamic Variables at Runtime (Dashboard)
You can view how dynamic variables are populated during a call directly from the dashboard.
### Steps
1. Go to **Conversations** from the left sidebar
2. Click on any call or chat
3. Open the **Dynamic Variables** tab
### What You’ll See
* All variables available during that conversation
* Runtime values (from API, webhook, headers, or extraction)
Example:
```text theme={null}
customer_name → Michael
order_id → 12345
last_order_date → 2026-04-20
```
***
## Why This Is Important
Use this view to:
* Debug missing or incorrect variables\\
* Verify data passed from API / webhook / CSV\\
* Understand how variables change during runtime\\
***
You can also see:
* **Transcript** → See where variables are used in conversation\\
* **Node Logs** → Debug step-by-step execution\\
* **System Logs** → Check backend events\\
* **Analysis** → View post-conversation insights
***
### Best Practices
* Always provide default values to handle missing or undefined variables.
* Keep variable names simple, consistent, and descriptive (e.g., customer\_name, order\_id).
* Validate and sanitize inputs from external sources such as API, CSV uploads, webhooks, and headers.
* Use the right source for the right use case (API for real-time data, CSV for campaigns, webhook for inbound calls, headers for metadata).
* Prefer conversation-extracted variables to reduce manual data collection during interactions.
* Avoid overloading variables with complex or nested data—keep values clean and usable.
* Test variable population during simulation to ensure values are correctly passed at runtime.
#### Summary:
* Dynamic Variables use the `{{ variable_name }}` format and allow you to inject real-time data into your agent.
* They are populated at runtime from sources like API calls, CSV campaigns, inbound webhooks, custom headers, and conversation inputs.
* They can be used across all agent nodes to enable personalized, context-aware, and fully automated interactions.
***
Dynamic variables empower your AI agent to adapt responses to each customer’s context, making conversations more natural and engaging.
# Agent level Webhooks
Source: https://docs.sigmamind.ai/documentation/agents/agent-webhooks
Learn how to use Webhooks in SigmaMind to receive real-time events from AI agents.
**Webhooks** in SigmaMind let you receive **real-time notifications** about events happening in your AI agents.\
Whenever an event is triggered (e.g., a conversation starts or ends), SigmaMind will send an HTTP `POST`request with a JSON payload to your configured webhook URL.
This allows you to fetch conversation info from your agents in your own applications, CRMs, or monitoring systems.
***
## How Webhooks Work
* Each **AI Agent** can have its own webhook.
* A **single webhook URL** can be reused across multiple agents.
* When the selected event occurs, SigmaMind sends a signed JSON payload to your webhook endpoint.
* Your system can then process this payload to perform actions like updating CRM records, triggering workflows, or logging analytics.
Think of webhooks as **push notifications** for your backend — you get updates instantly when something important happens in SigmaMind.
***
## Supported Webhook Events
The following events are currently supported:
* **conversation\_started** – Triggered when a new customer conversation begins.
* **conversation\_ended** – Triggered when a conversation is closed or completed.
* **conversation\_analysed** – Triggered when call analysis is completed.
***
## Creating Webhooks
You can create webhooks in **two ways**:
### 1. Using the Dashboard
You can configure webhooks from **Agent Settings**:
1. Open the **AI Agent** you want to connect.
2. Go to **Agent Settings → Webhooks**.
3. Click on **Add Webhook**
4. Provide the following details -
* **Webhook Name** - Set the name you want to give this webhook.
* **URL** - Enter a webhook URL. You'll find this from your system where you want to receive the events from SigmaMind.
* Hit **Submit** to add the Webhook.
***
### 2. Using the API
If you prefer programmatic control, you can use the [**Webhook API**](/api-reference/webhooks/create-webhook) to register webhooks.
* The `name` field is a human-readable identifier for your webhook.
* The `url` is the endpoint in your system that will receive webhook events.
* The `agentId` must correspond to an existing Agent in your SigmaMind account.
* The `events` parameter lists which Agent events will trigger the webhook.
```sh Create Webhook theme={null}
curl --location 'https://api.sigmamind.ai/v1/webhooks' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: key_C6HL3Goru7Q.TlI5kZOKPmDM03Gt39nRBEnxrL*******************' \
--data '{
"name": "Test Webhook 1",
"url": "https://your-server.com/webhooks/ai-agent",
"agentId": "D5D0p7TUs66TTAEAx",
"events": [
"conversation_started",
"conversation_ended"
]
}'
```
## Security and Verification
### 🔑 Secret Generation
* Each webhook is associated with a unique secret.
* This secret is generated securely using a cryptographically strong random generator.
* We store this secret encrypted at rest.
* You should securely store this secret on your side — it is required to verify incoming webhooks.
***
### 📦 What We Send
Every webhook request includes:
#### Headers
| Headers | Description |
| ----------------------- | ------------------------------------ |
| `x-webhook-signature` | HMAC SHA256 signature of the request |
| `x-webhook-timestamp` | Unix timestamp (in seconds) |
| `x-webhook-delivery-Id` | Unique delivery ID (for idempotency) |
| `x-webhook-id` | Webhook identifier |
#### Body
* JSON payload (exact content used for signature generation)
***
### 📄 Example Payload
Here’s an example of the webhook payload your endpoint will receive:
```json theme={null}
{
"id": "wh_BUbkx3PsbzQm5V10",
"event": "conversation_started",
"createdAt": "2026-05-04T10:05:37.800",
"data": {
"workspace": {
"workspace_id": "org_9y41TftLgBOuLi7e"
},
"agent": {
"name": "Test Agent",
"agent_id": "CYu0gJcTPZdy36T1",
"status": "Testing"
},
"phone_number": {},
"call": {
"call_id": "call_X8T94GBhe4mhFwct",
"call_type": "web",
"phone_number": null,
"status": "in_progress",
"start_time": "2026-05-04T08:05:37.845386Z",
"end_time": null,
"duration": 0,
"termination_reason": null,
"created_at": "2026-05-04T08:05:37.841",
"updated_at": "2026-05-04T08:05:37.968",
"recording_url": null,
"agent": {
"name": "Test Agent",
"agent_id": "CYu0gJcTPZdy36T1",
"status": "Testing"
}
},
"customer": {
"id": 17183296,
"name": "#Customer17183296_1777881938",
"email": null,
"phone": null,
"first_name": "#Customer17183296",
"last_name": "_1777881938"
},
"conversation": {
"id": 1810156,
"channel": "phone",
"status": "open",
"subject": "New conversation",
"via": "playground",
"email": null,
"phone": null,
"usage": null,
"helpdesk_source": "playground",
"store_name": null,
"voice_call_id": "room-playground-7VDMBztOdeHjEQQz",
"call_id": "call_X8T94GBhe4mhFwct",
"messages": [
{
"id": "5977628",
"role": "user",
"content": "New Call Started",
"channel": "phone",
"via": "playground",
"conversation_id": 1810156,
"helpdesk_source": "playground",
"intent": null,
"created_at": 1777881937,
"updated_at": null
}
],
"latest_message": {
"id": "5977628",
"role": "user",
"content": "New Call Started",
"channel": "phone",
"via": "playground",
"conversation_id": 1810156,
"helpdesk_source": "playground",
"intent": null,
"created_at": 1777881937,
"updated_at": null
},
"created_at": 1777881937,
"updated_at": 1777881937,
"closed_at": null,
"has_agent_response": false
},
"metadata": null,
"actions": {},
"dynamic_variables": {
"customer_phone_number": "",
"summary": null,
"fcustomer-name": null,
"calltransferredtolabtechnician": null,
"address": null,
"phone_number": "{{customer.phone}}",
"customer_name": "Aditya"
},
"usage": {},
"post_call_analysis": null
}
}
```
### 🔏 How Signature is Generated
We compute the signature using:
```sh theme={null}
signature = HMAC_SHA256(secret, timestamp + "." + payload)
```
and send it as:
```sh theme={null}
x-webhook-signature: sha256=
```
### ✅ How to Verify Webhook (Client Side)
To validate that the webhook is genuine:
#### Step 1: Extract values
* signature from header
* timestamp from header
* payload (raw request body)
***
#### Step 2: Recompute signature
```sh theme={null}
expectedSignature = HMAC_SHA256(secret, timestamp + "." + payload)
```
#### Step 3: Compare signatures
* Remove prefix sha256= from header signature
* Compare with your computed signature
* Use constant-time comparison to avoid timing attacks
#### Step 4: Validate timestamp (Replay Protection)
* Convert timestamp to current time
* Reject if difference > 5 minutes
Example:
```sh theme={null}
if (abs(current_time - timestamp) > 300 seconds) → reject
```
#### Step 5: Handle idempotency
* Use `x-webhook-delivery-id` to ensure the same event is not processed multiple times
Always use the raw request body (do not reformat JSON before verifying).\
Do not trust the request if signature validation fails.\
Keep your webhook secret secure (never expose in frontend code).
#### 💡 Examples
```sh Pseudo Code theme={null}
payload = timestamp + "." + rawBody
computed = HMAC_SHA256(secret, payload)
if (!constantTimeEquals(computed, receivedSignature)) {
reject request
}
```
```sh Java theme={null}
public String computeHmacSHA256(String secret, String payload) {
try {
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] raw = mac.doFinal(payload.getBytes(StandardCharsets.UTF_8));
return bytesToHex(raw);
}
catch (Exception ex) {
throw new GenericException("Failed to compute HMAC");
}
}
private String bytesToHex(byte[] bytes) {
StringBuilder sb = new StringBuilder(bytes.length * 2);
for (byte b : bytes) {
sb.append(String.format("%02x", b));
}
return sb.toString();
}
```
Always verify signatures before processing webhook data to prevent spoofing attacks.
### Summary
* Webhooks notify your system in real time about Agent events.
* You can create webhooks from the Dashboard or via the API.
* A single webhook URL can be used across multiple AI Agents.
* Supported events include conversation\_started, conversation\_analysed and conversation\_ended.
* Payloads are signed with a secret key for secure delivery.
### Where to View Analysis in Dashboard
After a conversation is completed and analysis is triggered (`conversation_analysed` event), you can also view the same data directly in the SigmaMind dashboard.
### Steps
1. Go to **Conversations**
2. Open any **Call or Chat**
3. Navigate to the **Analysis** tab
### What You’ll See
* All Post-Conversation Analysis fields
* Extracted insights (summary, outcome, scores, etc.)
* Structured data generated by the AI
***
### Why This Matters
* Helps you **verify webhook data**
* Useful for **debugging and testing**
* Ensures your analysis instructions are working correctly
Webhooks are the easiest way to integrate SigmaMind into your existing systems and automate workflows.
# Apply brand persona
Source: https://docs.sigmamind.ai/documentation/agents/brand-persona/apply-brand-persona
# Overview
Source: https://docs.sigmamind.ai/documentation/agents/brand-persona/overview
# Setup your brand persona
Source: https://docs.sigmamind.ai/documentation/agents/brand-persona/setup-your-brand-persona
# Create new intent
Source: https://docs.sigmamind.ai/documentation/agents/customer-intent/create-new-intent
# Disable existing intents
Source: https://docs.sigmamind.ai/documentation/agents/customer-intent/disable-existing-intents
# Overview
Source: https://docs.sigmamind.ai/documentation/agents/customer-intent/overview
# AI Agents Overview
Source: https://docs.sigmamind.ai/documentation/agents/overview
Learn how SigmaMind Agents work as conversational workflow builders for AI-driven interactions.
## Agent Builder Overview
An Agent in **SigmaMind AI** is a conversational workflow builder designed to handle customer interactions intelligently across voice, chat, and email.
Agents can be built using either **Single Prompt** or **Conversational Flow**, depending on the complexity of your automation needs.
They transform business processes into structured, scalable conversational experiences.
***
# What Is an Agent?
An Agent defines how AI interacts with customers by combining prompts, workflow logic, triggers, and integrations into a structured automation system.
It enables you to:
* Build structured conversational workflows
* Automate customer support, sales, and service processes
* Handle inbound and outbound interactions
* Integrate external systems and tools
* Ensure conversations follow a logical and predictable flow
Agents are the foundation of conversational AI inside SigmaMind.
***
## Two Ways to Build Agents
SigmaMind provides two approaches for building Agents:
* **Single Prompt AI Agent**
* **Conversational Flow**
## Single Prompt AI Agent
A **Single Prompt AI Agent** uses one main prompt to control the entire conversation, including:
* Welcome message behavior
* Variable collection
* Function/tool calls
* Voice actions
* Conversation flow logic
This approach is fast to configure and ideal for simple, structured workflows.
### When to Use a Single Prompt Agent
Use this approach when you need:
* Clear and straightforward conversations
* Quick testing and deployment
* Agents using a small number of tools
* Step-by-step interaction flows
Avoid using a Single Prompt Agent for complex, multi-step logic that requires heavy branching or multiple tool calls. For advanced automation, use Conversational Flow instead.
***
### Creating a Single Prompt AI Agent
1. Go to the **SigmaMind Dashboard**
2. Navigate to **AI Agents**
3. Click **Create AI Agent**
4. Choose one option:
* **New Single Prompt AI Agent** – Create from scratch
* **Select a Template** – Use a prebuilt agent
5. Click **Continue with this template**
***
## Using Templates
SigmaMind provides prebuilt templates to help you quickly deploy agents for common industries and use cases.
Templates include:
* Predefined prompt structure
* Tool configurations
* Built-in workflow logic
* Best-practice conversation design
You can fully customize any template after selecting it.
Templates reduce setup time and ensure production-ready configuration.
***
## Conversational Flow
Conversational Flow is designed for advanced conversational automation.
Agents are created using connected steps (nodes), where each step represents a specific part of the interaction. By connecting these steps together, you define how the AI:
* Sends responses
* Analyzes user input
* Waits for replies
* Branches based on conditions
* Calls external systems
* Performs voice or helpdesk actions
This approach provides deterministic control and is ideal for multi-step workflows with complex branching and integrations.
### When to Use Conversational Flow
Use this approach when you need:
* Advanced branching logic
* Multiple integrations and actions
* Full control over conversation structure
* Predictable, rule-based workflows
***
### Creating a Conversational Flow AI Agent
1. Go to the **SigmaMind Dashboard**
2. Navigate to **AI Agents**
3. Click **Create AI Agent**
4. Choose one option:
* **New conversational flow AI Agent** – Create from scratch
* **Select a Template** – Use a prebuilt agent
5. Click **Continue with this template**
You will now enter the Flow Builder interface, where you can design your workflow using connected nodes.
# How an Agent Works
When a phone number or communication channel (voice, chat, or email) is connected to an Agent, every incoming conversation is processed through that Agent’s workflow.
The workflow logic depends on whether the Agent is built using Single Prompt or Conversational Flow.
```text theme={null}
Single Prompt Agents rely on prompt-driven reasoning and internal AI logic to guide the conversation.
Conversational Flow Agents execute deterministic, step-based logic defined by connected nodes.
```
***
## Default Start Trigger
When a new **Conversational Flow Agent** is created, a **Start Trigger** node is automatically added to the canvas.
The Trigger Event is preconfigured as:
* `conversation_started`
This means the Agent will automatically activate whenever a new conversation begins on a connected communication channel (voice, chat, or email).
The Start Trigger node is automatically added and cannot be removed. Every Conversational Flow Agent begins execution from this node.
***
## How the Default Trigger Works
1. A customer initiates a new call, chat, or email.
2. The `conversation_started` event is detected.
3. The Start Trigger node activates the Agent.
4. The workflow begins executing from the connected node (for example, a Send Response node).
***
## Trigger Configuration Options
Inside the Start Trigger node, you can:
* Add additional trigger conditions using OR logic
* Add intent filters (if required)
> Note: Currently, `conversation_started` is the only supported trigger event in SigmaMind.
***
## Conversational Flow Nodes
Once triggered, the Agent evaluates nodes in sequence.
Each node represents a specific action in the workflow.
**Available Nodes**
* **Send Response** – Sends a message to the customer.
* **Analyze Customer Message** – Interprets customer input to detect intent or understand meaning.
* **Wait** – Pauses the workflow until the next customer message is received.
* **Branch** – Routes the conversation based on defined conditions.
* **Jump** – Moves the flow directly to another node.
* **Tools Action** – Executes external app integrations or API calls.
* **Helpdesk Action** – Performs actions within connected helpdesk systems.
* **Voice Action** – Triggers voice-specific actions such as transferring or ending calls.
* **Extract Variables** – Captures structured data from customer messages for later use.
For detailed configuration instructions, refer to the Add Basic Nodes section.
***
## Continuous Conversation Handling
* When a **Wait** step is active, the Agent pauses until the next message arrives.
* An **Analyze** step evaluates input and determines the next step.
* The Agent continues progressing through the flow until completion.
***
# Agent Flow Example
A typical workflow may look like this:
1. A customer calls a number connected to SigmaMind.
2. The **Conversation Started** event triggers the Agent.
3. The Agent sends an initial greeting using a **SendResponse** step.
4. The customer replies.
5. An **Analyze** step detects intent.
6. A **Branch** step routes the conversation.
7. A **Wait** step collects additional input if required.
8. A **Tools Action** step calls an external API.
9. The conversation ends with a closing message or human transfer.
***
# Requirements for Using an Agent
To deploy an Agent, you must have:
* At least one connected communication channel (voice, chat, or email)
* A configured Agent (Single Prompt or Conversational Flow)
* A configured Start Trigger (automatically added for Conversational Flow Agents)
* Connected integrations if external actions are required
A well-structured Agent ensures predictable and smooth conversations while minimizing failure cases.
***
# What You Can Achieve with Agents
With SigmaMind Agents, you can:
* Provide 24/7 automated customer support
* Route conversations dynamically based on intent
* Integrate with CRM, e-commerce, and helpdesk systems
* Personalize responses using dynamic variables and context
* Reduce manual workload through automation
* Scale operations across multiple communication channels
***
# Summary
Agents power intelligent automation inside SigmaMind.
You can choose between:
* **Single Prompt AI Agents** for simple and fast deployment
* **Conversational Flow** for advanced, multi-step automation
Agents are triggered by conversation events and execute structured logic using prompts or connected flow steps.
Uses one master prompt to control the entire conversation.
Build advanced, multi-step workflows using connected nodes.
# Basic Settings
Source: https://docs.sigmamind.ai/documentation/agents/settings/basic
The Basic Settings section allows you to configure the core behavior of your AI Agent, including voice selection, model choice, language preferences, and how conversations begin.
These settings directly influence how your agent sounds, understands users, and interacts during calls.
When a call or message is connected to your AI Agent, the conversation flow is determined by the configurations set in this section.
You can define:
* How your agent speaks (Voice)
* How your agent thinks (LLM Model)
* Which language it understands
* Who starts the conversation
## How to Configure
1. Open your agent in the **Agent Builder**
2. From the right-side panel, click on **Agent Settings**
3. In the **Basic Settings** section, configure Voice, LLM Model, Language, and conversation start preference
All changes are automatically saved. Review your settings before going live.
***
## 1. Select Voice
The **Select Voice** option allows you to choose how your AI Agent sounds during conversations.
You can select from multiple voice providers such as:
* ElevenLabs
* OpenAI
* Cartesia
* Rime AI
* Hume AI
Each provider offers a variety of voices with different tones, accents, genders, and speaking styles.
### Features
* **Search Voices**\
Quickly find voices using the search bar.
* **Filters Available**\
Narrow down voices based on:
* Age (young, middle-aged, etc.)
* Gender (male, female)
* Accent (Indian, British, American, etc.)
* **Voice Preview**\
Click **Play** to listen before selecting.
* **Voice Details**\
Each voice includes:
* Description
* Accent
* Age group
* Gender
* **Select Voice**\
Choose a voice that best matches your use case and brand tone.
* **Add Custom Voice**\
You can also upload or create a custom voice for a more personalized experience.
### Example
A warm and friendly voice is ideal for customer support, while an energetic voice works well for marketing or engagement calls.
***
## 2. Select LLM Model
The **LLM Model** determines how your AI Agent understands and responds to users.
Different models offer varying levels of:
* Intelligence
* Speed
* Cost
### Available Models (Example)
* GPT-5 Nano – Ultra fast and low cost
* GPT-5 Mini – Balanced performance
* GPT-5 Fast Tier – Faster responses for real-time interactions
* GPT-5.2 / GPT-5.1 – More advanced reasoning and accuracy
### How to Choose
* Use **lightweight models** for simple, high-volume conversations
* Use **advanced models** for complex queries and detailed interactions
Each model may have a cost per minute associated with usage, so choose based on your budget and requirements.
***
## 3. Select Language
The **Select Language** option allows you to define the primary language your AI Agent will use during conversations.
This setting ensures that the agent can accurately understand user input and respond in a natural, fluent manner.
***
### Overview
Choosing the correct language improves:
* Speech recognition accuracy
* Response quality
* Overall conversation experience
The selected language will be used throughout the interaction unless configured otherwise.
***
### Available Options
The platform supports a wide range of languages and regional variations.
For example:
* English
* English (US)
* English (UK)
* English (India)
* English (Australia)
* Hindi
* Multilingual (English + Spanish)
* Multilingual (Spanish + English)
These options allow your agent to handle conversations in one or multiple languages depending on your use case.
***
### How It Works
* The AI Agent listens and processes input based on the selected language
* It responds in the same language for a consistent experience
* Multilingual settings allow the agent to switch between supported languages dynamically
***
### Examples
**English (US)**\
Best suited for customers based in the United States or global audiences familiar with US English.
**English (India)**\
Ideal for Indian users, with better alignment to accent and communication style.
**Hindi**\
Useful for regional audiences who prefer Hindi communication.
**Multilingual (English + Spanish)**\
Enables the agent to handle conversations in both English and Spanish seamlessly.
***
### Best Practices
* Select the language based on your target audience
* Use **multilingual options** only when necessary to avoid confusion
* Match language with the selected voice for better consistency
* Test conversations to ensure accuracy and fluency
***
### Notes
* Incorrect language selection may lead to poor understanding of user input
* Always validate your configuration in the Playground before going live
***
## 4. Who Speaks First in the Call
This setting controls how the conversation begins when a call is connected.
***
### AI Starts the Conversation
The AI Agent immediately initiates the conversation.
* Sets the tone and context
* Provides a structured start
* Ideal for guided interactions
> **Example:**\
> “Hello, thanks for calling SigmaMind support. How can I help you today?”
***
### Customer Starts the Conversation
The AI Agent waits for the user to speak first.
* Creates a natural, user-driven interaction
* Allows customers to explain their issue directly
* Best for support and inbound scenarios
> **Example:**\
> Customer: “Hi, I need help with my order.”\
> Agent: Responds accordingly
***
## Use Cases
**AI First**
* Outbound calls
* Sales or onboarding flows
* Structured support interactions
**Customer First**
* Inbound support calls
* Helpdesks
* Self-service or query-based interactions
***
## Best Practices
* Choose a voice that matches your brand personality
* Test different LLM models for performance vs cost
* Always set the correct language for your audience
* Select the conversation flow based on your use case
# Call Settings
Source: https://docs.sigmamind.ai/documentation/agents/settings/call
Configure voicemail detection, reminders, silence handling, and max call duration.
Call settings control how your AI agent manages live calls, ensuring they are handled efficiently and gracefully. These options define behaviors for voicemail detection, IVR handling, reminders, silence detection, and call duration limits.
***
## Voicemail Detection
If a voicemail system is detected, the agent can be configured to:
* **Hang up the call** immediately.
* **Leave a voicemail** with a pre-configured message.
This prevents wasted call time and ensures important messages are delivered even when the customer is unavailable.
***
### IVR Detection
**Hang up if the IVR system is detected**
When enabled, the agent will automatically disconnect upon detecting an IVR (Interactive Voice Response) system. This prevents the agent from getting stuck navigating automated menus.
***
## **Send Reminder Message**
Agents can automatically **send reminder messages** during a call if the customer is inactive or not responding.
You can configure reminders as either:
* **Time-based** → e.g., every 10 seconds.
* **Count-based** → e.g., up to 4 times.
This ensures the agent remains proactive without overwhelming the customer.
***
## End call on silence (in minutes)
Agents can also be set to **end the call automatically** if silence is detected for a configured period.
Example:
* End call after **30 seconds of silence**.
This avoids unnecessary call charges and frees up the agent for new conversations.
***
## Max call duration (in minutes)
You can define a **maximum call duration** for each call.
Example:
* If set to **10 minutes**, the call will automatically disconnect once the limit is reached.
This prevents calls from running indefinitely due to unexpected scenarios.
***
### Ring Duration (in minutes)
Define how long the system should keep ringing before the call is unanswered:
* **Current setting:** **60 minutes** (out of 120 minutes max)
If the call is not answered within this duration, it will automatically stop ringing. This prevents prolonged unanswered call attempts and optimizes system resources.
***
## Summary
* **Voicemail Detection** → Hang up or leave a voicemail.
* **Reminder Messages** → Send based on time or count.
* **End call on silence (in minutes)** → End call after configurable silence duration.
* **Max Call Duration** → Automatically disconnect calls after a set time.
Call settings give you full control over how long conversations run and how they should end gracefully.
# Model Settings
Source: https://docs.sigmamind.ai/documentation/agents/settings/model
The Model Settings page allows you to configure a Global Prompt that will be automatically applied to all conversations.
### Global Prompt (Optional)
The **Global Prompt** is a system-level instruction that shapes how the model responds across every interaction.
* **Purpose:**\
Use this field to define consistent behavior, tone, or rules for the AI.
* **How it works:**\
Any text entered here is prepended to every conversation, influencing responses without needing to repeat instructions each time.
* **Examples:**
* “Respond in a professional and concise tone.”
* “Always provide step-by-step explanations.”
* “Act as a helpful coding assistant specialized in Python.”
* **When to use it:**
* Enforcing a consistent writing style
* Setting domain expertise (e.g., legal, medical, technical)
* Defining response constraints or preferences
* **When to leave it empty:**
* If you want each conversation to behave independently
* If instructions will vary frequently between chats
### Input Field
* Enter your global prompt in the text area labeled **“Enter value”**
* Changes take effect immediately for new and ongoing conversations
# Agent Settings Overview
Source: https://docs.sigmamind.ai/documentation/agents/settings/overview
Configure Agent settings in SigmaMind to control behavior, voice, models, and integrations.
Agents in SigmaMind come with a set of configurable settings that define **how they behave, speak, and process calls**.\
These settings allow you to customize the Agent’s personality, control technical parameters, and integrate external systems for advanced workflows.
## Available Settings
Configure agent voice, model, and language settings here.
Configure speech settings here.
configure Global Prompt here
Transcription Settings control how audio is processed before it is converted into text.
Configure call settings here.
Learn how to use dynamic variables in SigmaMind here
Learn How to use Post-Conversation Analysis
Learn How to use Webhooks in SigmaMind here
## Summary
Agent settings in SigmaMind give you full control over:
* **Voice and language** – Select your agent voice and language.
* **Intelligence** - Select an LLM to give your agent intelligence
* **Speech** – Tone and sound experience.
* **Call controls** – Voicemail handling, silence detection, and call limits.
* **Post-call analysis** – Insights and reporting after conversations.
* **Webhooks** – Real-time integration with external systems.
By tuning these settings, you can shape how your AI Agent behaves, speaks, and integrates — ensuring conversations are personalized, efficient, and aligned with your business needs.
# Post Conversation Analysis
Source: https://docs.sigmamind.ai/documentation/agents/settings/post-call-analysis
Learn how to use Post-Conversation Analysis in SigmaMind AI to automatically extract insights from conversations.
Post-Conversation Analysis allows your agent to analyze conversations after they end and extract useful insights automatically. These insights convert conversations into structured data that can be stored, analyzed, or sent to other systems.
You can define multiple fields and instruct the AI to extract specific information from each conversation.
These Analysis convert conversations into **usable data** that can be:
* Stored
* Analyzed
Sent to external systems
👉 Post-Conversation Analysis is billed separately. Charges are based on the chat message pricing of the selected LLM model.
## Enable Post-Conversation Analysis
To enable and configure Post-Conversation Analysis:
1. Open your **Agent Builder**.
2. From the side panel, click **Agent Settings**.
3. Expand the **Post-Conversation Analysis** section.
4. Toggle the switch **ON** to enable the analysis
Once enabled, the selected model (for example **GPT-4o mini**) will analyze conversations after they end and extract the configured Analysis
***
## Add New Field
To extract specific information from conversations, you can create custom fields.
1. In the **Post-Conversation Analysis** section, click **Add New Field**.
2. Select the type of Field you want to create.
3. Enter an **Name of Analysis.**
4. Provide **Analysis Instructions** that tell the AI what to extract from the conversation.
5. Click **Submit**.
The AI will analyze each conversation and populate the field based on your instructions.
***
## Field Types
SigmaMind supports four types of fields.
### Text
The **Text** field is used when you want the AI to generate written output.
### Best For:
```text theme={null}
Conversation summaries
Main reason for the call
Key discussion points
```
**Example**
```text theme={null}
Analysis Name:
conversation summary
```
**Analysis Instructions:**
```text theme={null}
Write a concise summary of the conversation including the main topic and final outcome.
```
***
### Selector
The **Selector** field allows the AI to choose one value from predefined options.
This is useful for categorizing conversations into structured outcomes.
### Best For:
```text theme={null}
Call outcomes
Intent classification
Routing analysis
```
**Example**
```text theme={null}
Analysis Name:
call outcome
```
**Analysis Instructions**
```text theme={null}
Select the final outcome of the conversation from the predefined options.
```
***
### Boolean
The **Boolean** field returns a **true or false** value.
This is useful for determining whether a specific event occurred during the conversation.
### Best For:
```text theme={null}
Event tracking
Conversion tracking
```
**Example**
```text theme={null}
Analysis Name:
appointment booked
```
**Analysis Instructions**
```text theme={null}
Return true if an appointment was booked during the conversation, otherwise return false.
```
***
### Number
The **Number** field allows the AI to return a numeric value.
This is useful for scoring or counting information from the conversation.
### Best For:
```text theme={null}
Scoring
Counting
Ratings
```
**Example**
```text theme={null}
Analysis Name:
sentiment score
```
**Analysis Instructions**
```text theme={null}
Rate the overall customer sentiment from 1 to 10 where 1 is very negative and 10 is very positive.
```
**Choosing the Right Model**
You can select which LLM model to use for Post-Conversation Analysis.
### Recommended Models by Use Case
**For Simple Classification (Fast & Low Cost)**\
Use:
* GPT-4o mini
**Best for:**
* Boolean fields (true/false)
* Selector fields (categorization)
Basic tagging (intent, outcome)
**Performance:**
* ⚡ Fastest response time
* 💲 Lowest cost
* 📉 Lower depth of analysis
***
**For Balanced Performance (Most Common Use Cases)**\
Use:
* GPT-4o
**Best for:**
* Conversation summaries
* Key information extraction
* General analysis with good accuracy
**Performance:**
* ⚖️ Balanced latency and quality
* 💲 Moderate cost
* ✅ Recommended default for most users
***
**For Advanced Analysis (High Accuracy)**\
Use:
* GPT-5 (or latest high-quality model available)
Best for:
* Complex reasoning
* Detailed summaries
* Multi-step analysis
* High-stakes workflows (sales insights, compliance, etc.)
**Performance:**
* 🧠 Highest quality output
* 🐢 Higher latency (slower responses)
* 💲 Higher cost
***
### Trade-offs
* **GPT-4o mini** → Lowest cost, fastest, but less detailed
* **GPT-4o** → Balanced cost and quality (recommended default)
* **GPT-5** → Highest quality, but higher cost and latency
***
### Recommendation
* Start with **GPT-4o** for most use cases
* Use **GPT-4o mini** for simple structured fields
* Upgrade to **GPT-5** only when higher accuracy is required
#### **Managing Fields**
After creating a field, you can:
* Edit the field to update the instructions
* Delete the field if it is no longer required
* Add multiple fields to capture different insights from conversations
You can also choose which model should be used for the analysis.
***
## Sending Extracted Data
The Analysisextracted through Post-Conversation Analysis can be sent to external systems using **SigmaMind Webhooks**.
Using webhooks, you can automatically send the extracted data to:
* CRM systems
* Google Sheets
* Databases
* Automation platforms such as n8n or Zapier
* Custom applications
This helps automate workflows and store conversation insights for further analysis.
### Where to View Analysis
After a conversation ends, you can view extracted insights in:
* Go to **Conversations**
* Open any **Call or Chat**
* Navigate to the **Analysis** tab
* Alongside:
* Transcript
* Node Logs
* Dynamic Variables
#### 👉 This helps you:
* Verify output
* Debug instructions
* Improve accuracy
# Speech Settings
Source: https://docs.sigmamind.ai/documentation/agents/settings/speech
Customize your AI agent’s voice, model, and background ambience.
The **Speech Settings** section allows you to control how your AI agent sounds and behaves during voice calls. These settings help create a more natural and controlled conversation experience.
## Available Settings
### 1. Background Sound
This setting lets you add ambient audio during a call to make conversations feel more realistic.
**Available Options:**
* **None (Default)**\
No background sound is played.
* **Office Ambient**\
Adds subtle office background noise (e.g., distant chatter, workspace sounds).
* **Keyboard Typing**\
Adds light typing sounds to simulate an active working environment.
**How to Configure:**
* Open your agent in the Agent Builder
* From the right-side panel, click on **Agent Settings**
* Go to **Speech Settings**
* Locate **Background Sound**
* Click the dropdown
* Select one of the available options
**When to Use What:**
* Use **None** → For clean, distraction-free conversations
* Use **Office Ambient** → To simulate a professional environment
* Use **Keyboard Typing** → To create a “live agent working” feel
***
### 2. Turn-Taking Responsiveness
Controls how quickly the AI starts speaking after the user finishes their input.
**Range:**
* **0 (Slower Response)** → Slight delay before the agent responds
* **1 (Instant Response)** → Agent responds immediately
**Default Value:**
* **1 (Fast response)**
**Behavior Guide:**
* Lower values → More natural pauses, less interruption risk
* Higher values → Faster replies, more responsive feel
***
### 3. Interruption Response
Controls how quickly the AI stops speaking when the user interrupts.
**Range:**
* **0 (Low Responsiveness)** → Agent continues speaking longer before stopping
* **1 (High Responsiveness)** → Agent stops immediately when interrupted
**Default Value:**
* **1 (Highly responsive)**
**Behavior Guide:**
* Lower values → Better for structured or scripted conversations
* Higher values → Better for dynamic, back-and-forth conversations
***
## Best Practices
* Use fast **Turn-Taking Responsiveness** for real-time conversational agents
* Reduce responsiveness slightly if conversations feel too abrupt
* Keep **Interruption Response** high for natural dialogue flow
* Lower interruption responsiveness for presentations or guided flows
* Use background sound sparingly to avoid distraction
# Transcription Settings
Source: https://docs.sigmamind.ai/documentation/agents/settings/transcription
Configure basic settings for your AI agents in SigmaMind.
Transcription settings manage how speech is converted into text for processing.
Correct transcription is essential for accurate intent recognition and smooth conversations.
# Transcription Settings
Source: https://docs.sigmamind.ai/documentation/agents/settings/transcription-settings
Transcription Settings control how audio is processed before it is converted into text.
These settings help improve:
* Speech clarity
* Transcription accuracy
* Call quality
## To configure Transcription Settings:
Open your **Agent Builder**.
From the side panel, click **Agent Settings**.
Expand the **Transcription Settings** section.
# Available Settings
## 1. Auto Volume Normalization
Automatically adjusts the speaker’s volume to keep it consistent.
### When to Use
* Callers speak too softly or too loudly
* Users move away from the microphone
* Mobile or real-world environments
### Recommendation
👉 Keep this **ON by default** for most use cases
***
## 2. Background Noise Filter
Reduces environmental noise such as:
* Fan or AC sounds
* Traffic noise
* Office background chatter
### When to Use
* Noisy environments
* Outdoor calls
* Call centers with background activity
### Recommendation
👉 Enable this if your users are not in a quiet environment
***
## 3. Echo Cancellation
Prevents the system’s audio from being picked up again by the microphone.
### When to Use
* Speakerphone or loudspeaker usage
* Open environments
* Cases where echo is noticeable
### Recommendation
👉 Keep this **ON**, especially for voice calls
***
# How to Choose the Right Settings
* **Quiet environment (office/home):**
* Noise Filter → Optional
* Echo Cancellation → ON
* Volume Normalization → ON
* **Noisy environment (call center/outdoor):**
* Noise Filter → ON
* Echo Cancellation → ON
* Volume Normalization → ON
***
# Why These Settings Matter
Poor audio quality can lead to:
* Incorrect transcription
* Misunderstood user intent
* Broken conversation flow
👉 These settings directly impact how well your agent understands users.
***
# Summary
* **Auto Volume Normalization** → Keeps audio levels consistent
* **Background Noise Filter** → Removes environmental noise
* **Echo Cancellation** → Prevents audio feedback
👉 Recommended setup: Keep all enabled unless you have a specific reason to disable them.
# Agent Webhook Settings
Source: https://docs.sigmamind.ai/documentation/agents/settings/webhook
Configure webhooks to receive real-time notifications from your AI agents in SigmaMind.
Webhooks allow SigmaMind to connect with external systems in real time.
Webhook integration extends the Agent’s functionality beyond SigmaMind, enabling automation across your tech stack.
# Setup your AI agent
Source: https://docs.sigmamind.ai/documentation/agents/setup-your-ai-agent
# How to Add tool
Source: https://docs.sigmamind.ai/documentation/agents/single-prompt-agent/add-tool-calls
Function calls allow the agent to perform real actions such as booking appointments or transferring calls. Without tools, your agent can only respond with words. With tools, it can **do things** — mid-conversation, in real time, without any human intervention.
Tools are added directly inside the **Agent Builder**. You can combine multiple tools in a single agent to handle complete workflows from start to finish.
## Supported Tools
SigmaMind supports five tool types across three categories:
### 🔊 Voice Tools
Control the call flow — where it goes and when it ends.
* **Transfer Call** — Route the active call to a human agent or phone number via warm or cold transfer
* **End Call** — Hang up and terminate the call cleanly once the conversation is complete
* **Navigate IVR** — Automatically handle IVR phone menus on outbound calls using keypad inputs or speech
### 📥 Extract Variables
* **Extract Dynamic Variables**— Capture values the customer provides during the call (names, IDs, dates) and store them as `{{variable_name}}` for use in any subsequent tool or prompt
### 🔗 Integration Tools
* **Add Integration Tool** — Connect to external apps and APIs mid-conversation to look up records, create bookings, update data, or trigger any action your connected integration supports
***
## How to Add a Tool
1. Open the **Agent Builder**
2. Click **+ Add Tool**
3. Select the tool type
4. Fill in the required fields
5. Click **Add to Agent**
Every tool has an **Instruction** field — a plain-language description of when the agent should trigger it. The agent reads this alongside the live conversation and acts when the condition is met.
# How to configure basic settings
Source: https://docs.sigmamind.ai/documentation/agents/single-prompt-agent/agent-settings
Basic Settings define how your AI agent **sounds, thinks, and communicates** during a call.
These are the **core configuration controls** that directly impact:
* Voice quality and experience
* Response speed and intelligence
* Language understanding and accuracy
* Overall conversation flow
👉 Incorrect setup here can lead to robotic voice, slow responses, or poor user experience.
## What You Configure Here
| Setting | What It Controls | Why It Matters |
| :--------------------------------------------------------------------------------------- | :------------------------ | :---------------------------------------- |
| [**Voice**](/documentation/agents/single-prompt-agent/how-to-select-voice-of-your-agent) | How the agent sounds | Affects user trust and engagement |
| **TTS Model** | Speech generation quality | Impacts realism and latency |
| [**LLM Model**](/documentation/agents/single-prompt-agent/how-to-select-llm-model) | Intelligence of responses | Controls speed, accuracy, and reasoning |
| [**Language**](/documentation/agents/single-prompt-agent/how-to-select-language) | Input/output language | Ensures correct understanding and replies |
| [**Who Speaks First**](/documentation/agents/single-prompt-agent/untitled-page) | Call start behavior | Defines conversation flow |
You can define:
* How your agent speaks (Voice)
* How your agent thinks (LLM Model)
* Which language it understands
* Who starts the conversation
## How to Configure
1. Open your agent in the **Agent Builder**
2. From the right-side panel, click on **Agent Settings**
3. In the **Basic Settings** section, configure Voice, LLM Model, Language, and conversation start preference
All changes are automatically saved. Review your settings before going live.
# Step 1: Write the main prompt
Source: https://docs.sigmamind.ai/documentation/agents/single-prompt-agent/configure-main-prompt
The **Main Prompt** defines how the agent behaves during the conversation. It controls the agent’s role, personality, tone, conversation flow, and how information should be collected.
This prompt acts as the brain of the agent and ensures consistent, professional, and goal-oriented interactions.
**Use the Main Prompt to:**
* Define the agent’s role and responsibilities
* Set tone and personality
* Guide conversation flow
* Define rules and restrictions
* Control how information is collected
* Ensure professional and consistent responses
**Example Prompt:**
```text theme={null}
You are a professional appointment booking assistant.
Your job is to:
1. Greet the customer politely.
2. Ask for their preferred date and time.
3. Collect their full name and phone number.
4. Confirm the appointment clearly.
Be concise, friendly, and professional.
If information is missing, ask follow-up questions.
```
### Using Variables
Variables allow the agent to collect and store structured information during the call.
Define variables using double curly braces:
```text theme={null}
{{customer_name}}
{{phone_number}}
{{appointment_date}}
{{appointment_time}}
```
**When the agent collects this information from the caller, these variables are automatically populated and can be used in workflows, function calls, or integrations.**
***
### Example Prompt
```text theme={null}
You are a professional and friendly appointment booking voice assistant for SigmaMind AI.
Your job is to:
1. Greet the customer politely
2. Ask for their preferred appointment date and store it as {{appointment_date}}
3. Ask for their preferred appointment time and store it as {{appointment_time}}
4. Ask for their full name and store it as {{customer_name}}
5. Ask for their phone number and store it as {{phone_number}}
6. Confirm the appointment clearly
Be concise, friendly, and professional.
If any information is missing, ask follow-up questions politely.
Always maintain a helpful and professional tone.
Do not mention internal system operations.
```
***
### Best Practices
Follow these best practices when writing your Main Prompt:
* Clearly define the agent’s role
* Use numbered steps to guide conversation flow
* Use variables to store important information
* Keep instructions clear and simple
* Define how the agent should handle missing information
* Set tone and communication style (friendly, professional, sales, etc.)
Avoid mentioning internal systems, tools, or function calls
### Recommended Prompt Structure
```text theme={null}
Identity:
You are a friendly AI assistant for ABC Clinic helping schedule appointments.
Style Guardrails:
- Be polite and conversational.
- Ask one question at a time.
- Keep responses short and clear.
Response Guidelines:
- Confirm important details.
- Ask for missing information when needed.
Task:
1. Greet the user.
2. Ask for their name.
wait for user response
3. Ask for preferred appointment date.
wait for user response
4. Confirm the appointment.
5. End the conversation politely.
```
A well-structured Main Prompt ensures predictable, reliable, and production-quality agent behavior.
# Step 2: Set First Message (optional)
Source: https://docs.sigmamind.ai/documentation/agents/single-prompt-agent/configure-welcome-message
The First Message is the first message the caller hears when the call connects. It sets the tone of the conversation and introduces the AI agent to the caller.
**SigmaMind** supports both **static and dynamic welcome messages**. In both of these, dynamic variables can be used to personalize the message for the user.
### Static Message
A Static Message is a fixed message that is played at the start of every call/ chat.
Use this when no personalization is required.
**Example:**
```text theme={null}
Hello, thank you for calling SigmaMind. How can I assist you today?
```
**You can also include variables in a static welcome message:**
```text theme={null}
Hello {{customer_name}}, thank you for calling SigmaMind. How can I assist you today?
```
***
### Dynamic Message
Dynamic message is rephrased by the LLM every time for a call/chat, so even though you may say "Hello, how can I help you?", the LLM will automatically rephrase that message every time for a new call or chat, thereby creating not a static but a refreshing new welcome message on every call or chat. You can also use dynamic variables to personalize this message.
Example:
```text theme={null}
Hello {{customer_name}}, thank you for calling SigmaMind. How can I help you today?
```
**How it works:**
SigmaMind injects variable values into the message before the LLM responds
The LLM uses these values as a conversation context
This allows the agent to provide personalized and relevant responses immediately
**These variables can be populated from:**
* CRM integrations
* Function calls
* Extracted conversation data
**The LLM receives the final message with actual values already filled in, allowing it to understand the caller’s context and respond intelligently.**
This improves personalization, accuracy, and overall conversation quality.
**`Variables must be defined using double curly braces: {{variable_name}}`**
# How to Select Language
Source: https://docs.sigmamind.ai/documentation/agents/single-prompt-agent/how-to-select-language
This setting defines the **primary language your AI agent will understand and speak** during calls.
### Where to Configure
**Agent Settings → Select Language.**
***
# Available Language Options
SigmaMind supports **multiple languages and regional variants**, including:
* English (US, UK, India, Australia, etc.)
* European languages (German, Dutch, Italian, Swedish, Danish, etc.)
* Indian languages (Hindi, etc.)
* Other global languages
👉 The full list is available in the dropdown inside the platform.
***
## Language Selection
| Scenario | What to Select | Why |
| :----------------------- | :-------------------------------------------- | :------------------------------------- |
| Single-language audience | Specific language (e.g., English – US, Hindi) | Best accuracy and pronunciation |
| Region-specific users | Regional variant (e.g., English – India) | Matches local accent |
| Mixed-language users | Multilingual | Handles multiple languages dynamically |
***
### Recommendation
👉 If your users speak **one language** → select that specific language\
👉 If users may switch languages → use **Multilingual**
***
### Quick Rule
👉 One language → **Select that language**\
👉 Multiple languages → **Use multilingual**
# How to select LLM Model
Source: https://docs.sigmamind.ai/documentation/agents/single-prompt-agent/how-to-select-llm-model
## Select LLM Model
SigmaMind provides multiple model options optimized for different use cases, allowing you to balance intelligence, speed, and cost based on your workflow requirements.
Navigate to:
**Agent Settings → Select LLM Model**\
\
**You can select models from the following providers:**
* OpenAI
* Google (Gemini)
* Anthropic (Claude)
#### Model Comparison
| Model | Latency (Speed) | Quality | Cost | Best Use Case |
| :---------------- | :-------------- | :-------- | :---------- | :-------------------------------- |
| GPT-4.1 Fast | Fast | High | Medium | General use, support agents |
| Gemini 2.5 Flash | Very Fast | High | Low | Voice agents, sales calls |
| Claude 3.5 Sonnet | Medium | Very High | Medium–High | Support, reasoning-heavy tasks |
| GPT-5 | Slow | Very High | High | Complex workflows, advanced logic |
### Quick Recommendation
* 👉 **Voice / Call agents** → Gemini 2.5 Flash
* 👉 **General / Support** → GPT-4.1 Fast
* 👉 **Complex logic** → Claude 3.5 Sonnet or GPT-5
Each provider offers models optimized for different levels of intelligence and performance.
# How to select voice of your agent
Source: https://docs.sigmamind.ai/documentation/agents/single-prompt-agent/how-to-select-voice-of-your-agent
Voice is one of the **most important configuration decisions** for your AI agent.
It directly impacts:
* User experience
* Trust and engagement
* Perceived intelligence of the agent
👉 A poor voice choice can make even a well-designed agent feel robotic.
***
# Available Voice Providers
You can choose voices from multiple providers:
* **ElevenLabs**
* **OpenAI**
* **Cartesia**
* **Rime AI**
* **Hume AI**
***
### How These Providers Differ (Important)
| Provider | Best For | Notes |
| :--------------------- | :--------------------------- | :------------------------------ |
| ElevenLabs | Production, realism | Most natural sounding |
| OpenAI | Balanced use cases | Good quality + performance |
| Cartesia / Rime / Hume | Experimental / varied styles | Different tones & personalities |
### How to Choose the Right Voice
### Based on Use Case
| Use Case | Recommended Voice |
| :--------------- | :------------------ |
| Customer support | Neutral, clear |
| Sales calls | Confident, engaging |
| India users | Indian accent |
| Global users | Neutral / American |
***
### Based on Audience
* Older users → slower, clearer voice
* Younger users → slightly energetic
* Noisy environments → very clear pronunciation
***
### Explore Voices
Use **keywords** and **filters to shortlist voices**, then prioritize those that align with your **users**’ **geography,** **accent expectations**, and **listening environment.**
***
#### Preview (Critical Step)
Before selecting:
* Play the sample
* Check pronunciation
* Test real phrases
### How to add Custom Voices:
1. Go to ElevenLabs dashboard
2. Select or create a voice
3. Copy the **Voice ID**
4. Go to **SigmaMind → Voice Settings**
5. Click on **Add Custom Voice**
6. Paste into **Custom Voice**
7. Click **Submit**
***
# How to Configure Who starts the conversation
Source: https://docs.sigmamind.ai/documentation/agents/single-prompt-agent/untitled-page
This setting controls who starts the conversation when the call connects.
### Who Speaks First - Decision Table
| Scenario | Setting to Choose | Why | What Happens |
| :----------------------------- | :------------------------ | :---------------------- | :---------------------------------------- |
| Outbound calls (you call user) | **AI starts first** | AI initiates the call | AI speaks immediately after call connects |
| Automated workflows | **AI starts first** | No user input expected | AI drives the conversation |
| Inbound calls (user calls you) | **Customer starts first** | Natural user behavior | AI waits, then responds |
| Support helpline | **Customer starts first** | Matches real-world flow | Avoids interrupting user |
See where to 👉 [Set First Message](/documentation/agents/single-prompt-agent/configure-welcome-message) in Single Prompt Agent. The **first message spoken by AI.**
#### Recommendation (Important)
👉 Inbound calls → **Customer starts first**\
👉 Outbound calls → **AI starts first**
***
### Why This Matters
Wrong configuration can lead to:
* AI talking over the user
* Awkward silence at call start
* Confusing conversation flow
***
## What Actually Happens
* **AI starts first** → Agent speaks immediately after connection
* **Customer starts first** → Call stays silent until the user speaks
# Test
Source: https://docs.sigmamind.ai/documentation/agents/test1
Add image, video, and other HTML elements
# Building Conversational AI Agent Flows with SigmaMind AI
The SigmaMind AI platform provides an AI agent builder studio that allows users to design custom conversational AI agents by connecting various modules.
## 1. Configure the Start Trigger
The "Start Trigger" is the initial component that determines how your AI agent flow is activated.
* **Default Trigger**: When you add a new AI agent, the "Start Trigger" is included by default.
* **Select Trigger Event**: You can choose different trigger events based on the communication channel:
* **Voice Agents**: Select `voice call started`.
* **Text-based Channels (Chat, Email, SMS)**: Select `ticket saved created event` for inbound requests.
* **Multiple Triggers**: You can add more than one trigger event if you want the same flow to work across multiple channels, such as voice, chat, and email.
* **Filter by Intent**: To make the agent trigger only for specific customer requests, you can filter by intent. For example, if you select "schedule an appointment" as an intent, the AI agent will only activate when an inbound request is about scheduling an appointment. Otherwise, the flow won't trigger, and the request might be handled by a human agent or another setup. You can also specify multiple intents.
## 2. Define Send Responses
The "Send Response" module allows your AI agent to communicate with the customer.
* **Drag and Drop**: You can drag and drop this module into your flow.
* **Response Types**:
* **Prompt**: You can provide a direct prompt as a response, breaking your flow into smaller conversational segments, such as greeting a customer.
* **Templates/Macros**: If you have pre-built templates or macros, you can select the `static category` to use them as responses.
* **Channel-Specific Responses**: You can customize responses based on the channel. For instance, a phone voice conversation might have a different prompt than an email, by selecting the appropriate channel within the module.
## 3. Implement Wait Conditions
The "Wait" module enables the AI agent to pause and wait for customer input or an intentional delay.
* **Drag and Drop**: Add this module to your flow by dragging and dropping it.
* **Event-Based Waiting**: You can set an event for which the agent should wait. For example, selecting `ticket message created customer` will make the agent wait for a customer's reply in the conversation flow. This is crucial for back-and-forth conversations, such as after an agent greets a caller and expects a response.
* **Conditions**: You can add specific conditions for each waiting event.
* **Intentional Delay**: You can set a delay, such as a 24-hour or 8-hour window, if you need to wait for a customer message within a specific timeframe. This helps set up conversational automation.
## 4. Detect User Intent
The "User Intent" module helps the AI agent understand what the customer is saying.
* **Mini-Prompts**: This module is essentially a mini-prompt designed to detect the customer's intent.
* **If-Then-Else Conditions**: You can set up one or multiple "if-then-else" conditions. For example, if the customer's message is about "canceling an order," the flow can be directed to a specific app action or a different response. This allows you to break down the conversation into multiple prompts based on detected customer intent.
## 5. Integrate with Third-Party Systems via App Actions
The "App Action" module is where all third-party API integrations come into play, allowing the AI agent to retrieve information or take actions in external systems.
* **API Integrations**: If you have set up API integrations (e.g., with Shopify or a CRM system), they will appear in a dropdown.
* **Available Requests**: The dropdown will show all available API requests for the selected application, such as a `get order request` for Shopify or fetching/posting customer info in a CRM.
* **Retrieve Information/Take Action**: This module allows you to retrieve specific information (e.g., order details) or take actions (e.g., posting info) related to a customer.
### Adding and Managing Apps
Before using "App Actions," you need to set up your integrations in the "Apps" section.
* **Add Applications**: Go to the "Apps" section to add all your third-party integrations.
* **Define API Actions**: For each integrated app, you can add specific API actions (e.g., `get request` for retrieving order info from Shopify).
* **Configure Variables and API Keys**: Within this section, you can set up variables and add API keys for your integrations.
## 6. Create Conditional Paths with Branching
The "Branch" module enables you to add pre-validations and multiple conditions to guide the conversation flow.
* **Multiple Conditions**: You can think of "Branch" as a way to perform checks before deciding the direction of the conversation.
* **AND/OR Conditions**: You can combine multiple conditions using "and" or "or" logic.
* **Integration Fields**: This module pulls fields directly from your API integrations (e.g., "Shopify order status"). You can then select different conditions based on these fields.
* **Connecting Modules**: Based on these pre-validations, you can connect the "Branch" module to various other modules, allowing for dynamic conversation paths.
## 7. Design an Overall Flow (Example: Looping Responses)
Modules can be arranged and connected to create complex conversational flows. A common pattern involves looping responses back to the "Wait" module to continue the conversation.
* **Example: Cancel Order Request**:
1. The customer places a cancel order request.
2. "User Intent" messages detect the request, and "App Actions" retrieve specific order information (e.g., looking up email ID or phone number).
3. After the AI agent responds (e.g., offering a 30% discount instead of cancellation), the flow can **loop back** to the "Wait" module.
4. This forces the agent to wait for the customer's response to the AI's offer, allowing for a continuous conversation. You can have multiple such loops.
## 8. Test Your AI Flow in the Playground
Once you have built your AI flow, you can test it directly within the SigmaMind AI platform.
* **Access Playground**: Navigate to the "Playground" section from the menu.
* **Simulate Input**: You can simulate an inbound request by adding a subject, a random email ID, selecting a channel from a list, and typing a message, then hitting submit.
* **View Events**: The playground will show if your AI agent's triggers are met and if the flow is activated. You can then view the events and steps to verify that everything happened as expected.
```
```
# Connect Agent for Inbound Calls
Source: https://docs.sigmamind.ai/documentation/agents/voice/inbound
# Connect Agent for Outbound Calls
Source: https://docs.sigmamind.ai/documentation/agents/voice/outbound
# Webhook Logs
Source: https://docs.sigmamind.ai/documentation/agents/webhook-logs
The Webhook Logs page helps monitor and debug all webhook activity triggered from the platform. It provides visibility into request status, execution time, and delivery performance.
## How to Navigate
1. Go to the Home Dashboard.
2. From the left side panel, click on **Logs**.
3. Select the **Webhooks** tab at the top of the page.
## Key Insights
* Track all outgoing webhook requests in real time.
* View request execution details such as:
* Request ID
* Action name
* HTTP method
* Duration
* Response status
* Quickly identify failed or delayed webhook calls.
* Filter logs using date range and timezone for easier troubleshooting.
## Common Use Cases
* Verify whether a webhook was successfully delivered.
* Debug integration issues with external services.
* Monitor webhook response times and reliability.
* Audit historical webhook activity.
## Status Indicators
* **200** → Request completed successfully.
* Failed or non-200 responses indicate delivery or integration issues requiring attention.
# API Logs
Source: https://docs.sigmamind.ai/documentation/api-keys/api-logs
The API Logs page provides a detailed history of all API requests made within the platform. It helps monitor API activity, track request performance, and identify failed requests.
## How to Navigate
1. Go to the Home Dashboard.
2. From the left side panel, click on **Logs**.
3. Open the **API** tab at the top of the page.
## Key Insights
* View all API request activities in one place.
* Track:
* Request ID
* Action name
* HTTP method
* Response status
* Request duration
* Identify successful and failed API requests quickly.
* Use date range and timezone filters for easier analysis.
## Status Indicators
* **200** → Request completed successfully.
* **400** → Bad request or invalid input.
* Other non-200 responses indicate API or configuration issues.
***
# Create API Keys
Source: https://docs.sigmamind.ai/documentation/api-keys/overview
API Keys allow you to create and manage secure authentication credentials required to access **SigmaMind APIs** and configure webhooks.
These keys are used to authorize external applications, automation tools, and integrations securely.
***
## View API Keys
1. Log in to your **SigmaMind AI** dashboard.
2. From the left navigation panel, click **API Keys** under the **Deploy** section.
You will see a list of existing API keys with:
* **Key ID**
* **Name**
* **Status**
* **Secret Key (masked)**
* **Created Date**
**Important:** For security reasons, the full secret key is only shown once at the time of creation.\
After you close the creation modal or leave the page, the secret key cannot be viewed again.
If you lose the secret key, you must:
1. Delete the existing key.
2. Create a new API key.
3. Update your integrations with the new key.
***
# Create an API Key
Follow these steps to generate a new API key:
1. Go to **API Keys** from the left navigation panel.
2. Click **+ Create API Key** in the top-right corner.
3. Enter a **descriptive name** to identify its purpose (e.g., "Webhook Integration" or "Production App").
4. Click **Create**.
Copy and securely store the secret key immediately after it is generated.\
For security reasons, the full secret key will not be visible again.
***
# Delete an API Key
If you no longer need an API key, you can delete it:
1. Go to **API Keys** from the left navigation panel.
2. Click the **three-dot (⋯) menu** next to the API key.
3. Select **Delete**.
4. Confirm the deletion.
Once deleted, the API key cannot be recovered. Any connected application, automation, or webhook using this key will stop working immediately.
***
# Best Practices
To maintain security and stability:
* 🔒 Never share your secret key publicly.
* 🔁 Rotate keys periodically for production systems.
* 🧪 Use separate keys for development and production environments.
* ❌ Delete unused or compromised keys immediately.
***
# When to Use API Keys
Use API Keys when:
* Connecting external applications to SigmaMind AI
* Setting up webhook integrations
* Automating workflows using third-party tools (e.g., Zapier, Make, etc.)
* Making authenticated API calls to SigmaMind services
# Make Calls
Source: https://docs.sigmamind.ai/documentation/calls/make-calls
SigmaMind AI lets you trigger outbound phone calls either through the **Dashboard UI** or programmatically via the `POST /v1/calls` API endpoint. Your AI agent handles the conversation end-to-end — no human needed on your side.
Before you start, make sure you have:
* A configured agent
* A phone number provisioned or imported on your account
* Your SigmaMind API key (`X-API-Key`) *(for API usage)*
***
## Step 1: Get a Phone Number
You need a caller number before placing any outbound call. SigmaMind supports two options:
| Option | UI Path | API Endpoint | When to Use |
| -------------------------- | ------------------------------------------------------ | ------------------------------- | ---------------------------------------------------------- |
| **Provision a new number** | Deploy → Phone Numbers → **Add Phone Number** | `POST /v1/phone-numbers` | Buy a SigmaMind-managed number directly |
| **Import your own (BYO)** | Deploy → Phone Numbers → **Add Phone Number** → Import | `POST /v1/phone-numbers/import` | Bring a number via SIP trunking from your telecom provider |
### Via the Dashboard
1. In the left sidebar, go to **Deploy → Phone Numbers**.
2. Click **Add Phone Number**.
3. Choose to provision a new number or import an existing one via SIP trunking.
4. Once added, the number appears in your list with its active status, provider (e.g. Twilio), and assigned agent.
To configure a number after adding it, click it in the list. You'll see:
* **Phone Number Name** — a friendly label (e.g. "Debt Collection Inbound")
* **Inbound Call Setting** — assign an Inbound AI Agent and optionally an Inbound Webhook URL
* **Outbound Call Setting** — assign an Outbound AI Agent and set the outbound phone number
### Via the API
To see all numbers already on your account:
```bash theme={null}
GET https://api.sigmamind.ai/v1/phone-numbers
X-API-Key:
```
Each number returned includes its assigned agent, active status, provider, and SIP configuration.
***
## Step 2: Create an Outbound Call
### Via the Dashboard
1. Go to **Deploy → Phone Numbers** and select the phone number you want to call from.
2. Scroll to the **Outbound Call Setting** section.
3. Set the **Outbound Phone Number** (the number that will appear as the caller ID).
4. Select an **Outbound AI Agent** from the dropdown — this agent will handle the call conversation.
5. Click the **Call** button at the bottom of the panel to initiate an outbound call immediately.
Make sure an Outbound AI Agent is selected before clicking Call. If no agent is assigned, the call will not be initiated.
### Via the API
Use `POST /v1/calls` to initiate a call. The agent you pass (or the one pre-assigned to the number) will handle the conversation.
#### Required Parameters
| Parameter | Type | Description |
| ----------------- | -------------- | ------------------------------------------------ |
| `fromPhoneNumber` | string (E.164) | Your SigmaMind number, e.g. `+14157774444` |
| `toPhoneNumber` | string (E.164) | The number you want to call, e.g. `+12137774445` |
#### Optional Parameters
| Parameter | Type | Description |
| ------------------ | ------ | ---------------------------------------------------------------------------------------------------- |
| `agentId` | string | Override which agent handles this call. If omitted, uses the agent assigned to the `fromPhoneNumber` |
| `dynamicVariables` | object | Key-value pairs injected into your agent's prompt at runtime, e.g. customer name, account ID |
#### Example Request
```bash cURL theme={null}
curl -X POST https://api.sigmamind.ai/v1/calls \
-H "X-API-Key: " \
-H "Content-Type: application/json" \
-d '{
"fromPhoneNumber": "+14157774444",
"toPhoneNumber": "+12137774445",
"agentId": "agent_abc123",
"dynamicVariables": {
"customer_name": "John Doe",
"plan_type": "Premium"
}
}'
```
```javascript Node.js theme={null}
const response = await fetch("https://api.sigmamind.ai/v1/calls", {
method: "POST",
headers: {
"X-API-Key": "",
"Content-Type": "application/json",
},
body: JSON.stringify({
fromPhoneNumber: "+14157774444",
toPhoneNumber: "+12137774445",
agentId: "agent_abc123",
dynamicVariables: {
customer_name: "John Doe",
plan_type: "Premium",
},
}),
});
const call = await response.json();
console.log(call.callId); // save this for monitoring
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.sigmamind.ai/v1/calls",
headers={
"X-API-Key": "",
"Content-Type": "application/json",
},
json={
"fromPhoneNumber": "+14157774444",
"toPhoneNumber": "+12137774445",
"agentId": "agent_abc123",
"dynamicVariables": {
"customer_name": "John Doe",
"plan_type": "Premium",
},
},
)
call = response.json()
print(call["callId"]) # save this for monitoring
```
The response includes a `callId` — keep this to retrieve call details later.
Use `dynamicVariables` to personalise each call without creating separate agents. Any variable you pass is available inside your agent's prompt at call time.
***
## Step 3: Run a Campaign (High-Volume Outbound)
For bulk outbound — sales blasts, reminders, surveys — use **Campaigns** instead of triggering individual calls.
### How Campaigns Work
You upload a CSV of contacts, attach an agent and a caller number, and SigmaMind dials through the list automatically with configurable concurrency.
### Via the Dashboard
1. In the left sidebar, go to **Deploy → Campaign Calls**.
2. Click **Create Campaign**.
3. Fill in the campaign details:
* **Campaign Name** — a human-readable label for this campaign
* **Agent** — select the AI agent that will handle all calls
* **Phone Number** — select the caller number (must already be added under Phone Numbers)
* **Contacts CSV** — upload a CSV file containing your contact list
* **Concurrent Calls** — set how many calls to run in parallel
* **Dynamic Variables** *(optional)* — add key-value pairs applied to every call in the campaign
4. To schedule the campaign for a later time, toggle **Schedule Campaign** and fill in:
* **Date** — e.g. `2025-09-01`
* **Time** — e.g. `09:00`
* **Timezone** — e.g. `America/New_York`
5. Click **Launch Campaign** to start immediately, or **Save** to confirm a scheduled campaign.
Once created, your campaign appears in the Campaign Calls list with its status (`Active`, `Scheduled`, `Completed`, or `Paused`). Click a campaign to view progress, pause/resume it, or delete it.
Your CSV must include at minimum a column for the destination phone number in E.164 format (e.g. `+12137774445`). Additional columns can be used as dynamic variables in your agent's prompt.
### Via the API
#### Create a Campaign
```bash theme={null}
POST https://api.sigmamind.ai/v1/campaigns
```
| Parameter | Type | Required | Description |
| ------------------- | ------- | -------- | ----------------------------------------------------- |
| `campaignName` | string | ✅ | A human-readable name for this campaign |
| `agentId` | string | ✅ | The agent that will handle all calls in this campaign |
| `sipPhoneNumber` | string | ✅ | The caller number (E.164) |
| `file` | string | ✅ | CSV file with contact list |
| `concurrentCalls` | integer | — | How many calls to run in parallel |
| `dynamicVariables` | object | — | Variables applied to every call in the campaign |
| `isScheduled` | boolean | — | Set `true` to schedule for a future time |
| `scheduledDate` | string | — | Date to launch, e.g. `2025-09-01` |
| `scheduledTime` | string | — | Time to launch, e.g. `09:00` |
| `scheduledTimezone` | string | — | Timezone, e.g. `America/New_York` |
#### Example — Immediate Campaign
```bash theme={null}
curl -X POST https://api.sigmamind.ai/v1/campaigns \
-H "X-API-Key: " \
-H "Content-Type: application/json" \
-d '{
"campaignName": "September Follow-ups",
"agentId": "agent_abc123",
"sipPhoneNumber": "+14157774444",
"file": "",
"concurrentCalls": 5
}'
```
#### Example — Scheduled Campaign
```bash theme={null}
curl -X POST https://api.sigmamind.ai/v1/campaigns \
-H "X-API-Key: " \
-H "Content-Type: application/json" \
-d '{
"campaignName": "Morning Reminders",
"agentId": "agent_abc123",
"sipPhoneNumber": "+14157774444",
"file": "",
"concurrentCalls": 3,
"isScheduled": true,
"scheduledDate": "2025-09-01",
"scheduledTime": "09:00",
"scheduledTimezone": "America/New_York"
}'
```
The response includes a `campaignId` you can use to check status, update, or delete the campaign.
***
## Step 4: Monitor Calls
### Via the Dashboard
* **Conversations** — Go to **Observe → Conversations** in the sidebar to see a live and historical list of all calls. Click any call to view its transcript, duration, assigned agent, and status.
* **Analytics** — Go to **Observe → Analytics** to see aggregate metrics across all calls — total call volume, average duration, completion rates, and more.
* **Logs** — Go to **System → Logs** for a detailed technical log of call events, errors, and webhook deliveries.
* **Campaign Calls** — Go to **Deploy → Campaign Calls**, click a campaign, and view per-contact call status in real time as the campaign dials through your list.
### Via the API
#### Retrieve a Single Call
```bash theme={null}
GET https://api.sigmamind.ai/v1/calls/{callId}
X-API-Key:
```
Returns: call status, direction, assigned agent, phone numbers, duration, and transcript metadata.
#### List All Calls
```bash theme={null}
GET https://api.sigmamind.ai/v1/calls?status=completed&page=1&size=20
X-API-Key:
```
Filter by `status` to narrow results. Paginate with `page` and `size`.
#### Set Up Webhooks (Recommended)
Rather than polling, register a webhook to receive real-time push notifications when call events happen.
**Via the Dashboard:** Go to **System → Webhooks** (or configure the Inbound Webhook URL directly on a phone number under Deploy → Phone Numbers) to add and manage webhooks without writing any code.
**Via the API:**
```bash theme={null}
POST https://api.sigmamind.ai/v1/webhooks
```
You can scope webhooks to a specific agent using `agentId`, and list or toggle them via `GET /v1/webhooks`.
Webhooks are the recommended approach for production systems — they eliminate polling overhead and give you instant event delivery.
#### Delete a Call Record
If you need to remove a call record from your account:
```bash theme={null}
DELETE https://api.sigmamind.ai/v1/calls/{callId}
X-API-Key:
```
Returns `204 No Content` on success. This action cannot be undone.
***
## Quick Reference
### Dashboard Navigation
| Task | Where to go |
| ------------------------------- | ------------------------------------------------------------------------- |
| Add or manage phone numbers | Deploy → Phone Numbers |
| Make a single outbound call | Deploy → Phone Numbers → select number → Outbound Call Setting → **Call** |
| Create or manage campaigns | Deploy → Campaign Calls |
| View call transcripts & history | Observe → Conversations |
| View call analytics | Observe → Analytics |
| View system logs | System → Logs |
| Manage API keys | Deploy → API Keys |
### API Endpoints
| Task | Method | Endpoint |
| ------------------------------- | -------- | ---------------------------- |
| Initiate a single outbound call | `POST` | `/v1/calls` |
| Get call details | `GET` | `/v1/calls/{callId}` |
| List all calls | `GET` | `/v1/calls` |
| Delete a call record | `DELETE` | `/v1/calls/{callId}` |
| Create a bulk campaign | `POST` | `/v1/campaigns` |
| Get campaign status | `GET` | `/v1/campaigns/{campaignId}` |
| Register a webhook | `POST` | `/v1/webhooks` |
| List phone numbers | `GET` | `/v1/phone-numbers` |
| Provision a number | `POST` | `/v1/phone-numbers` |
| Import a number (BYO) | `POST` | `/v1/phone-numbers/import` |
# Receive Calls
Source: https://docs.sigmamind.ai/documentation/calls/receive-calls
Different agents often need to share the same phone number, and Inbound calls frequently require context based on who's calling. For outbound calls and chats, you can easily provide this call-specific information through the API when initiating contact. However, inbound calls are initiated by others, so you need a mechanism to receive notifications when they arrive and process them accordingly. For this we have Inbound webhook which serves this exact purpose. Once configured, it allows you to customize the agent ID and set dynamic variables. This webhook is configured as part of your phone number settings and works with both purchased and imported numbers. When the webhook response is not received yet, the call will stay in ringing state.
## Use cases
* Add context (dynamic variables) to inbound calls.
* Override the agent id.
* Inbound call system records.
## Dashboard
You can set the inbound call webhook url from the **SigmaMind Dashboard**. Head over to the **Phone Numbers** section, and under **Inbound Call Settings** you will see the option to set the **Inbound Webhook URL.**
## Webhook specifications
The webhook sends a `POST` request to your endpoint and waits up to 10 seconds for a response. If no successful response is returned within that period, the system will retry the request up to 3 additional times. If a successfull response is not received after 3 retrials then the call will not be connected to the agent.
## Request payload
The payload will include the following fields :
* `event`: the event which triggered the webhook ("inbound\_call" in this case).
* `agent_id`: appears when an inbound agent ID is configured for the number.
* `from_number`: identifies the caller so you can process the call or SMS appropriately.
* `to_number`: identifies the recipient so you can process the call or SMS appropriately.
```json theme={null}
{
"event": "inbound_call",
"agent_id":"shvb5xs5fo2D2222",
"from_number": "+12345678912",
"to_number": "+12345678913"
}
```
## Response
Your endpoint should return a JSON response with a 2xx status code, containing upto 2 optional fields. The following fields are available:
* `dynamic_variables`: use this to define dynamic variables specific to this inbound call.
* `override_agent_id`: if you want to override the agent id, you can set it here.
Here’s a sample response for inbound call:
```json theme={null}
{
"dynamic_variables": {
"first_name": "Jim",
"last_name": "Smith"
},
"override_agent_id":"shvb5xs5fo2D2225"
}
```
## FAQ
The call would remain in a ringing state.
The webhook waits up to 10 seconds for a response. If no successful response is returned within that period, the system will retry the request up to 3 additional times. If a successfull response is not received after 3 retrials then the call will not be connected to the agent and it will be disconnected. During this timeperiod the call will remain in a ringing state.
Once successfull response is received the call gets connected to the agent.
Then the webhook will not be triggered and the call will get directly connected to the agent.
Then the call will remain in ringing state and its not connected to the agent.
First, clear the default "Inbound AI Agent" in the "Inbound Call Setting" under "Phone Numbers" in the Sigmamind Dashboard. Then, in your webhook response, set `override_agent_id` to null for calls you wish to reject. Such calls will remain in ringing state and will not get connected to the agent.
# Create a Campaign
Source: https://docs.sigmamind.ai/documentation/campaigns/create-campaign-calls
Step-by-step guide to create and configure outbound call campaigns in SigmaMind.
Use this process to set up and launch a call campaign through **SigmaMind**.
Campaigns can be created via the **Dashboard** or **API**.
## Dashboard
***
### Step 1: Navigate & Initiate
* Go to the **Campaign Calls** section in your SigmaMind dashboard.
* Click **Create New Campaign**.\\
### Step 2: Configure Campaign Name and Phone Number
* Enter a **Campaign Name** to help identify the campaign later.
* Select or enter the **Phone Number** you want as the caller ID.
* The number must already be purchased and bound in your system.
### Step 3: Assign an Outbound Agent
* Add the `agentId` of the outbound agent that should run this campaign.
* This ensures calls run within the context of the selected agent.
### Step 4: Upload a File
* Prepare a **CSV file** with a header row:
* Minimum required column: Phone Number.
* Additional columns (e.g., `First Name`, `City`) can be used as template variables like `{{first_name}}`.
```csv theme={null}
Phone Number,First Name,City
+14150000001,Alex,New York
+14150000002,Maria,San Francisco
```
Use the provided CSV template for consistency, or upload your own with custom headers.
### Step 5: Choose When to Send
* **Send Now**: Start the campaign immediately.
* **Schedule for Later**:
* Define scheduledDate and scheduledTime.
* Provide a scheduledTimezone to ensure accurate scheduling.
### Step 6: Limit Concurrent Calls
* Set the concurrentCalls parameter (1–20).
* Controls how many calls run simultaneously.
Use lower concurrency for testing or sensitive campaigns. Use higher concurrency for large-scale campaigns.
## API
If you prefer programmatic control, you can use our APIs.\
Refer to the [Create Campaign API Reference](/api-reference/campaigns/create-campaign) for details on all available parameters.
* The CSV file must be uploaded as `multipart/form-data`.
* The `file` parameter should contain the path to your CSV file.
* The `concurrentCalls` parameter controls how many calls run simultaneously (1-20).
* The `isScheduled` parameter determines if the campaign starts immediately or at a scheduled time.
* If scheduling, provide `scheduledDate`, `scheduledTime`, and `scheduledTimezone`.
* Ensure the `sipPhoneNumber` is a valid number in your SigmaMind account.
* The `agentId` must correspond to an existing outbound agent in your system.
```sh Create Campaign theme={null}
curl --location 'https://api.sigmamind.ai/v1/campaigns' \
--header 'X-API-KEY: key_C6HL3Goru7Q.TlI5kZOKPmDM03Gt39nRBEnx************************' \
--form 'campaignName="New Campaign"' \
--form 'sipPhoneNumber="+14150000001"' \
--form 'agentId="D5D0p7TUs66TTAEA"' \
--form 'file=@"/Users/ambujaak/Desktop/work/NOTES/Sample/local/campaign_appointment_booking.csv"' \
--form 'isScheduled="false"' \
--form 'scheduledDate=""' \
--form 'scheduledTime=""' \
--form 'scheduledTimezone=""' \
--form 'concurrentCalls="2"'
```
# Monitor Campaign Calls
Source: https://docs.sigmamind.ai/documentation/campaigns/monitor-campaign-calls
Learn how to track, manage, and review the progress of outbound call campaigns in SigmaMind.
After creating a campaign, you can track its progress and results in real-time from the **Campaigns for Outbound Calls** dashboard.
This section provides live updates and final statistics for every campaign.
***
## Step 1: Campaign Status
Each campaign displays a **Status badge** showing its current state:
* **scheduled** – A start date and time are set. The campaign will begin automatically.
* **in\_progress** – Calls are actively being placed according to concurrency.
* **completed** – All calls have finished and the campaign is closed.
***
## Step 2: Key Metrics on the Dashboard
For every campaign, the dashboard displays:
* **Total Calls** – Number of outbound calls in the campaign.
* **Campaign Name** - Name of the campaign
* **# Completed** – Calls that reached a final outcome.
* **# Picked** – Calls successfully answered by recipients.
* **# Voicemail** – Calls that ended in voicemail/answering machine.
* **Outbound Phone Number (sipPhoneNumber)** – The SIP caller ID used.
* **Last Modified** - Date and time of the last update
These figures **update in real time** as calls progress.
***
## Step 3: Open Detailed Campaign View
Click a **Campaign Name** to open detailed call records, including:
* Recipient’s number
* Start and end timestamps
* Call outcome (`answered`, `voicemail`, `failed`, etc.)
* Termination reason
* Call duration
### Viewing a Call in Detail
Click any **Call ID** to open a side panel with full details of that call, including:
* **Call date, time, and duration**
* **From / To numbers** – Agent's outbound number and recipient's number
* **Recording** – Download or playback the call audio
The panel has 5 tabs for deeper inspection:
| Tab | What you'll find |
| :-------------------- | :------------------------------------------------------------------------ |
| **Transcript** | Full conversation between the AI agent and the recipient, with timestamps |
| **Node Logs** | Step-by-step flow of nodes the agent executed during the call |
| **Dynamic Variables** | Variables used or updated during the call |
| **Analysis** | Call performance summary and insights |
| **System Logs** | Technical logs including STT, LLM, and TTS latency per message |
## Example Use Cases
* Marketing managers tracking conversion campaigns.
* Customer service teams monitoring service update campaigns.
* Healthcare organizations verifying appointment reminders.
# Campaigns Overview
Source: https://docs.sigmamind.ai/documentation/campaigns/overview
Learn how SigmaMind Campaign Calls work and when to use them.
With **SigmaMind**, you can launch call campaigns that place multiple outbound calls at once — no need to dial each number manually.
This makes it easy to create, schedule, and track multiple calls in one go—saving time and effort.
***
## Why Use Campaign Calls?
Campaigns are ideal for scenarios where you need to quickly reach many people, such as:
* **Marketing campaigns**
* **Appointment reminders**
* **Service updates**
* **Emergency notifications**
***
## Key Features
* **Bulk calling**: Upload customer lists via CSV.
* **Flexible scheduling**: Launch campaigns immediately or schedule them for later.
* **Agent assignment**: Choose which outbound agent executes the campaign.
* **Concurrency control**: Limit simultaneous calls between `1` and `20`.
* **Personalization**: Use variables (like `{{first_name}}`) from your CSV for dynamic conversations.
Campaigns can be created via both **Dashboard** and **API**.
# Create Your First AI Agent
Source: https://docs.sigmamind.ai/documentation/getting-started/create-first-ai-agent
Get started with SigmaMind AI — a complete platform for building, testing, and deploying conversational AI agents.
## Setup Your First AI Agent from Dashboard
Create a new AI Agent with a global prompt that defines its behavior.
You can create an agent directly from the **Dashboard**.
1. Navigate to **AI Agents** in the left sidebar.
2. Click **Create Agent**.
3. Add a **name** and (optionally) a description.
4. Configure the **global prompt** — this defines how your agent behaves.
```txt theme={null}
Example Prompt:
You are a friendly AI support assistant. Greet the caller politely, answer their questions,
and keep responses concise and natural.
```
5. Save and Publish the agent.
At this point, your agent is ready to be connected to a phone number.
# Introduction
Source: https://docs.sigmamind.ai/documentation/getting-started/introduction
Get started with SigmaMind AI - a production-grade Voice AI platform for developers and enterprises.
SigmaMind AI is a Voice AI platform built for developers and enterprise teams to design, test, and deploy production-ready voice agents that handle real conversations, integrate with systems, and execute actions reliably.
Whether you are designing a simple single-prompt voice agent or a complex multi-node workflow, SigmaMind provides everything you need to create enterprise-ready voice AI agents with full control and visibility.
Deploy your first AI agent in minutes with our step-by-step quick start guide.
Explore pre-built templates to quickly create AI agents for various use cases.
Configure and manage third-party integrations and APIs that your agents can use during conversations.
Test and simulate your AI agents in real time to validate responses, logic, and integrations before deployment.
Manage and configure phone numbers used to connect voice calls with your AI agents.
Generate and manage API keys to securely authenticate and integrate SigmaMind with external systems.
## What You Can Do with SigmaMind
**SigmaMind** is designed to cover the **entire lifecycle of AI agents**:
* **Build** – Define agent behavior with single-prompt logic and structured configuration so it works consistently in production.
* **Test** – Use the Playground to simulate conversations across voice, chat, and email channels.
* **Deploy** – Connect your agents to phone numbers, apps, and external platforms for live interactions.
***
## Key Capabilities
**SigmaMind** provides a complete solution with the following features:
* **Inbound & Outbound Calls** – Handle customer calls in both directions using AI.
* **Web Calls via Playground** – Simulate and test real-time conversations in a controlled environment.
* **Bring Your Own Number (BYO)** – Integrate phone numbers from providers like Twilio, Vonage, or Telnyx through SIP.
* **App Actions** – Extend agent capabilities by connecting with third-party apps and services.
* **Agent Types** – Build agents with:
* **Single-Prompt Logic** for quick responses.
* **Multi-Prompt Workflows** for structured conversations.
* **Playground** – Test, debug, and analyze conversations before production.
* **Conversation Analysis** – Capture insights, outcomes, and transcripts for every call.
* **Helpdesk Integration** – Seamlessly connect agents to existing customer support systems.
* **Webhooks** – Receive real-time notifications of conversation events.
* **Customizable Settings** – Control voice, speech, models, transcription, and call behavior.
SigmaMind empowers businesses to build AI-driven communication workflows that feel human, scale effortlessly, and integrate with existing systems.
***
## Why Choose SigmaMind?
Unlike fragmented solutions that handle only parts of the AI workflow, SigmaMind delivers an **end-to-end platform**:
* Unified environment for **building, testing, and deploying**.
* Flexible integrations with **telephony providers, apps, and CRMs**.
* Developer-friendly tools like APIs, webhooks, and dynamic variables.
* Full visibility into logs, nodes, and system-level events for debugging.
***
## Next Steps
* Learn how to [create your first AI Agent](/documentation/getting-started/create-first-ai-agent).
* Explore the [Playground](/documentation/playground/overview) to test conversations.
* Set up [SIP Integration](/documentation/phone-number/sip-integration/overview) to bring your own numbers.
* Configure [Webhooks](/documentation/agents/agent-webhooks) for real-time notifications.
***
## Summary
* SigmaMind AI is a **complete platform** for conversational AI agents.
* Supports **inbound, outbound, and web calls**.
* Provides **Playground testing**, **BYO integration**, **webhooks**, and **settings control**.
* Designed for both **quick prototypes** and **enterprise-scale deployments**.
With SigmaMind AI, you can move from idea to production-ready Voice AI agents faster, with full control, flexibility, and confidence.
# Prompt Engineering Guide
Source: https://docs.sigmamind.ai/documentation/getting-started/prompt-engineering-guide
Good agents start with good instructions. This guide walks you through writing a clear, structured prompt for your AI agent - step by step.
***
## Why Your Prompt Matters
Your agent behaves exactly as you instruct it. Vague instructions produce vague behavior. The more specific and structured your prompt, the more consistently your agent performs — across every conversation, every edge case, every user.
***
## The 5-Part Structure
Every agent prompt should have these five sections. Follow them in order.
***
### 1. Identity
Define who your agent is. Give it a name, a role, and a clear purpose. This sets the foundation for everything else.
Write it like this:
```text theme={null}
You are [Name], a [role] for [company]. You help [who] with [what].
```
Example:
```text theme={null}
You are Maya, a customer support assistant for Bloom Skincare.
You help customers with order questions, returns, and product guidance.
```
***
### 2. Style
Tell your agent how to communicate — tone, length, language level. Be specific. "Be friendly" means nothing. "Keep responses to 2 sentences and never use jargon" does.
Things to specify:
* Response length (e.g. 2–3 sentences max)
* Tone (e.g. warm, professional, direct)
* Whether to use the customer's name
* How formal or casual the language should be
Example:
```text theme={null}
Be warm and concise. Keep answers to 2–3 sentences.
Always use the customer's name if you have it. Avoid technical terms.
```
***
### 3. Rules
List what your agent must always do — and must never do. These are your guardrails.
```text theme={null}
Always do:
- Ask for an order number before looking anything up
- Confirm actions with the user before completing them
- Offer to escalate if you can't resolve the issue
Never do:
- Promise a refund without checking policy first
- Make up information you don't have access to
- Mention competitor products
```
***
### 4. Task
Break the agent's job into numbered steps. One action per step. This is the core flow the agent follows in every conversation.
```text theme={null}
Step 1: Greet the user and ask how you can help.
Step 2: Identify what the user needs.
Step 3: Collect their order number if relevant.
Step 4: Resolve the issue or escalate if needed.
Step 5: Close warmly and ask if there's anything else.
```
If your agent handles multiple use cases (e.g. returns AND product questions), write a separate task flow for each one.
***
### 5. Objection Handling
Tell your agent what to do when things don't go smoothly. Cover at least three situations: confusion, frustration, and out-of-scope requests.
```text theme={null}
If the user is confused:
Slow down, repeat what you understood, and ask one clarifying question.
If the user is upset:
Apologize, acknowledge the issue without deflecting, and offer to
connect them with a human agent.
If the user asks something out of scope:
Say you can't help with that specifically, and offer to escalate or redirect.
```
***
## Using Variables
Variables let you personalize conversations automatically. They pull in real data — like a customer's name or order number — without hardcoding it.
Write variables in double curly braces: `{{variable_name}}`
Common examples:
| Variable | What it fills in |
| ------------------- | ------------------------ |
| `{{customer_name}}` | The caller's actual name |
| `{{order_number}}` | Their specific order ID |
| `{{company_name}}` | Your company name |
| `{{agent_name}}` | The AI agent's name |
Where to use them:
* **Greeting:** `"Hi {{customer_name}}, thanks for reaching out!"`
* **Confirmation:** `"I've updated your order {{order_number}}."`
* **Escalation:** `"Connecting you now, {{customer_name}}. One moment."`
* **Closing:** `"Thanks for calling {{company_name}}. Have a great day!"`
A variable only works if it's been passed into the conversation or extracted during the call. If the data isn't available, the agent will say the placeholder literally — like `customer_name`. Always make sure variable names match exactly what your system sends.
For a full variable reference, see the [Extract Variables Guide](https://docs.sigmamind.ai/documentation/agents/add-advance-nodes/extract-variables).
***
## Connecting Tools
If your agent has access to external tools or APIs, your prompt needs to tell it when to use them — and what to do after.
Write each one as a trigger condition:
```text theme={null}
If the user asks for order status → use the check_order_status tool
→ confirm the result with the user before closing.
If the user wants a refund → use the escalate_to_human tool
→ do NOT attempt to process the refund yourself.
If the user is upset or asks for a manager → use the escalate_to_human tool
→ immediately, without attempting to resolve further.
```
List a trigger rule for every tool your agent has access to. Don't assume the agent will figure out when to use them on its own.
***
## Controlling How Data Is Formatted
Voice agents don't always speak numbers, names, and codes the way you expect. Without explicit instructions, an agent might read a phone number as "four hundred fifteen million..." instead of digit by digit - or pronounce an order ID incorrectly.
Tell your agent exactly how to speak each type of data.
### Why This Matters
The same value can be spoken in multiple valid ways. Your agent has no way to know which format you want unless you specify it clearly.
| Data Type | Uncontrolled Spoken Output | What You Want |
| :----------- | :-------------------------------- | :-------------------------------- |
| State name | "C A" | "California" |
| Phone number | "four hundred fifteen million..." | "(4-1-5) 5-5-5-2-6-7-1" |
| Amount | "one hundred twenty-five dollars" | "one hundred twenty-five dollars" |
| Order ID | "\$125" | "O-R-D 1-0-2-9-3" |
| ZIP code | "ninety-four one oh five" | "9-4-1-0-5" |
### How to Write Voice Formatting Rules
Add speaking instructions to your **Style** or **Rules** section. Be explicit — say exactly how the agent should read values out loud.
```text theme={null}
Always say state names in full —
say "California", not "C A".
Always read phone numbers digit by digit —
say "(4-1-5) 5-5-5-2-6-7-1".
Always read dollar amounts $125 naturally for voice —
say "one hundred twenty-five dollars".
Always read order IDs clearly one character at a time —
say "O-R-D, 1-0-2-9-3".
Always read ZIP codes digit by digit —
say "9-4-1-0-5".
```
If your voice agent handles phone numbers, addresses, dates, verification codes, or IDs, add a speaking rule for each one. Clear pronunciation rules make conversations much easier for callers to understand.
***
## Common Mistakes to Avoid
These are the most frequent reasons an agent behaves inconsistently or unexpectedly.
* **Too vague on tone.** "Be professional" is not enough. Say exactly what professional looks like for your brand.
* **Missing the unhappy path.** Most prompts only describe the ideal flow. Always write what happens when something goes wrong.
* **Combining steps.** If a step has two actions, split it into two steps.
* **Skipping tool triggers.** If a tool isn't mentioned in the instructions, the agent won't know when to use it.
* **Untested variables.** Always verify your variables are being passed in correctly before going live.
* **No formatting rules for data.** If you don't specify how to handle phone numbers, amounts, state names, or IDs, your agent will pick a format on its own — and it's often wrong.
# Quick Start with AI Agents
Source: https://docs.sigmamind.ai/documentation/getting-started/quick-start
Get started with SigmaMind AI Agents by creating your first agent, connecting a phone number, and testing calls.
## Overview
This guide walks you through the end-to-end flow of setting up your first **AI Agent** in SigmaMind:
* Create an agent
* Purchase or bring your own phone number
* Connect the number to your agent
* Make your first calls
**Note:** If you haven't already, [Sign Up for a SigmaMind account](https://dashboard.sigmamind.ai/p/signup).
### 1. Create an AI Agent (single prompt or conversational flow)
From the [SigmaMind Dashboard](https://dashboard.sigmamind.ai/app/ai/agents), navigate to **AI Agents** in the left sidebar.
Click the **Create AI Agent** button. You can create an agent using a pre-configured template or build it from scratch:
* **Select a template** that fits your use case (e.g., Debt collection agent, Hotel booking agent)
* [**Create a single-prompt agent**](https://www.youtube.com/watch?v=Kbs-U9kzYmk) for simple, straightforward interactions
* [**Create a conversational agent**](https://www.youtube.com/watch?v=oXGBz_weFrc) (multi-prompt agent) for complex, multi-step workflows
* Under [**Basic Settings**](https://www.youtube.com/watch?v=800kz9V1LdQ), select the agent voice, language, and model that you want to use.
* Fine-tune your agent using [**Call settings**](https://www.youtube.com/watch?v=kLo32BFkT2M) and [**Speech settings**](https://www.youtube.com/watch?v=KqQBZSyBcc8).
As you configure the agent it will auto-save. Just change the agent mode to **Testing** if you want to test it on **Playground** or to **Live** to make it handle live phone calls.
At this point, your agent is ready to be connected to a phone number.
### 2. Add Phone Number
From the [SigmaMind Dashboard](https://dashboard.sigmamind.ai/app/dashboard), navigate to **Phone Numbers** in the left sidebar.
Click the **Add Phone Number** button to either purchase a new number or bring your own number (BYO).
Click on **Purchase from Twilio**. Select your desired country and area code or prefix. Confirm the purchase to add the number to your account.
Click on **Connect via SIP Trunking**. Choose your provider (e.g., `Twilio`, `Telnyx`) and configure the necessary SIP credentials or forwarding settings. Save the configuration to integrate the number into your account.
After selecting or integrating a number, confirm your choice and save it to your account.
You now have a phone number ready to be assigned to your AI agent.
### 3. Assign the number to your agent
From the [SigmaMind Dashboard](https://dashboard.sigmamind.ai/app/dashboard), navigate to **Phone Numbers** in the left sidebar.
Click on the phone number you just purchased or integrated to open its details page.
In the number details, find the **Inbound AI Agent** and **Outbound AI Agent** in dropdown. Select the AI Agent you created earlier from the list.
Click **Save** to apply the changes and connect the number to your agent.
Your agent is now connected to a real phone number.
### 4. Make Your First Calls
From any phone, dial the connected number. Your AI Agent will answer with the first response based on the global prompt.
You can trigger an outbound call from the [**Campaigns**](https://www.youtube.com/watch?v=fr7Dj-l7YXU) module or via the API.
Example API (simplified):
```sh theme={null}
curl --location 'https://api.sigmamind.ai/v1/calls' \
--header 'X-API-KEY: ' \
--data '{
"agentId": "D5D0p7TUs66TTAEAx",
"customer": { "number": "+1234567890" }
}'
```
## Next Steps
* Configure [Agent Settings](/documentation/agents/settings/overview)
* Customize Speech & Voices
* Integrate Webhooks
* Monitor Campaign Calls
# Templates
Source: https://docs.sigmamind.ai/documentation/getting-started/templates
Explore pre-built templates to quickly create AI agents for various use cases.
## Overview
Templates allow you to quickly create AI agents using pre‑built configurations designed for common business use cases. Instead of building an agent from scratch, you can select a template that already includes predefined prompts, logic, and behavior.
This helps you save time, follow best practices, and deploy AI agents faster.
Templates are ideal for use cases such as appointment booking, customer support, debt collection, insurance assistance, and more.
***
## Why Use Templates
Using templates provides several advantages:
* **Faster setup** – Create AI agents in seconds without starting from scratch.
* **Pre‑configured logic** – Templates include ready‑made prompts and workflows.
* **Best practice design** – Built using proven conversational structures.
* **Easy customization** – Modify prompts, voice, tools, and behavior as needed.
* **Multiple use cases** – Available for different industries and business needs.
***
## Available Template Types
Templates are available for different agent types and industries. Examples include:
### Appointment & Booking
* Appointment booking assistant
* Hotel booking agent
* Service scheduling assistant
### Customer Support
* Telecom customer service agent
* Food delivery support agent
* General customer support assistant
### Financial Services
* Debt collection agent
* Insurance support agent
* Loan inquiry assistant
### Sales & Business
* Sales representative agent
* Lead qualification assistant
Product inquiry assistant
## Available Templates
SigmaMind provides the following pre-built templates:
**Appointment & Scheduling**
* Appointment Booking with [Cal.com](http://Cal.com)
* Hotel Booking Agent
**Customer Support**
* Food Delivery Support (Hindi)
* Telecom – Wireless Provider Customer Service Agent
**Financial Services**
* Debt Collection Agent
* Debt Collection Agent (Hindi)
* Receptionist – Home Loan Provider
* Auto Insurance Policy Renewal
* Receptionist for Health Insurance
**Sales & Lead Handling**
* Sales Rep for EdTech Company
These templates are designed for common business use cases and can be customized based on your specific requirements.
***
## Template Categories
Templates are organized based on:
* **Industry** – Healthcare, Banking, Telecom, Insurance, E‑commerce, etc.
* **Agent Type** – Single Prompt Agent or Conversational Flow Agent
* **Language support** – English, Hindi, and more
This makes it easy to find the right template for your use case.
***
## How to Use a Template
Follow these steps to create an agent using a template:
1. Go to the **SigmaMind AI Dashboard**.
2. Click on **Create AI Agent**.
3. Browse and select any template based on your use case.
4. Click **Continue with this template**.
5. Update and customize the template configuration as per your requirements.
> Templates provide a ready‑made starting point, and you can modify prompts, voice, tools, and other settings to match your business needs.
***
**Customizing a Template**
After selecting a template, you can modify:
* Agent name and description
* System prompt and instructions
* Voice and language
* Tools and integrations
* Call handling behavior
This allows you to tailor the agent to your exact business requirements.
***
## Single Prompt vs Conversational Flow Templates
### Single Prompt Templates
These templates use one main instruction to control the agent’s behavior. The AI dynamically handles the entire conversation based on that instruction.
**Best for:**
* General support
* Appointment booking
* Sales inquiries
* Flexible conversations
### Conversational Flow Templates
These templates use structured steps and predefined conversation paths.
**Best for:**
* Strict workflows
* Compliance‑based conversations
* Step‑by‑step processes
***
## When to Use Templates
Templates are recommended when:
* You want to deploy an AI agent quickly
* You are building common business use cases
* You want a starting point for customization
* You want to follow proven conversation patterns
***
## Best Practices
* Choose the template closest to your use case
* Customize prompts to match your business tone
* Test the agent before deploying
* Add integrations if required
* Continuously improve based on real conversations
***
## Next Steps
After creating an agent from a template, you can:
* Configure voice and behavior
* Add tools and integrations
* Test the agent
* Deploy it for calls or automation
Templates provide the fastest way to build and deploy powerful AI agents.
# Call Analytics
Source: https://docs.sigmamind.ai/documentation/observe/call-analytics
The **Call Analytics** dashboard gives you a real-time view of how your AI voice agents are performing, from call volume and duration to cost breakdowns and quality scores.
Analytics are scoped to the agents and date range selected in the filter bar. Use the **Agent Name**, **Date Range**, and **Timezone** controls at the top of the page to customize your view.
***
## Key Metrics
Cumulative talk time across all selected agents and the chosen date range.
Total calls handled. Use this alongside **Avg Call Duration** to understand traffic patterns.
All-in cost including LLM inference, telephony, TTS, STT, and platform fees.
Mean duration per call in minutes. A falling average on a high-volume day is normal and expected.
Total spend divided by number of calls. Useful for budgeting and capacity planning.
Breakdown (count and %) of how calls ended — caller hang-up, agent end, or transfer.
***
## Volume & Cost Trends
Each metric card on the dashboard includes a **time-series chart** grouped by the interval you select (Hours, Days, Weeks). These charts help you spot:
| Pattern | What it means |
| ----------------------------------------- | ------------------------------------------- |
| Flat volume → sudden spike | Testing session or new user on-boarding |
| Rising avg duration early → falling later | Power users first, focused callers later |
| Cost closely tracks volume | Healthy — no runaway per-call cost |
| Cost rising faster than volume | Investigate LLM prompt length or model tier |
Switch **Group By** to **Hours** when investigating a specific day's spike — it shows exactly when traffic arrived.
***
## Agent Activity
### Tool Calls
The **# Tool Calls** chart shows how often agents invoked external tools (e.g. CRM look-ups, appointment booking APIs) during calls. The **% Tool Calls (weighted)** metric normalises this against total call volume.
A very low tool-call rate for agents designed to use tools may indicate missing intent triggers or misconfigured tool definitions. Review your agent's tool configuration if the weighted rate is unexpectedly low.
### Transfer & End Calls
| Metric | Description |
| ------------------------------- | ----------------------------------------------------------------------------------------- |
| **# Transfer Calls** | Calls escalated to a live agent. A non-zero value means your fallback routing is working. |
| **# End Calls** | Calls the agent actively ended (as opposed to the caller hanging up). |
| **% Transfer Calls (weighted)** | Transfer rate as a share of all calls — key self-service KPI. |
***
## Call Quality
### Blank Calls
The **% of Blank Calls** chart shows the percentage of calls with no meaningful audio or interaction per day. High blank-call rates are normal during testing phases but should fall toward 0% in production.
### Quality by Duration
The **Call Quality (% of call b/w duration)** stacked bar chart segments calls into duration buckets — longer calls generally indicate higher engagement and are treated as higher quality.
During ramp-up or heavy test days, you may see 100% of calls fall into shorter duration buckets. This is expected and will normalize as real traffic grows.
***
## Cost Breakdown
The **Cost Breakdown** chart splits spend into five components:
The largest cost driver for most agents. Directly influenced by system prompt length, conversation turns, and the model tier selected in your agent configuration.
Per-minute carrier charges for inbound or outbound calls. Fixed rate regardless of agent behaviour.
Charged per character synthesised. Shorter, more concise agent responses reduce TTS cost.
Per-second transcription cost. Longer silences and hold periods are included in billable STT time.
Fixed SigmaMind infrastructure overhead per call.
***
## Call Source
The **Call Source** donut shows where calls originated:
| Source | Description |
| ---------------- | ------------------------------------------------------- |
| **Playground** | Calls made via the SigmaMind in-browser testing sandbox |
| **Web Widget** | Calls initiated from an embedded widget on your website |
| **Phone Number** | Calls from a provisioned SigmaMind phone number |
| **API** | Programmatically triggered calls via the Calls API |
Use the **↺ refresh icon** on individual charts to reload that metric without refreshing the full page.
# Chat Analytics
Source: https://docs.sigmamind.ai/documentation/observe/chat-analytics
Monitor chat and ticket performance, tool usage, and intent detection across your SigmaMind AI agents.
The **Chat Analytics** dashboard tracks how your AI agents handle text-based interactions — across chat, email, and phone (ticket) channels. Use it to measure volume, cost efficiency, tool usage, and the intents your agents are resolving.
Chat Analytics are scoped by **Channel**, **Agent Name**, **Date Range**, and **Timezone**. Use the filter bar at the top to narrow your view. Supported channels: `chat`, `email`, `phone`.
***
## Key Metrics
The total number of messages or exchanges handled across all selected channels and agents. Includes every turn in a conversation, not just conversation starts.
The number of distinct chat sessions or support tickets opened during the period. Use this to understand conversation volume independent of message depth.
Cumulative cost across all chat interactions. Chat-based agents are generally lower cost than voice agents since telephony charges do not apply.
Total spend divided by number of chats or tickets. A rising average may indicate longer conversations or heavier tool use per session.
***
## Volume Trends
The **Total Interactions** and **# Chats/Tickets** charts display activity over time, grouped by your chosen interval (Hours, Days, Weeks).
| Pattern | What it means |
| -------------------------------------- | --------------------------------------------------------------------------------- |
| Interactions growing faster than chats | Conversations are getting longer — agents may need more turns to resolve requests |
| Chats spike, interactions flat | Short, transactional sessions dominating — typical for FAQ-style agents |
| Gradual ramp then sharp spike | Testing phase transitioning to real or bulk traffic |
| Flat interactions across period | Consistent, stable usage — a sign of a mature deployment |
Compare **Total Interactions** against **# Chats/Tickets** to derive the implicit **avg messages per conversation** — a useful proxy for resolution complexity.
***
## Tool Calls
The **# Tool Calls** chart shows how many times agents invoked external tools (e.g. knowledge base look-ups, CRM queries, appointment APIs, form submissions) across chat sessions.
If your agents are configured with tools but the tool-call count is consistently 0, check that your agent's intent-to-tool mappings are correctly defined. Low tool usage on agents designed to use tools is a common misconfiguration signal.
Tool call data is broken down by day so you can correlate spikes in tool usage with specific conversation volumes or agent deployments.
***
## Intents
The **Intents** chart visualises the topics and goals your agents detected during conversations. Each bar or data point represents a recognised intent category and how frequently it appeared across sessions.
Intent detection requires that your agent has intent classification enabled. If the Intents chart appears empty, verify that your agent configuration includes an intent schema or classifier. See [Agent Configuration](/agents/configuration) for setup instructions.
Common use cases for intent data:
* Identify which topics drive the most volume so you can prioritise knowledge base improvements
* Spot intents with high frequency but low resolution rate — signals where agents need better training
* Detect unexpected intents that suggest callers or users have needs your agent is not designed to handle
***
## Channels
Chat Analytics aggregates data across three channel types:
| Channel | Description |
| --------- | -------------------------------------------------------------------- |
| **chat** | Live or async chat sessions from your web widget, mobile SDK, or API |
| **email** | Email threads processed by your AI agent as a support ticket |
To add or remove channels from the analytics view, use the **Channels** multi-select filter at the top of the page. Each channel can also be analysed independently by deselecting the others.
***
## Cost Behaviour
Unlike voice calls, chat interactions are not subject to telephony or TTS/STT charges. Chat cost is driven almost entirely by **LLM inference** — the number of tokens processed per conversation turn.
Factors that influence chat cost:
* **System prompt length** — loaded on every conversation start
* **Conversation history** — longer threads pass more context tokens per turn
* **Tool call responses** — tool results injected into context add tokens
* **Model tier** — higher-capability models cost more per token
If **Avg Cost per Chat/Ticket** is rising without a corresponding increase in resolution quality, audit your system prompt for verbosity and consider whether a lighter model tier meets your accuracy needs for common intents.
***
## Filters & Controls
| Control | Options | Notes |
| -------------- | ----------------------------- | ------------------------------------------- |
| **Channels** | `chat` · `email` · `phone` | Multi-select; all channels shown by default |
| **Agent Name** | Multi-select from your agents | Filter to one or more specific agents |
| **Date Range** | Custom start / end date | Maximum range: 90 days |
| **Timezone** | Any IANA timezone | Defaults to your account timezone |
Use the **↺ refresh icon** on any individual chart to reload that metric without refreshing the full dashboard.
# Calls Logs
Source: https://docs.sigmamind.ai/documentation/observe/monitor-calls
The Conversation page provides a complete history of all inbound, outbound, and web calls handled through the platform. It helps track call activity, monitor agent performance, and review conversation details.
The **Calls** tab under Conversations displays all voice and web call interactions handled by your AI agents. Use this page to track call outcomes, review durations, and investigate individual sessions.
## How to Navigate
1. Go to the Home Dashboard.
2. From the left side panel, click on **Conversations**.
3. Open the **Calls** tab at the top of the page.
***
## Filters
Use the filter bar at the top to narrow down your call list:
| Filter | Description |
| -------------- | ---------------------------------------------------------------------------------- |
| **Agent Name** | Filter by one or more agents (e.g., *Receptionist for Health Insurance*, *New AI*) |
| **Date Range** | Set a custom start and end date (e.g., Apr 26, 2026 – May 8, 2026) |
| **Timezone** | Choose your preferred timezone for all timestamps (e.g., Asia/Calcutta GMT+05:30) |
Click **1 Filter** to view or clear any active filters. Use **Download** to export the current view as a CSV. Click **Refresh** to reload the latest data.
***
## Calls Table
Each row represents a single call interaction. The table includes the following columns:
| Column | Description |
| ------------------------- | ---------------------------------------------------------------- |
| **Conversation\_ID** | Unique numeric identifier for the conversation |
| **Source** | Origin of the call (e.g., *Playground*) |
| **From phone number** | Caller's phone number — populated for Outbound calls |
| **To phone number** | Recipient's phone number — populated for Outbound calls |
| **Call type** | Type of call — `Chat`, `Web`, or `Outbound` |
| **Call ID** | Unique string identifier for the call session |
| **Call status** | Current status of the call (e.g., `Ended`) |
| **Terminated reason** | How the call ended — `Agent Ended Call` or `Customer Ended Call` |
| **Agent Name** | The AI agent that handled the call |
| **Updated Datetime** | Date when the conversation record was last updated |
| **Duration (in seconds)** | Total length of the call in seconds |
| **Start time** | Timestamp when the call began |
| **End time** | Timestamp when the call ended |
***
## Call Types
Text-based sessions initiated through the Playground interface. Duration is typically `0` seconds as these are non-voice interactions.
Calls initiated via a web embed or widget by a customer visiting your site or app.
Calls placed by the AI agent to a customer's phone number. Both `From` and `To` phone numbers are populated.
***
## Terminated Reasons
| Reason | Description |
| --------------------- | ------------------------------------------- |
| `Agent Ended Call` | The AI agent terminated the conversation |
| `Customer Ended Call` | The customer or user ended the conversation |
## FAQs
Chat-type calls (text sessions in the Playground) show a duration of `0` seconds because they are not voice calls — there is no audio duration to measure.
*Playground* indicates the call was initiated from the SigmaMind Playground testing environment, not a live production deployment.
Use the **Agent Name** and **Date Range** filters together to narrow results. You can also sort by **Conversation\_ID** (descending) to see the most recent calls first.
Duration-based filtering is not available in the UI. Download the data and apply duration filters in a spreadsheet tool like Excel or Google Sheets.
# Chat logs
Source: https://docs.sigmamind.ai/documentation/observe/monitor-chats
The \*\*Chat \*\*under Conversations displays all text-based interactions handled by your AI agents. Use this page to browse conversations across multiple channels, filter by agent or date, and review individual chat sessions.
## How to Navigate
1. Go to the Home Dashboard.
2. From the left side panel, click on **Conversations**.
3. Open the **Chats** tab at the top of the page.
## Common Use Cases
* Monitor agent chat performance.
* Review customer conversation history.
* Track active and completed conversations.
* Analyze communication activity across channels.
* Audit customer support interactions for quality assurance.
## Status Indicators
* **Updated Datetime** → Displays the latest activity timestamp for the conversation.
* **Channel** → Indicate the communication channel used for the conversation.
* **Agent Name** → Shows which AI agent or support workflow handled the interaction.
***
## Filters
Use the filter bar at the top to narrow down your chat list:
| Filter | Description |
| -------------- | ---------------------------------------------------------------------------------- |
| **Channels** | Filter by one or more channel types — `chat`, `email`, or `phone` |
| **Agent Name** | Filter by one or more agents (e.g., *Receptionist for Health Insurance*, *New AI*) |
| **Date Range** | Set a custom start and end date (e.g., Apr 1, 2026 – May 8, 2026) |
| **Timezone** | Choose your preferred timezone for all timestamps (e.g., Asia/Calcutta GMT+05:30) |
Click **1 Filter** to view or clear any active filters. Use **Download** to export the current view as a CSV. Click **Refresh** to reload the latest data.
***
## Chats Table
Each row represents a single chat conversation. The table includes the following columns:
| Column | Description |
| -------------------- | ----------------------------------------------------------------------------------- |
| **Conversation\_ID** | Unique numeric identifier for the conversation |
| **Source** | Origin of the conversation (e.g., *Playground*) |
| **Channel** | The channel through which the conversation took place — `Chat`, `Email`, or `Phone` |
| **Agent Name** | The AI agent that handled the conversation |
| **Updated Datetime** | Date when the conversation record was last updated |
***
## Channels
Text conversations initiated through a chat widget, web embed, or the SigmaMind Playground.
Conversations that originated from or were handled via email threads.
Use the **Agent Name** and **Date Range** filters together to quickly find what you're looking for.
***
## FAQs
*Playground* indicates the conversation was initiated from the SigmaMind Playground testing environment, not a live production deployment.
Click on any row in the Chats table to open the full conversation transcript and details.
Yes — use the **Channels** filter at the top to select one or more channels (`chat`, `email`, `phone`). Deselect channels to exclude them from the results.
If you see many conversations with the same **Updated Datetime**, it typically means a batch of test conversations were created together in the Playground during that session.
# Observe Overview
Source: https://docs.sigmamind.ai/documentation/observe/overview
Learn how to monitors chat & calls.
# Overview
The Observe section provides comprehensive monitoring and analytics capabilities to track your AI agent's performance and customer interactions.
## 1. Conversations
Monitor and analyze customer interactions across all channels to ensure optimal performance and customer satisfaction.
### 1.1. Monitor Conversations
Real-time and historical conversation monitoring with:
* Live conversation tracking and oversight
* Conversation thread visualization
* Agent response quality assessment
* Customer satisfaction scoring
* Issue identification and flagging
* Multi-channel conversation aggregation
* Search and filtering capabilities
* Conversation export and archiving
## 2. Analytics
Comprehensive analytics and reporting tools to gain insights into your AI agent's performance and customer behavior patterns.
### 2.1. Analyze Conversations / Calls
Detailed analysis of customer interactions providing:
* Conversation outcome classification
* Response time and resolution metrics
* Customer sentiment analysis throughout conversations
* Agent accuracy and effectiveness scoring
* Common issue identification and trending
* Peak usage time analysis
* Channel performance comparison
* Customer journey mapping
* Success rate tracking by conversation type
* Automated insights and recommendations
* Custom reporting and dashboard creation
* Data export for external analysis tools
# Termination Reasons
Source: https://docs.sigmamind.ai/documentation/observe/termination-reasons
Every call handled by SigmaMind ends with a **Termination Reason** — a system-assigned value that tells you exactly how and why the call session closed. This value appears in the **Call Logs** table under the `Terminated reason` column and is also returned via the API as `terminationReason` on any call record.
Understanding termination reasons helps you:
* Monitor agent performance and call quality
* Identify calls that ended unexpectedly or due to failures
* Improve agent prompts based on how conversations are closing
* Filter and segment call data for reporting and analytics
***
## Where to Find Termination Reasons
### In the Dashboard
1. Go to **Home Dashboard**
2. From the left panel, click **Conversations**
3. Open the **Calls** tab
4. Look for the **Terminated reason** column in the calls table
Each row shows one of the reason values listed below.
### Via the API
Termination reason is returned in the `terminationReason` field when you fetch a call record:
```bash theme={null}
GET https://api.sigmamind.ai/v1/calls/{callId}
```
**Example response:**
```json theme={null}
{
"callId": "call_AuUKK371Spr5nHJS",
"status": "ended",
"terminationReason": "user_ended_call",
"duration": 120,
"startTime": "2024-04-20T10:00:00.000Z",
"endTime": "2024-04-20T10:02:00.000Z"
}
```
`terminationReason` is `null` if the call has not yet ended (status is `in_progress` or `scheduled`)
***
## All Termination Reasons
### `silence_timed_out`
**The call was terminated due to prolonged silence or no interaction.**
SigmaMind detected that neither the customer nor the agent was speaking for an extended period. The platform automatically closed the session to avoid an open, idle connection.
**Common triggers:**
* Customer put the phone down without hanging up
* Customer was placed on hold manually but the AI did not detect activity resuming
* Network or audio issues caused one side to stop transmitting
* The agent was waiting for a response that never came
**What it means for you:** Silence timeout terminations usually point to either a customer who disengaged quietly or a technical audio issue. Review the transcript to see where the silence began.
**How to reduce it:**
* Configure silence handling in **Call Settings** — set a maximum silence duration and a prompt the agent should play (e.g., "Are you still there?") before terminating
* Ensure your agent prompts are open-ended enough to keep the customer engaged
***
### `agent_ended_call`
**The AI agent terminated the call programmatically.**
This happens when the agent executes the `voice_end_call` tool based on its configured instruction. It is the expected, intentional ending for any call where the AI completes its task and closes the conversation cleanly.
**Common triggers:**
* Customer confirmed a booking, renewal, or action
* Customer said goodbye or "that's all"
* Customer declined the offer or asked to be removed from the list
* Agent reached the end of its script after all steps completed
**What it means for you:** This is a healthy termination reason. A high proportion of `agent_ended_call` in your call logs means your agent is closing conversations correctly and consistently.
**How to control it:** Configure the `voice_end_call` tool in your agent with a precise instruction.
***
### `user_ended_call`
**The customer or user hung up first.**
The call ended because the person on the other end disconnected — either by pressing the hang-up button on their phone, saying "goodbye" without triggering the agent's end-call tool, or simply dropping the line.
**Common triggers:**
* Customer finished the conversation and hung up before the agent did
* Customer lost patience mid-conversation
* Customer accidentally disconnected
* Customer was not satisfied and dropped the call
**What it means for you:** Occasional `user_ended_call` is normal — many customers will hang up on their own. However, a high rate of this reason, especially early in calls, may indicate the agent is not engaging the customer effectively or is failing to trigger its own `voice_end_call` tool cleanly.
**How to improve:**
* Review transcripts of calls with this reason to identify drop-off points
* Ensure the agent has a warm, natural closing flow so it ends the call before the customer feels they need to hang up themselves
***
### `voicemail_detected`
**The call reached voicemail and was not answered live.**
SigmaMind's voicemail detection identified that the call connected to an automated voicemail system rather than a live person. The platform terminated the call rather than leaving a message (unless voicemail drop is configured).
**Common triggers:**
* Customer's phone went to voicemail (did not answer)
* Business line is outside operating hours and routes to voicemail
* Customer's phone is switched off
**What it means for you:** For outbound campaigns, a high `voicemail_detected` rate can indicate poor timing (calling outside peak hours), list quality issues (inactive numbers), or the need to adjust retry schedules.
**How to handle it:**
* Use **Campaign Settings** to set preferred calling hours that align with your audience's availability
* Configure retry logic to attempt the number again at a different time
* Enable voicemail drop if you want the agent to leave a pre-recorded message
***
### `ivr_detected`
**The call connected to an automated IVR (Interactive Voice Response) system instead of a live person.**
SigmaMind detected that the answered call was an automated phone menu rather than a human recipient. The platform terminated the call to avoid the agent interacting with a non-human system.
**Common triggers:**
* Calling a business number that routes through an IVR before reaching a person
* The destination number has an automated attendant or press-1 menu
* Corporate or multi-department lines with front-end automation
**What it means for you:** A high `ivr_detected` rate in your campaign may indicate that your contact list includes business switchboard numbers rather than direct lines, or that you are calling during hours when live agents are unavailable.
**How to handle it:**
* Review your contact list to ensure you are dialling direct lines where possible
* Consider adjusting call timing to hours when live staff are more likely to answer
***
### `agent_transferred_call`
**The AI agent transferred the call to another destination.**
The call session on SigmaMind's side was closed because the agent performed a call transfer — handing the conversation off to a human agent, a different number, or another system.
**Common triggers:**
* Customer requested to speak to a human
* Agent reached an escalation point in its script
* Transfer tool was triggered based on customer intent or outcome
**What it means for you:** `agent_transferred_call` is an expected and intentional outcome when your agent is configured with transfer logic. Monitor this rate to understand how often escalations occur and whether transfer destinations are handling calls effectively.
***
### `max_call_duration_exceeded`
**The call reached the maximum allowed duration and was automatically terminated.**
SigmaMind enforces a configurable maximum call duration to prevent runaway sessions. When a call hits this limit, it is closed regardless of where the conversation is.
**Common triggers:**
* An unusually long conversation that exceeded the set limit
* A loop or repeated exchange in the agent's script that kept the call running
* A customer who stayed on the line for an extended period without resolution
**What it means for you:** Calls hitting `max_call_duration_exceeded` may indicate the agent is not resolving the customer's request efficiently, or that the max duration setting is too short for your use case.
**How to adjust it:** Go to **Call Settings** → **Max Call Duration** to increase or decrease the limit. Review transcripts of `max_call_duration_exceeded` calls to check whether the agent is looping or stalling.
***
### `dial_telephony_permission_denied`
**Outbound dialling was blocked by the telephony provider due to a permission or authorisation issue.**
The call could not be placed because SigmaMind's telephony provider rejected the dial request at the permission level — not because the destination number is invalid, but because the originating account or number is not authorised to place this type of call.
**Common triggers:**
* Outbound calling not enabled on the account or phone number
* Geographic or international dialling restrictions in place
* Caller ID or originating number not verified or approved
* Account compliance hold or restriction applied by the provider
**What it means for you:** This is a configuration or account-level issue, not a problem with the destination number. It requires action on your SigmaMind account or telephony settings.
**How to investigate:** Review your telephony provider permissions, confirm outbound calling is enabled for the originating number, and contact SigmaMind support if the issue persists.
***
### `dial_invalid_destination`
**The call could not be placed because the destination number was invalid.**
SigmaMind or the carrier rejected the dial attempt because the destination phone number is not a valid, dialable number.
**Common triggers:**
* Phone number is not in valid E.164 format (`+[country code][number]`)
* Number contains invalid characters or incorrect digit count
* Number is not assigned or does not exist on the carrier network
**What it means for you:** Isolated `dial_invalid_destination` calls indicate bad numbers in your contact list. A high rate may point to a data quality issue with your list or an incorrect number format being passed to the API.
**How to fix it:** Validate all numbers are in E.164 format before importing or passing them to SigmaMind. Remove or correct invalid entries from your list.
***
### `dial_no_answer`
**The call rang but was not picked up within the timeout period.**
SigmaMind dialled the number, the carrier confirmed ringing, but no one answered before the configured timeout expired.
**Common triggers:**
* Customer did not hear or see the incoming call
* Customer chose not to answer an unknown number
* The number is valid but the person is unavailable
**What it means for you:** `dial_no_answer` is the most common outbound non-connection reason. A high rate may suggest poor timing, unrecognised caller ID, or list quality issues.
**How to handle it:**
* Retry no-answer calls at different times of day to increase contact rate
* Use a local or recognisable phone number as the caller ID to improve answer rates
* Segment your campaign by timezone to call during reasonable hours
***
### `dial_user_declined`
**The recipient actively declined the incoming call.**
The destination phone rang and the recipient explicitly rejected it — pressing the decline button or otherwise actively dismissing the call rather than simply not answering.
**Common triggers:**
* Customer saw the incoming number and chose not to answer
* Customer is on Do Not Call preference and recognised the number
* Repeated calls from the same number causing the recipient to decline
**What it means for you:** Unlike `dial_no_answer`, this is an active rejection. A high rate may indicate caller ID recognition issues, poor list targeting, or contact frequency that is too high for the audience.
**How to handle it:**
* Review call frequency and avoid contacting the same number too often
* Ensure your caller ID is recognisable and trustworthy to your target audience
* Audit your contact list for numbers that have repeatedly declined
***
### `dial_busy`
**The destination number was busy when the call was attempted.**
The outbound call connected to the carrier, but the recipient's line was engaged with another call at the time of dialling.
**Common triggers:**
* The customer was already on another call
* The destination number has a single line with no call waiting
* High-volume campaign dialling the same number simultaneously
**What it means for you:** `dial_busy` is a carrier-level outcome outside SigmaMind's control. It is expected at a low rate in any outbound campaign.
**How to handle it:**
* Configure campaign retry settings to re-attempt busy numbers after a defined interval (e.g., 30–60 minutes)
* Avoid concentrating calls to the same number in a short time window
***
### `dial_failed`
**The outbound call failed due to a SIP or telephony error.**
The call could not be connected because of a SIP-level or telephony provider error — distinct from permission denials or invalid numbers, this indicates a technical failure in the call routing or connection process.
**Common triggers:**
* SIP configuration error on a BYO or SIP trunk number
* Carrier routing failure or temporary outage
* SIP signalling error during call setup
* Incompatible codec or SIP parameters
**What it means for you:** Isolated `dial_failed` calls may be transient carrier issues. A sustained spike may indicate a SIP misconfiguration or a carrier-side problem.
**How to investigate:**
* Review SIP configuration if using BYO or SIP trunking
* Check carrier status for any reported outages
* Contact SigmaMind support if the issue persists across multiple calls
***
### `error_credit_limit_reached`
**The call was terminated because the account's credit balance was insufficient.**
SigmaMind could not continue or initiate the call because the account has reached its credit limit or has insufficient balance to cover the call cost.
**What it means for you:** Active campaigns may pause or calls may terminate mid-session if credit runs out. This requires immediate action to restore calling capacity.
**How to fix it:** Top up your account balance in **Billing Settings**. Consider setting up auto top-up to prevent interruptions during active campaigns.
***
### `error_llm`
**The call was terminated because the language model failed to generate a response.**
The AI engine powering your agent encountered an error and could not produce a reply during the call, causing the session to close.
**Common triggers:**
* Transient LLM service outage or timeout
* Unusually complex input that caused a model processing failure
* Context window or token limit exceeded during a very long call
**What it means for you:** Occasional `error_llm` events may be transient. A pattern of this error across many calls may indicate a systemic issue or a prompt configuration that is causing consistent model failures.
**How to investigate:** Review the transcript up to the point of failure. If the issue recurs, contact SigmaMind support with the affected call IDs.
***
### `error_tts`
**The call was terminated due to a text-to-speech service error.**
The TTS engine failed to convert the agent's text response into audio, causing the session to close.
**Common triggers:**
* Transient TTS service outage
* Unsupported characters or formatting in the agent's response text
* TTS provider rate limit or quota exceeded
**What it means for you:** Isolated `error_tts` events are usually transient. A recurring pattern may indicate a prompt or response format issue causing the TTS engine to fail consistently.
***
### `error_asr`
**The call was terminated due to a speech recognition service error.**
The ASR (Automatic Speech Recognition) engine failed to process the customer's audio input, causing the session to close.
**Common triggers:**
* Transient ASR service outage
* Severe audio quality issues preventing transcription
* ASR provider rate limit or quota exceeded
**What it means for you:** Occasional `error_asr` may reflect transient service issues or poor call audio quality. If this reason appears frequently for calls to a specific region or carrier, audio quality between SigmaMind and that carrier may need investigation.
***
### `error_sigmamind`
**The call was terminated due to an internal SigmaMind processing error.**
An unexpected error occurred within SigmaMind's core platform during the call session, causing it to close.
**What it means for you:** This is a platform-side error. Isolated occurrences may be transient edge cases. If you see a sustained rate of `error_sigmamind`, contact SigmaMind support with the affected call IDs and timeframe.
***
### `error_telephony`
**The call was terminated due to a telephony provider or connection error.**
A failure occurred at the telephony infrastructure level — either with the provider SigmaMind uses or with the connection between SigmaMind and the carrier — that caused the session to close unexpectedly.
**Common triggers:**
* Telephony provider outage or degraded service
* Network connectivity issue between SigmaMind and the carrier
* Unexpected session drop from the provider side
**What it means for you:** A spike in `error_telephony` across multiple calls at the same time may indicate a provider-side incident. Check SigmaMind's status page and your telephony provider's status for any active incidents.
***
### `error_unknown`
**The call ended due to an unknown internal error.**
SigmaMind encountered an unexpected condition that caused the session to close, but the specific error could not be classified.
**Common triggers:**
* Rare edge case during session teardown
* Internal error path not mapped to a known category
**What it means for you:** A small number of `error_unknown` terminations is normal. If you see a large proportion, contact SigmaMind support with affected call IDs for investigation.
***
## Quick Reference Table
| Termination Reason | Who Ended It | Expected? | Action Needed |
| ---------------------------------- | --------------------------- | ------------------------ | ----------------------------------------------- |
| `silence_timed_out` | System (silence timeout) | ⚠️ Sometimes | Check silence settings, review transcripts |
| `agent_ended_call` | AI agent (programmatic) | ✅ Yes | None — healthy outcome |
| `user_ended_call` | Customer hung up | ✅ Usually | Review if rate is high |
| `voicemail_detected` | System (voicemail detected) | ⚠️ Expected in campaigns | Adjust call timing, enable voicemail drop |
| `ivr_detected` | System (IVR detected) | ⚠️ Expected | Review contact list for direct lines |
| `agent_transferred_call` | AI agent (transfer) | ✅ Yes | None — expected escalation outcome |
| `max_call_duration_exceeded` | System (duration limit hit) | ⚠️ Occasional | Review agent script for loops, adjust limit |
| `dial_telephony_permission_denied` | Carrier (permission denied) | ❌ Investigate | Check account permissions, contact support |
| `dial_invalid_destination` | System / Carrier | ❌ Investigate | Validate E.164 number format, clean list |
| `dial_no_answer` | Carrier (no pickup) | ⚠️ Expected | Retry at different times, check caller ID |
| `dial_user_declined` | Recipient (active decline) | ⚠️ Monitor | Review call frequency, caller ID trust |
| `dial_busy` | Carrier (line engaged) | ⚠️ Expected | Configure retry with delay |
| `dial_failed` | Carrier / SIP error | ❌ Investigate | Check SIP config, contact support if widespread |
| `error_credit_limit_reached` | System (no balance) | ❌ Act immediately | Top up account balance |
| `error_llm` | System (LLM failure) | ❌ Investigate | Review transcript, contact support if recurring |
| `error_tts` | System (TTS failure) | ❌ Investigate | Check prompt formatting, contact support |
| `error_asr` | System (ASR failure) | ❌ Investigate | Check audio quality, contact support |
| `error_sigmamind` | System (internal error) | ❌ Investigate | Contact support with call IDs |
| `error_telephony` | Telephony provider | ❌ Investigate | Check provider status page |
| `error_unknown` | Undetermined | ❌ Investigate | Contact support if widespread |
***
## Termination Reason in Post-Call Analysis
Termination reasons are also available in **Post-Conversation Analysis**. You can configure your agent to extract and log the reason alongside custom variables like customer intent, resolution status, or sentiment — giving you a complete picture of each call's outcome.
See [Post-Conversation Analysis](/documentation/agents/settings/post-call-analysis) for setup instructions.
***
## Filtering by Termination Reason
Currently, the Calls table does not support direct filtering by termination reason in the UI. To analyse reason distribution:
1. Click **Download** in the top-right of the Calls table to export the current view as a CSV
2. Open the CSV in Excel or Google Sheets
3. Filter or pivot the `Terminated reason` column to see counts and percentages by reason
# Bring Your Own Number (BYO)
Source: https://docs.sigmamind.ai/documentation/phone-number/bring-your-own-number
How to integrate your own number with SigmaMind
You can bring your own numbers from supported telephony providers into **SigmaMind** using **[SIP Trunking](/documentation/numbers/sip-integration/sip-trunking)**.
Currently, we support the following providers:
* **Twilio**
* **Telnyx**
## Dashboard
You can purchase and assign agents to numbers directly from the **SigmaMind Dashboard**.
* During purchase, you may optionally specify preferred **area codes**.
* After purchase, you can update the number’s **nickname** for easier identification.
* Once assigned, you can configure both **inbound** and **outbound agents**.
After setup, your number will be ready to accept **inbound calls** if an inbound agent has been assigned.\
Give it a try by calling the number to confirm it’s working!
## API
If you prefer programmatic control, you can use our APIs.\
Refer to the [Create Phone Number API Reference](/api-reference/phone-numbers/create-phone-number) for details on all available parameters.
* Numbers are **yours indefinitely** once purchased.
* Manage your purchased numbers in the [Numbers Dashboard](https://dashboard.sigmamind.ai/app/ai/phone-numbers).
* You can assign **different inbound and outbound agents**.
```sh Bring Your Own Number (BYO) theme={null}
curl --location 'https://api.sigmamind.ai/v1/phone-numbers' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: key_C6HL3Goru7Q.TlI5kZOKPmDM03Gt39nRBEnxrL****************' \
--data '{
"friendlyName": "Inbound Agent 2",
"phoneNumber": "+14159876543",
"provider": "byo",
"trunkName": "SigmaMing SIP Trunk",
"trunkUsername": "admin",
"trunkPassword": "password",
"terminationSipURI": "sip.telnyx.com"
}'
```
```sh Purchase New Number theme={null}
curl --location 'https://api.sigmamind.ai/v1/phone-numbers' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: key_C6HL3Goru7Q.TlI5kZOKPmDM03Gt39nRBEnxrL****************' \
--data '{
"friendlyName": "Inbound Agent 1",
"provider": "telnyx"
}'
```
# International Calling & Fees
Source: https://docs.sigmamind.ai/documentation/phone-number/international-calling-fees
Per-minute telephony rates for every country SigmaMind supports, powered by Twilio.
SigmaMind uses **Twilio** as its telephony provider for all outbound and inbound voice calls. Call costs are charged **per minute** based on the destination country of the call. These rates are in addition to your SigmaMind plan subscription.
***
## How Billing Works
* Calls are billed **per minute**, rounded up to the nearest minute
* The rate applied is based on the **destination country** of the call (where the phone number being called is located)
* Charges appear in your **Usage & Billing** dashboard after each call
* All prices are in **USD**
* Rates reflect Twilio's published telephony pricing and are subject to change
***
## Supported Countries & Rates
| Country | Route | Rate per Minute |
| ------------------------------ | ----------------- | --------------- |
| 🇺🇸 United States | US → US | \$0.015 |
| 🇺🇸 United States (Toll-Free) | US → US Toll-Free | \$0.060 |
| 🇨🇦 Canada | US → Canada | \$0.030 |
| 🇲🇽 Mexico | US → Mexico | \$0.050 |
| 🇬🇧 United Kingdom | US → UK | \$0.100 |
| 🇩🇪 Germany | US → Germany | \$0.100 |
| 🇫🇷 France | US → France | \$0.060 |
| 🇮🇹 Italy | US → Italy | \$0.060 |
| 🇪🇸 Spain | US → Spain | \$0.100 |
| 🇦🇺 Australia | US → Australia | \$0.100 |
| 🇮🇳 India | US → India | \$0.150 |
| 🇯🇵 Japan | US → Japan | \$0.280 |
| 🇲🇾 Malaysia | US → Malaysia | \$0.200 |
| 🇮🇩 Indonesia | US → Indonesia | \$0.400 |
| 🇹🇭 Thailand | US → Thailand | \$0.450 |
| 🇵🇭 Philippines | US → Philippines | \$0.800 |
***
## Frequently Asked Questions
**What if my call doesn't connect (busy, no answer, voicemail)?** Calls that connect to voicemail are billed at the normal rate for the duration of the voicemail interaction. Calls that result in `busy` or `no_answer` are typically not billed, as no telephony minutes were consumed.
**Are there volume discounts?** Volume pricing is available on Enterprise plans. Contact [support@sigmamind.ai](mailto:support@sigmamind.ai) for details.
**My target country isn't listed — can I still call it?** Countries not listed above may still be reachable. Contact support to confirm availability and pricing for unlisted destinations.
# Phone Number Overview
Source: https://docs.sigmamind.ai/documentation/phone-number/overview
Learn how to purchase or bring your own phone number into SigmaMind and connect it to AI Agents for inbound and outbound calls.
SigmaMind provides powerful telephony capabilities by allowing you to **purchase new phone numbers** directly from the platform or **bring your own existing numbers**. These numbers serve as the entry and exit points for your AI Agents, enabling them to handle real-world **inbound and outbound calls**.
You can purchase phone numbers directly inside the SigmaMind Dashboard.
If you already own numbers from providers like Twilio or Telnyx, you can integrate them using SIP trunking.
## Why Phone Numbers?
Phone numbers act as the **bridge between your AI Agents and real customers**. By connecting a number to an agent, you enable that agent to:
* **Receive inbound calls** from customers dialing your number.
* **Make outbound calls** for campaigns, follow-ups, or notifications.
* **Test conversations** in a real-world telephony environment, beyond just the Playground.
***
## Purchase a New Number
You can purchase phone numbers directly inside the SigmaMind Dashboard:
1. Navigate to **Phone Numbers** in the sidebar.
2. Click **Purchase Number**.
3. Select:
* **Country / Region** where you need the number.
* **Capabilities** (Voice / SMS, if applicable).
* **Area code or prefix** for local presence.
4. Complete the purchase, and the number will be instantly available in your account.
***
## Bring Your Own Number (BYO)
If you already own numbers from providers like **Twilio, Telnyx, or others**, you can integrate them into SigmaMind using **SIP trunking** or supported providers.
Steps:
1. Go to **Phone Numbers → Bring Your Own Number**.
2. Choose your provider from the available list (e.g., Twilio, Telnyx).
3. Follow the instructions to configure SIP credentials or forwarding.
4. Once added, your number will appear alongside purchased numbers in your SigmaMind dashboard.
***
## Connecting Numbers to AI Agents
After you purchase or bring a number, you can assign it to an AI Agent:
1. Navigate to **Phone Number** in dashboard.
2. Choose the phone number you want to bind.
3. Select the desired **AI Agent** from the dropdown for both inbound and outbound.
4. Save the settings.
* Inbound calls to that number will be routed to your AI Agent.
* Outbound calls made by that agent will display the assigned number as the **Caller ID**.
***
## Testing Inbound & Outbound Calls
* **Inbound Test**: Dial your purchased/connected number from any phone to interact with your AI Agent.
* **Outbound Test**: Trigger calls via the **Campaigns module** or the **API** to see how your agent performs in live outbound scenarios.
***
## Key Benefits
* Unified telephony management inside SigmaMind.
* Flexibility to purchase or integrate existing numbers.
* Easy mapping between numbers and AI Agents.
* Full control over inbound, outbound, and test calls.
***
> 📌 Next steps: [Purchase Phone Number](/documentation/phone-number/purchase-phone-number) or [Bring Your Own Number](/documentation/phone-number/bring-your-own-number).
# Purchase Phone Number
Source: https://docs.sigmamind.ai/documentation/phone-number/purchase-phone-number
Step by step guide to buy a number from SigmaMind
The numbers are fully managed by SigmaMind, so you don’t need to worry about telephony infrastructure setup.
Currently, we only support the purchase of **US numbers** and making **domestic calls** from the platform.\
If you are looking to:
* Use numbers from other countries
* Make international calls
* Use your own telephony provider
Check out the [Bring Your Own Number guide](./bring-your-own-number).
***
## Dashboard
You can purchase and assign agents to numbers directly from the **SigmaMind Dashboard**.
* During purchase, you may optionally specify preferred **area codes**.
* After purchase, you can update the number’s **nickname** for easier identification.
* Once assigned, you can configure both **inbound** and **outbound agents**.
After setup, your number will be ready to accept **inbound calls** if an inbound agent has been assigned.
Give it a try by calling the number to confirm it’s working!
## API
If you prefer programmatic control, you can use our APIs.
Refer to the [Create Phone Number API Reference](/api-reference/phone-numbers/create-phone-number) for details on all available parameters.
* Numbers are **yours indefinitely** once purchased.
* Manage your purchased numbers in the [Numbers Dashboard](https://dashboard.sigmamind.ai/app/ai/phone-numbers).
* You can assign **different inbound and outbound agents**.
```sh Purchase New Number theme={null}
curl --location 'https://api.sigmamind.ai/v1/phone-numbers' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: key_C6HL3Goru7Q.TlI5kZOKPmDM03Gt39nRBEnxrL*****************' \
--data '{
"friendlyName": "Inbound Agent 1",
"provider": "telnyx"
}'
```
```sh Bring Your Own Number (BYO) theme={null}
curl --location 'https://api.sigmamind.ai/v1/phone-numbers' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: key_C6HL3Goru7Q.TlI5kZOKPmDM03Gt39nRBEnxrL*****************' \
--data '{
"friendlyName": "Inbound Agent 2",
"phoneNumber": "+14159876543",
"provider": "byo",
"trunkName": "SigmaMing SIP Trunk",
"trunkUsername": "admin",
"trunkPassword": "password",
"terminationSipURI": "sip.telnyx.com"
}'
```
# SIP Integration Overview
Source: https://docs.sigmamind.ai/documentation/phone-number/sip-integration/overview
Learn how to integrate your phone numbers using SIP in SigmaMind.
# SIP Integration with SigmaMind
**SIP (Session Initiation Protocol)** is the backbone of modern voice communication. Using SIP, you can connect phone numbers purchased from external providers (such as Twilio, Vonage, or Telnyx) directly into the **SigmaMind** platform. This enables your AI agents to send and receive calls just like a real human agent.
***
## What is SIP?
SIP (**Session Initiation Protocol**) is a communication protocol used to set up and manage real-time sessions, such as voice and video calls, over the internet.
SIP does not transmit the audio itself. Instead, it handles the signaling — initiating, modifying, and terminating communication sessions. The actual voice data flows over a separate protocol called **RTP (Real-Time Transport Protocol).**
Think of SIP as the *signal* that establishes the call, while RTP is the *data channel* that carries the actual voice.
***
## Key Terms in SIP
Before integrating, here are some common terms you may encounter:
* **SIP Trunking** – A virtual connection that replaces traditional phone lines, enabling multiple calls over the internet.
* **DID (Direct Inward Dialing)** – A virtual phone number assigned to your SIP trunk for inbound calls.
* **VoIP (Voice over IP)** – Technology for transmitting voice over the internet.
* **PBX (Private Branch Exchange)** – A private telephone network within an organization.
* **PSTN (Public Switched Telephone Network)** – The traditional landline network.
* **SIP URI** – An address (e.g., `sip:user@domain.com`) used to identify SIP endpoints.
* **SIP Registrar** – The server that registers your number or device with the SIP network.
* **SIP Proxy** – Routes SIP requests between devices and providers.
You do not need to memorize all these terms. A basic understanding is useful when configuring or troubleshooting SIP.
***
## Why Use SIP with SigmaMind?
SIP integration allows you to bring your own numbers into **SigmaMind**, regardless of which provider you use. With this approach, you can:
* Keep your existing provider (`Twilio`, `Vonage`, `Telnyx`, etc.).
* Import your number into **SigmaMind** via SIP.
* Allow your AI agent to answer inbound calls and make outbound calls.
* Scale without relying on SIM cards or physical telecom hardware.
***
## How SIP Integration Works in SigmaMind
The high-level process looks like this:
1. Purchase a number from a SIP-supported provider.
2. Obtain SIP credentials (domain, username, password, proxy/server details).
3. Configure SIP settings in the SigmaMind Dashboard under [**Phone Numbers**](https://dashboard.sigmamind.ai/app/ai/phone-numbers).
4. SigmaMind connects to your SIP trunk, acting as a virtual softphone.
5. Calls to your number are routed into your AI agent in real time.
Your phone number remains with your provider. SigmaMind only manages the call flow and AI interaction.
***
## Step-by-Step: Integrating SIP Numbers
### 1. Purchase a Number
Obtain a number from a SIP-supported provider such as:
* [Twilio SIP Trunking](https://www.twilio.com/sip-trunking)
* [Vonage SIP](https://www.vonage.com/communications-apis/sip/)
* [Telnyx SIP](https://telnyx.com/products/sip-trunking)
### 2. Collect SIP Credentials
From your provider, gather the following details:
* SIP Domain / Server
* SIP Username
* SIP Password
* SIP Proxy / Registrar (if required)
### 3. Configure in SigmaMind
In the SigmaMind Dashboard:
1. Navigate to [**Phone Numbers**](https://dashboard.sigmamind.ai/app/ai/phone-numbers).
2. Click **Add Phone Number**.
3. Enter the Phone number and SIP credentials provided by your provider.
4. Save the configuration and test the connection.
### 4. Assign Number to an Agent
* Go to [**Phone Numbers**](https://dashboard.sigmamind.ai/app/ai/phone-numbers).
* Select your imported SIP number.
* Assign it to an Inbound AI Agent and Outbound AI Agent.
At this point, your agent is ready to handle inbound and outbound calls using the configured number.
***
## Example: SIP Settings
Example configuration for **Twilio**:
```yaml theme={null}
SIP Domain: your-domain.pstn.twilio.com
Username: your-sip-username
Password: your-sip-password
Proxy/Registrar: sip.twilio.com
Transport: TLS
Port: 5061
```
The exact values will vary depending on your provider. Always confirm with their documentation.
## Troubleshooting
* **401 Unauthorized** – Incorrect username or password.
* **404 Not Found** – Number not configured properly on the provider’s side.
* **One-way audio** – Likely an RTP or firewall issue. Ensure correct media ports are open.
* **Call drops after a few seconds** – Could be caused by NAT issues or SIP session timer settings.
If problems persist, test your credentials with a softphone application such as **Zoiper** or **Linphone**. This helps verify provider setup before connecting with SigmaMind.
## Summary
* SIP is the protocol that connects external phone numbers to SigmaMind.
* Any SIP-supported provider (Twilio, Vonage, Telnyx, etc.) can be used.
* Configure SIP credentials in SigmaMind to integrate your number.
* Once set up, your AI agent can seamlessly handle both inbound and outbound calls.
SIP integration gives you flexibility, scalability, and freedom to choose your telecom provider, while letting SigmaMind power intelligent, AI-driven voice communication.
# Connect via SIP Trunking with Telnyx
Source: https://docs.sigmamind.ai/documentation/phone-number/sip-integration/providers/telnyx
Guide to integrate Telnyx phone numbers with SigmaMind using SIP trunking.
If you own phone numbers in **Telnyx**, you can connect them to **SigmaMind** using Elastic SIP Trunking.
This guide will walk you through creating a SIP trunk in Telnyx and linking it with **SigmaMind**.
## Steps to Integrate
1. **Log in to Telnyx Portal** → [Telnyx SIP Trunking](https://portal.telnyx.com/#/voice/connections).
2. **Create a New Connection**
* Go to **Real-Time Communications -> Voice -> SIP Trunking**.
* Click on **Create SIP Connection**.
* Select **FQDN** as the connection type.
* Name it (e.g., *SigmaMind SIP Trunk*).
3. **Add FQDN**
* In the **FQDN** field, enter:
```
5t4n6j0wnrl.sip.livekit.cloud
```
* Set the **Port** to `5060`.
* Choose the **Transport Protocol** (UDP, TCP, or TLS).
* Enable **SIP over TLS** if using TLS.
4. **Assign Numbers**
* Attach your purchased Telnyx number(s) to this connection.
5. **Termination URI**
* Use the **Termination URI** provided by Telnyx.
6. **Transport & Encryption**
* Allowed Transports: UDP, TCP, TLS.
* Media Encryption: Enable **SRTP**.
7. **Save and Test**
* Save your configuration.
* Place a test call to confirm SIP trunking works.
## Verification
* Ensure the number is visible in your **SigmaMind Dashboard**.
* Assign an **Inbound Agent** to receive calls on this number.
Telnyx offers advanced SIP features such as **mutual TLS** and **static IP auth**.
Since SigmaMind does not currently support static IP whitelisting, use **SIP URI with SRTP** for connectivity.
# Connect via SIP Trunking with Twilio
Source: https://docs.sigmamind.ai/documentation/phone-number/sip-integration/providers/twilio
Guide to integrate Twilio phone numbers with SigmaMind using SIP trunking.
If you own phone numbers in **Twilio**, you can connect them to **SigmaMind** using Elastic SIP Trunking.
This guide will walk you through setting up SIP trunking in Twilio and registering the number in **SigmaMind**.
## Steps to Integrate
1. **Log in to Twilio Console** → [Twilio Elastic SIP Trunking](https://console.twilio.com/dashboard).
2. **Create a New SIP Trunk**
* Go to **Elastic SIP Trunks → Create new SIP Trunk**.
* Give your trunk a descriptive name (e.g., *SigmaMind SIP Trunk*).
3. **Enable Call Transfer**
* In the trunk settings, enable **Call Transfer** to allow inbound calls.
4. **Configure Termination**
* Under **Termination → Termination SIP URI**, enter: unique id
```
sigmamind-sip-trunking
```
5. **Configure Origination**
* Under **Origination → Origination URIs**, Click on `Add new Origination URI` and enter:
```
sip:28y698lhv2f.sip.livekit.cloud
```
6. **Configure Authentication**
* Use **IP Authentication** or **Credential Lists** depending on your setup.
* Ensure that SigmaMind can authenticate calls through Twilio.
* Media Encryption: Enable **SRTP**.
7. **Assign Numbers**
* Attach your purchased Twilio number(s) to the trunk.
8. **Save and Test**
* Save your SIP trunk settings.
* Place a test call from your Twilio number.
***
## Verification
* Ensure the number appears in your **SigmaMind Dashboard** after configuration.
* Assign an **Inbound Agent** to the number to start receiving calls.
If you face connection issues, confirm that:
* Transport protocol matches on both sides.
* SRTP is enabled in Twilio trunk settings.
# SIP Trunking
Source: https://docs.sigmamind.ai/documentation/phone-number/sip-integration/sip-trunking
Step by step guide to understand SIP trunking
## What is SIP Trunking?
**SIP Trunking** is a cloud communication service that allows you to connect your phone numbers from a provider to SigmaMind's SIP infrastructure.
This enables your AI agents to :
* Receive **inbound calls** on your existing numbers.
* Make **outbound calls** using your provider’s numbers.
***
## Prerequisites
Before setting up SIP trunking, ensure the following:
* You have already purchased a number from **Twilio** or **Telnyx**.
* You have access to the provider’s dashboard to configure SIP trunking.
* You have access to **SigmaMind** Dashboard to register and manage numbers.
***
## SigmaMind SIP Trunking Requirements
To connect a number to **SigmaMind**, you will need:
* **SIP Server URI**:\
`sip:28y698lhv2f.sip.livekit.cloud`
* **Transport Methods Supported**:
* UDP
* TCP
* TLS
* **Media Encryption Supported**:
* SRTP
Currently, **SigmaMind** does **not** support static IP whitelisting.\
If your provider requires IP whitelisting, this may not work.
***
### Provider Guides
To set up SIP trunking with your provider, follow the detailed guides:
* [Twilio SIP Trunking Guide](/documentation/numbers/sip-integration/providers/twilio)
* [Telnyx SIP Trunking Guide](/documentation/numbers/sip-integration/providers/telnyx)
# Node logs
Source: https://docs.sigmamind.ai/documentation/playground/analytics/node-logs
# System.logs
Source: https://docs.sigmamind.ai/documentation/playground/analytics/system.logs
# Controls
Source: https://docs.sigmamind.ai/documentation/playground/controls
# Test Chat
Source: https://docs.sigmamind.ai/documentation/playground/llm-playground
Use Chat mode to test text-based conversations with your agent in real time before deployment.
## How to Test in Chat Mode
1. Switch to **Chat** at the top
2. Click on **Manual Chat Conversation**
3. Start typing your message in the input field
4. Click **Send** to interact with the agent
This mode allows you to:
* Manually test conversation flows
* Validate prompts and responses
* Test dynamic variables
* Verify branching logic
* Debug workflow execution
All triggered nodes (Start Trigger, Response Node, Function Calls, etc.) will be displayed in the conversation panel for inspection.
# Playground Overview
Source: https://docs.sigmamind.ai/documentation/playground/overview
Learn how to use the Playground in SigmaMind to test, debug, and verify AI agents across multiple channels.
The **Playground** in SigmaMind AI allows you to test, debug, and analyze your agent in real time - directly inside the Agent Builder.
It simulates live user interactions and shows exactly how your workflow nodes are triggered during a conversation.
## Accessing the Playground
1. Open your agent in **Agent Builder**
2. Select **Playground** from the right-side panel or click on **'Test in Playground'**
You will see:
* **Voice / Chat toggle**
* Conversation window
* Node execution trace
* Test history panel
* Audio playback controls
* Start New Call button
***
# Testing Your Agent
The testing flow in Playground differs depending on whether you are using **Voice** or **Chat** mode.
## Audio Playback & Recording
In **Voice mode**, the Playground provides full audio controls for reviewing test calls.
You can:
* ▶️ Play the recorded conversation
* ⏸ Pause anytime during playback
* ⏩ Adjust playback speed
* ⬇️ Download the call recording
* View total call duration from the timeline
This allows you to:
* Analyze tone and clarity
* Review pauses and response timing
* Validate whisper messages and transfers
* Share recordings for QA or team review
* Perform compliance checks
The playback speed control is especially useful when reviewing longer conversations, allowing you to speed up analysis without missing important details.
***
### Clear & Retest
You can instantly:
* Clear messages
* Start a new call
* Re-run test scenarios
This enables rapid iteration while building your workflow.
***
### Real-Time Debugging
The Playground allows you to:
* Identify which node failed
* Check incorrect branching
* Verify conditions
* Inspect variable replacements
* Confirm action execution
If something is incorrect, you can immediately update the node in the Agent Builder and retest without leaving the Playground.
***
# Why Playground is Important
The Playground helps you:
* Test before going live
* Validate conversation flow
* Debug integrations
* Verify function calls
* Optimize user experience
* Ensure production readiness
It centralizes testing, debugging, and optimization in one place.
***
## Best Practice
Before deploying your agent:
* Test multiple conversation paths
* Trigger all conditional branches
* Validate all integrations
* Review transcripts
* Replay voice recordings
* Confirm successful action execution
Only deploy after full Playground validation.
# Review Test Runs
Source: https://docs.sigmamind.ai/documentation/playground/review-test-runs
# Run Batch Simulations
Source: https://docs.sigmamind.ai/documentation/playground/run-batch-simulations
The **Simulate** tab provides tools to run and evaluate AI agent behavior against predefined test cases. It is divided into two sub-sections: **Test Cases** and **Batch Runs**.
***
## Overview
The LLM Simulation page allows you to:
* Define and manage test cases for your AI agents
* Trigger batch runs that execute multiple test cases simultaneously
* Review results, success/failure status, and detailed remarks for each job
***
## Navigation
The page is accessed via the top navigation bar under the **Simulate** tab (alongside **Build**).
```text theme={null}
Build | Simulate (active)
```
A secondary tab bar within the page switches between:
| Tab | Description |
| -------------- | ------------------------------------------------- |
| **Test Cases** | Create and manage individual simulation scenarios |
| **Batch Runs** | View and manage grouped execution runs |
***
## Batch Runs
### Batch Run List (Left Panel)
The left panel displays all batch runs sorted by creation time. Each entry shows:
* **Batch ID** — a unique identifier (e.g. `batch_Xb1RnQ8vfbE0Ed8b`)
* **Created At** — timestamp of when the batch was created (e.g. `4/18/2026, 4:57:05 AM`)
Clicking a batch run loads its details in the right panel.
### Batch Run Summary (Right Panel — Top)
When a batch run is selected, three summary cards are displayed:
| Metric | Description |
| ----------------------- | ------------------------------------------ |
| **Total Attempts** | Total number of jobs executed in the batch |
| **Successful Attempts** | Number of jobs where `is_success = true` |
| **Failed Attempts** | Number of jobs where `is_success = false` |
**Example:**
```text theme={null}
Total Attempts: 30 Successful Attempts: 17 Failed Attempts: 13
```
***
## Job Results Table
Below the summary cards, a detailed table lists every job in the selected batch run.
### Columns
| Column | Type | Description |
| ------------------ | --------- | ----------------------------------------------------------------------------------------- |
| `Job ID` | string | Unique identifier for the individual job (e.g. `job_h5IDmcZfPRUIGaRv`) |
| `Test Case ID` | string | The test case the job was run against (e.g. `tc_wlKlRIsGjKV9gFDL`) |
| `Chat ID` | string | Identifier of the chat session generated during simulation (e.g. `chat-r5ThYqOTUZpzk8Jl`) |
| `Is Success` | boolean | `true` (green) if the agent met all evaluation criteria; `false` (red) if it did not |
| `Status` | badge | Current state of the job — typically `Completed` |
| `Remarks` | text | AI-generated evaluation summary explaining why the job passed or failed |
| `Created Datetime` | timestamp | When the job was created |
### Success / Failure Badge
The `Is Success` column renders a color-coded badge:
* 🟢 `true` — Agent passed all evaluation criteria
* 🔴 `false` — Agent failed to meet one or more criteria
### Status Badge
The `Status` column shows the current execution state. Common values:
| Status | Meaning |
| ----------- | ---------------------------------- |
| `Completed` | Job finished execution |
| `Running` | Job is currently in progress |
| `Failed` | Job encountered an execution error |
### Remarks
The `Remarks` column contains a natural-language summary of agent performance. Examples:
> "The agent successfully introduced themselves warmly, clearly explained the overdue balance, offered a payment plan in response to the customer's financial difficulty, confirmed the 3-installment option, and closed the conversation by…"
> "The agent acknowledged the customer's time constraints and kept the pitch brief, but failed to effectively execute a micro-close. While the agent did mention the credit impact reminder, it was not integrated naturally into the conversation and…"
Remarks are truncated in the table view. Click a row to view the full remark.
***
## Example Batch Run
Below is a sample from a batch run showing mixed results:
| Job ID | Test Case ID | Is Success | Remarks (summary) |
| ---------------------- | --------------------- | ---------- | ------------------------------------------------------------------------- |
| `job_h5IDmcZfPRUIGaRv` | `tc_wlKlRIsGjKV9gFDL` | ❌ false | Agent failed to complete the primary goal — customer requested a callback |
| `job_nNjj6EgdIyOlqTcb` | `tc_jBuFAVeD0OsSekgW` | ✅ true | Successfully introduced, explained balance, confirmed payment plan |
| `job_hFO6nnPvfw8mGa9c` | `tc_jBuFAVeD0OsSekgW` | ✅ true | Successfully handled objection and confirmed 3-installment option |
| `job_7NknE7cMoPvsppko` | `tc_jBuFAVeD0OsSekgW` | ✅ true | Payment plan confirmed, conversation closed appropriately |
| `job_FMCxaLhVViQj51Kl` | `tc_lDawKCNE05hzUaOv` | ✅ true | Remained empathetic, handled objection twice with different approaches |
| `job_AC59MKlMCJWlLbvS` | `tc_wlKlRIsGjKV9gFDL` | ❌ false | Micro-close failed; credit reminder not integrated naturally |
| `job_KxemQu0GeTC951ao` | `tc_lDawKCNE05hzUaOv` | ❌ false | Failed to provide non-payment alternatives per customer's primary request |
***
## Tips
* Use **Batch Runs** to run large-scale evaluations across many test cases at once.
* Monitor the **Successful / Failed Attempts** summary to quickly gauge agent quality.
* Read **Remarks** carefully — they provide specific, actionable feedback about agent behavior.
* Multiple jobs can share the same `Test Case ID`, allowing you to test consistency across runs.
# Create Test Cases
Source: https://docs.sigmamind.ai/documentation/playground/test-simulations
# Test Voice
Source: https://docs.sigmamind.ai/documentation/playground/test-voice
Use Voice mode to simulate real-time call interactions with your agent before going live.
## How to Test in Voice Mode
1. Switch to **Voice** tab at the top of the Playground
2. Click **Start New Call** at the bottom
3. **Speak** to the agent as a real caller would
4. **Listen** to the agent's responses in real time
***
## After the Call Ends
Once the call completes, you can:
* ▶️ Replay the recording
* ⏩ Adjust playback speed
* ⬇️ Download the audio
* Review node execution logs
***
## Node Execution Trace
Displays the real-time path the agent follows through connected nodes during the call — useful for debugging workflow behavior.
For each step you can see:
* Which node was triggered
* The exact input it received
* The output it generated
* Whether the action executed successfully
Common node types shown:
| Node | Description |
| :------------------- | :------------------------------ |
| `start-trigger-node` | Entry point of the conversation |
| `response-node` | Agent's response step |
| `voice-action-node` | Function or transfer action |
***
## Function Call Logs
When your agent triggers an action (e.g. a transfer or API call), the Playground shows:
* Input payload
* Output response
* Execution status
**Example:**
```text theme={null}
Function Call: VOICE_TRANSFER_CALL (voice-action-node)
Input: { "transfer_to": "+919773216895", "transfer_type": "warm" }
Output: { "response": "Call transferred successfully" }
```
Use this to verify data mapping, variable passing, and integration accuracy.
***
## Test History & Restore
On the right side of the Playground, the **Test History** panel lets you:
* View all previous test sessions
* Click **Restore** to reload a past conversation
* Re-check transcripts and node execution
Useful for debugging previous issues or validating fixes after making changes.
***
## Real-Time Debugging
If something goes wrong during a test, you can immediately:
* Identify which node failed
* Check incorrect branching
* Inspect variable replacements
* Confirm action execution
Fix the node in **Agent Builder** and retest — without leaving the Playground.
***
## Best Practice
Before deploying your agent, make sure to:
* Test multiple conversation paths
* Trigger all conditional branches
* Validate all integrations
* Replay voice recordings
* Confirm all actions execute successfully
Only deploy after full Playground validation.
# System
Source: https://docs.sigmamind.ai/documentation/system/docs
# System
The System section manages platform administration, billing, and configuration settings for your AI agent deployment.
## 1. Billing Usage
Comprehensive billing and usage tracking to monitor costs and optimize resource allocation.
Features include:
* Real-time usage monitoring across all services
* Detailed billing breakdowns by feature and time period
* Cost optimization recommendations
* Usage alerts and spending limits
* Invoice generation and payment processing
* Historical usage trends and forecasting
* Multi-currency support and regional pricing
* Subscription plan management and upgrades
* Credit and discount tracking
* Automated billing notifications and reports
## 2. Settings
Platform configuration and customization options to tailor the system to your organization's needs.
Configuration areas include:
* User account management and permissions
* Organization profile and branding settings
* API keys and integration credentials
* Security settings and access controls
* Notification preferences and alerts
* Data retention and privacy policies
* Backup and disaster recovery settings
* Compliance and regulatory configurations
* Custom domain and white-label options
* Integration webhooks and callbacks
* Default agent behaviors and templates
* System-wide language and localization settings
# Test
Source: https://docs.sigmamind.ai/documentation/test/docs
# Test
The Test section provides comprehensive testing environments to validate your AI agents across different communication channels before deployment.
## 1. Playground
Interactive testing environments for different communication methods to ensure your AI agent performs optimally across all channels.
### 1.1. Voice
Test your AI agent's voice interactions in a simulated environment. This playground allows you to:
* Validate speech recognition accuracy
* Test voice response quality and naturalness
* Simulate phone call scenarios
* Verify voice-specific actions and flows
* Test different accents and speaking patterns
### 1.2. Chat
Simulate text-based conversations with your AI agent. The chat playground enables you to:
* Test conversation flows and logic
* Validate message analysis and responses
* Simulate various customer scenarios
* Test branching and jumping logic
* Verify app and helpdesk actions
### 1.3. Email
Test your AI agent's email handling capabilities. This environment allows you to:
* Validate email parsing and understanding
* Test automated email responses
* Simulate email-based customer service scenarios
* Test email-specific formatting and templates
* Verify integration with email platforms
# How to Add New Integration
Source: https://docs.sigmamind.ai/documentation/tools/add-a-custom-tool
The **Add New Integration** feature lets you integrate external applications or APIs with your **SigmaMind AI** agent by creating custom tool actions. This is especially useful when the application you want to use (such as Zendesk or any other service) is not already available in the SigmaMind AI Marketplace.
By adding a custom tool, you enable your agent to communicate directly with external systems, send and retrieve data, and perform real-world operations automatically during conversations.
You can:
* Add a new custom app
* Create custom tool actions
* Define dynamic input variables
* Test API actions
* Embed and use tools inside your AI agent
This enables your Voice AI agent to perform real-world actions such as booking, rescheduling, fetching data, updating records, and more.
***
## Step 1: Add New Integration
If your app is not available in the marketplace, you can create a custom tool.
### Steps:
1. Open **Agent Builder**
2. Click the **Tool Library**
3. Click **Add New Integration**
4. Enter the following:
| Field | Description |
| :--------------------- | :---------------------------------------------------- |
| App/Integration name | Name of the external app (e.g., Calendly, Custom CRM) |
| Description (Optional) | Description of the tool |
Click **Save Integration**
The newly created custom tool will appear in your **Tool Library**.
***
## Step 2: Configure Authentication
Before creating actions, configure authentication based on the app’s API.
1. Click the app or custom tool that you want to configure authentication for.
2. Click **Configure Authentication**
3. Select the required Auth Type
4. Enter credentials
5. Click **Submit Authentication**
SigmaMind AI will automatically use this authentication in API requests.
For detailed instructions on authentication types and configuration steps, refer to this [How to Configure Authentication](/documentation/tools/authentication)
### 2. Using the API
Create an integration programmatically using the [**Integrations API**](https://docs.sigmamind.ai/api-reference/integrations/create-integration).
### **Field descriptions**
| **Field** | **Required** | **Description** |
| :---------- | :----------- | :--------------------------------------------------------------------- |
| name | **required** | Human-readable name for the integration (e.g. `Stripe`, `HubSpot CRM`) |
| description | **optional** | Short description of what this integration connects to |
shellCopy
```text theme={null}
curl --request POST \
--url https://api.sigmamind.ai/v1/integrations \
--header 'Content-Type: application/json' \
--header 'X-API-Key: ' \
--data '{
"name": "Stripe",
"description": "Payment processing integration"
}'
```
The response contains an `integrationId`. Save it — every subsequent auth and tool call requires it.
# How to Configure Authentication
Source: https://docs.sigmamind.ai/documentation/tools/authentication
## Supported Authentication Types
**SigmaMind AI** provides multiple authentication methods to securely connect external applications. You can select the required authentication type based on the API requirements of the app you are integrating.
### Available Authentication Types
The following authentication types are supported:
* **Bearer Token** – Uses a token generated by the external app (from its API or developer settings) to authenticate requests.
* **API Key** – Uses a key included in headers or query parameters
* **Basic Auth** – Uses a username and password combination
* **No Auth** – Used when no authentication is required
#### **How to Configure Authentication**
Follow these general steps to configure authentication:
1. Open the **Tool Library** section
2. Select the app you want to configure
3. Click **Configure Authentication**
4. Select the required **Auth Type** from the dropdown
5. Enter the required authentication details
6. Click **Submit Authentication**
### Bearer Token
Bearer Token is the most commonly used authentication method for APIs such as [Cal.com](http://Cal.com).
**Configuration Steps:**
1. Select **Bearer Token** from the Auth Type dropdown
2. Enter the token in the **Token** field
3. Click **Submit Authentication**
**Example Header Sent Automatically:**
Authorization: Bearer your\_token
The AI agent will automatically include this token in every API request.
### API Key
Use this method when the API provides an API key for authentication.
**Configuration Fields:**
* **Add to** – Select where the API key should be included:
* Header
* Query Parameter
* **Key Name** – The parameter name defined by the API (e.g., `x-api-key`, `Authorization`, `api_key`)
* **API Key Value** – Your actual API key provided by the service
**Example (Header):**
x-api-key: your\_api\_key
**Example (Query Parameter):**
[https://api.example.com/events?apikey=](https://api.example.com/events?apikey=\{yourapikey})
After clicking **Submit Authentication**, SigmaMind AI securely stores the API key and automatically includes it in all tool action requests.
### Basic Auth
Use Basic Auth when the API requires a username and password combination.
**Configuration Fields:**
* **Username** – Your account username or client ID
* **Password** – Your password or client secret
**Example Header Generated Automatically:**
Authorization: Basic base64\_encoded\_username\_password
Example:
Authorization: Basic YWRtaW46cGFzc3dvcmQ=
After clicking **Submit Authentication**, SigmaMind AI securely stores your credentials and automatically applies authentication to all API calls.
### No Auth
Use this option when:
* The API does not require authentication, or
* Authentication is handled in headers manually inside tool actions
***
### How Authentication Works
Once authentication is submitted:
* Credentials are securely stored
* Authentication headers are automatically included
* Tool actions can access the connected app
Your Voice AI agent can execute API actions securely
### Tool Execution Example
Example: Booking Appointment
User: Book an appointment tomorrow at 10 AM
**What happens internally:**
```text theme={null}
User request → AI detects booking intent → AI extracts date and time → AI selects book_appointment tool → AI replaces input variables in API request → API request sent to external service → External service processes booking → API returns confirmation response → AI receives response → AI generates natural language reply → User receives booking confirmation
```
**Agent Response:**
```text theme={null}
Your appointment has been successfully booked.
```
Some apps include pre-configured actions. For example, Cal. com provides:
* Get available slots
* Book appointment
* Fetch event types
These actions can be directly enabled and used by the Voice AI agent.
### 2. Using the API
If you prefer programmatic control, you can use the [**Integration Auth API**](https://docs.sigmamind.ai/api-reference/integration-auth/create-integration-auth) to configure authentication.
### Field Descriptions
* **authType** → Specifies the authentication method to use (`API_KEY`, `BEARER`, `BASIC`, `NONE`)
* **token** → Required when using Bearer Token authentication
* **username** → Required for Basic Auth (your API username or client ID)
* **password** → Required for Basic Auth (your password or client secret)
* **apiKey** → Required when using API Key authentication
* **key** → The header or query parameter name (e.g., `x-api-key`)
* **value** → The actual API key
* **position** → Specifies where the API key should be included (`header` or `query`)
* **headers** → Optional custom headers that will be included in every request
```sh Create Integration Auth theme={null}
curl --request POST \
--url https://api.sigmamind.ai/v1/integrations/{integrationId}/auth \
--header 'Content-Type: application/json' \
--header 'X-API-Key: ' \
--data '
{
"authType": "API_KEY",
"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"username": "api_user@example.com",
"password": "s3cretP@ssword",
"apiKey": {
"key": "X-API-KEY",
"value": "",
"position": "header"
},
"headers": [
{
"key": "X-Request-Source",
"value": "sigmamind"
}
]
}
'
```
You can also add new tool to existing apps using the Add Tool option. For detailed instructions, see Add a New Integration
# Cal.com
Source: https://docs.sigmamind.ai/documentation/tools/cal-com
# How to Add New Tool
Source: https://docs.sigmamind.ai/documentation/tools/how-to-add-new-tool
Tool actions define what operation the AI agent can perform using the API.
### Steps:
1. Click on **Add New Tool**
2. Enter the following details:
| Field | Description |
| :-------------------- | :-------------------------------------------- |
| Action Name | Name of the action (e.g., Reschedule Booking) |
| Description(Optional) | What the action does |
| Endpoint URL | API endpoint URL |
| Request Method | GET, POST, PUT, DELETE |
| Headers | Required headers from API documentation |
| Body | Request payload |
## Tool Name
**Definition:**\
A unique identifier for the tool action. The agent uses this name internally to trigger the correct API call.
**Requirements:**
* Must be unique
* Use snake\_case format
* No spaces allowed
**Example:**
```text theme={null}
reschedule_booking
```
***
## Description (Optional)
**Definition:**\
Explains when and why the agent should use this action. This helps the AI understand the correct context for calling the API.
**Example:**
```text theme={null}
Use this action to reschedule a Cal.com booking when the user provides a new date and time.
```
***
## HTTP / Request Method
**Definition:**\
Specifies the type of operation to perform on the API.
**Supported methods:**
* GET → Retrieve data
* POST → Create data
* PUT → Update data
* PATCH → Partially update data
* DELETE → Remove data
**Example:**
```text theme={null}
GET
```
***
## Endpoint URL
**Definition:**\
The API endpoint where the request will be sent. You can use input variables to dynamically insert values.
**Static example:**
```text theme={null}
https://api.cal.com/v1/bookings
```
**Dynamic example using input variable:**
```text theme={null}
https://api.cal.com/v1/bookings/{{booking_id}}
```
Here, `{{booking_id}}` will be dynamically provided by the agent.
***
## Headers
**Definition:**\
Headers provide additional information required by the API, such as authentication and content type.
**Common headers example:**
| Key | Value |
| :------------ | :------------------- |
| Content-Type | application/json |
| Authorization | Bearer access\_token |
**Example configuration:**
```text theme={null}
Content-Type: application/json
Authorization: Bearer {{access_token}}
```
***
## Query Parameters
**Definition:**\
Query parameters allow you to filter or modify the API response. These are appended to the endpoint URL.
**Example configuration:**
| Key | Value |
| :----- | :-------------- |
| status | booking\_status |
**Final request example:**
```text theme={null}
https://api.cal.com/v1/bookings?status=upcoming
```
***
## Request Body
**Definition:**\
The request body contains the data sent to the API when creating or updating resources.
You can use input variables to dynamically pass values.
**Example:**
```text theme={null}
{
"start": "{{start_time}}",
"end": "{{end_time}}",
"eventTypeId": "{{event_type_id}}",
"reason": "User requested reschedule"
}
```
***
## Input Variables (Dynamic Placeholders)
Input variables are **dynamic placeholders** written inside double curly braces.
Format:
```text theme={null}
{{variable_name}}
```
These placeholders are replaced with real values **when the agent executes the API request during a conversation**.
The agent determines these values using:
* User input
* Conversation context
* Extracted variables configured in the agent workflow
* Agent configuration
**Examples:**
```text theme={null}
{{booking_id}}
{{start_time}}
{{end_time}}
{{event_type_id}}
{{email}}
```
**Input variables can be used in:**
* Endpoint URL
* Query Parameters
* Request Body
***
## Complete Example: Reschedule Booking (Cal .com)
**Action Name**
```text theme={null}
reschedule_booking
```
**Method**
```text theme={null}
POST
```
**Endpoint URL**
```text theme={null}
https://api.cal.com/v1/bookings/{{booking_id}}/reschedule
```
**Headers**
```text theme={null}
Content-Type: application/json
Authorization: Bearer {{access_token}}
```
## How Input Variables Work
### Conversation Example:
User: I want to reschedule my appointment for tomorrow at 10 AM.
### What SigmaMind AI does:
1. Extracts values from conversation
2. Maps values to variables
3. Replaces variables in the API body
4. Calls the API automatically
### Final API Request Sent:
```text theme={null}
{
"start": "2026-03-10T10:00:00Z",
"end": "2026-03-10T10:30:00Z",
"eventTypeId": "12345",
"reason": "User requested reschedule"
}
```
3. Click **Submit Action**
The action is now available for your agent.
You can add new actions to an existing integration in the App Marketplace in the same way, allowing your AI agent to perform additional operations using the connected app.
## How to Test Tool
You can test a tool action to verify that the API works correctly before using it in your agent.
### Steps:
1. Go to Tool Library from the Agent Builder
2. Select the tool (for example, [Cal.com](http://Cal.com))
3. In the **Tools** section, locate the tool you want to test
4. Click the **Test** button next to the action
This opens the **Mock Test API** screen.
5. Enter test values for the detected input variables (such as `{{start_date}}`, `{{end_date}}`, `{{event_type_id}}`)
6. Click **Run Test**
7. Review the response to confirm the API is working correctly
***
## Step 5: Use the Custom Tool in the Agent
After creating and testing your tool actions, you must add them to your agent. This allows the agent to call the tool during conversations and perform real-world operations.
## Method 1: Go to your Tools Section
1. Find your tool (like `get_available_slots`)
2. Click **Add to Agent**
3. Fill in the **Instructions** — describe when the AI should invoke this tool
4. Bind placeholders (if required) — see the [+Add Mapping](#add-mapping-binding-response-values-as-dynamic-variables) section below
5. Click **Add to Agent** to confirm
## Method 2: Via the Agent Builder
1. Open the **Agent Builder**
2. Click **Add Tool**
3. Click **Add Integration Tool**
4. Select the app you created or configured
5. Select the tool you want the agent to use
6. Click **Add to Agent**
***
## +Add Mapping: Binding Response Values as Dynamic Variables
The **+Add Mapping** feature lets you extract specific fields from a tool's response and save them as named variables. These variables can then be referenced in subsequent prompts or tool inputs using the `{{variable_name}}` syntax.
### Understanding the Sample Response
Click **View sample response (from last run)** to expand a live preview of the JSON returned by the tool. This helps you identify the exact field names to use when configuring mappings.
For example, the `get_customer_list` tool returns a structure like this:
```json theme={null}
{
"contacts": [
{
"vid": 3285518502114,
"addedAt": 1763618783287,
"portal-id": 244418020,
"is-contact": true,
"properties": {
"company": {
"value": "HubSpot"
}
}
}
]
}
```
Use the **Copy JSON** button inside the sample response panel to copy the full response and inspect nested fields before setting up your mappings.
To map a nested field like `company.value`, you would enter `contacts.0.properties.company.value` as the field path in the left input.
***
### How to Configure a Mapping
1. In the tool configuration panel, scroll to **Store response values as dynamic variable**
2. Confirm the **Root path** — this is auto-populated based on the tool name (e.g., `hubspot_get_customer_info`)
3. In the **left field**, enter the field name from the API response (e.g., `user_id`)
4. In the **right field**, the full variable path is auto-generated (e.g., `hubspot_get_customer_info.user_id`)
5. Click **+Add Mapping** to add more fields as needed
6. Use the 🗑 delete icon to remove any unwanted mappings
### Example Mappings for `get_customer_list`
Based on the actual sample response, here are useful field mappings you can configure:
| Field Path | Mapped Variable | Reference in Prompts |
| ------------------------------------- | -------------------------------------- | -------------------- |
| `contacts.0.vid` | `hubspot_get_customer_list.vid` | `{{vid}}` |
| `contacts.0.addedAt` | `hubspot_get_customer_list.addedAt` | `{{addedAt}}` |
| `contacts.0.portal-id` | `hubspot_get_customer_list.portal_id` | `{{portal_id}}` |
| `contacts.0.is-contact` | `hubspot_get_customer_list.is_contact` | `{{is_contact}}` |
| `contacts.0.properties.company.value` | `hubspot_get_customer_list.company` | `{{company}}` |
### Using Variables in Subsequent Steps
Once mapped, reference these variables anywhere in your agent flow:
```text theme={null}
Send an email to {{email}} with a personalized greeting.
Look up account for user ID: {{user_id}}
Pass {{company}} to the CRM update tool input field.
```
Reference these variables as `{{variable_name}}` in any subsequent prompt or tool input field.
***
## Tips & Best Practices
Click **View sample response (from last run)** before adding mappings to confirm exact field names returned by the API. If no sample is available, run the tool once from the Test panel first.
Only map fields you'll actually use in downstream steps. Unused variables add clutter without any benefit.
Ensure consistency between the mapped name and how you reference it in prompts. `{{Email}}` and `{{email}}` are treated as different variables.
The root path prefix (e.g., `hubspot_get_customer_info.`) is automatically prepended. You only need to type the leaf field name (e.g., `user_id`) in the left input field.
***
### 2. Using the API
If you prefer programmatic control, use the [**Integration Tools API**](https://docs.sigmamind.ai/api-reference/integration-tools/create-tool) to create a tool.
### **Field descriptions**
| **Field** | **Required** | **Description** |
| :---------- | :----------- | :----------------------------------------------------------------------------------------------- |
| name | **required** | Unique name for the tool within this integration (e.g. `get-customer`) |
| description | **required** | Natural language description of what the tool does — agents use this to decide when to invoke it |
| method | **required** | HTTP method: `GET`, `POST`, `PATCH`, `PUT`, or `DELETE` |
| url | **required** | Full endpoint URL the tool will call (e.g. `https://api.stripe.com/v1/customers/{id}`) |
| queryParams | **optional** | Array of query parameter definitions — each with `key`, `value`, and `description` |
| bodyParams | **optional** | Object describing the request body schema — used for `POST` / `PATCH` / `PUT` requests |
| headers | **optional** | Array of custom headers to include with every call from this tool, each with `key` and `value` |
```json Add New Tool theme={null}
curl --request POST \
--url https://api.sigmamind.ai/v1/integrations/{integrationId}/tools \
--header 'Content-Type: application/json' \
--header 'X-API-Key: ' \
--data '{
"name": "get-customer",
"description": "Retrieves a customer record by ID from Stripe",
"method": "GET",
"url": "https://api.stripe.com/v1/customers/{customerId}",
"queryParams": [
{
"key": "expand[]",
"value": "subscriptions",
"description": "Expand nested subscription data"
}
],
"headers": [
{
"key": "Stripe-Version",
"value": "2023-10-16"
}
]
}'
```
Example Agent Workflow
1. User: I want to reschedule my appointment
2. Agent collects the required information
3. Agent calls Reschedule Booking action
4. API processes the request
5. Agent confirms the reschedule
Authentication failing: Verify credentials and authentication type
API request failing: Test API action and verify endpoint and headers
***
## Best Practices
* Always follow the API documentation of the external app
* Use clear variable names
* Test actions before enabling
* Configure authentication properly
* Use descriptive action names
# Hubspot
Source: https://docs.sigmamind.ai/documentation/tools/hubspot
# How to Access Tool Library
Source: https://docs.sigmamind.ai/documentation/tools/overview
The **Tool Library** section in **SigmaMind AI** allows you to connect external applications, configure actions, and enable your Voice AI agents to interact with real-world services such as scheduling, CRM, email, and more.
This App Marketplace provides a centralized interface where you can:
* Connect third-party apps
* Configure authentication
* Create and manage tool actions
* Define dynamic variables
* Test API integrations
* Enable actions for Voice AI agents
These integrations allow your AI agent to perform tasks such as booking appointments, retrieving data, sending notifications, and automating workflows.
**How Tool Execution Works**
```text theme={null}
User → AI Agent → Tool Action → External API → Response → AI Agent → User
```
## Accessing Tool Library
To access this section:
1. Open the **Agent Builder**
2. Click **Tool Library** option
3. Browse available integrations or add custom tools
This section allows you to view connected apps, configure authentication, create actions, and manage integrations for your AI agent.
You will see a list of pre-built integrations, such as:
* Cal. com
* Shopify
* Recharge
* HubSpot
* Stripe
* Zoho
* Pipedrive
Each app displays its authentication status and available actions.
**Default Integrations vs Custom Tools**
**Use Default Integrations when:**
• The app is already available ([**Cal.com**](http://Cal.com), **Shopify, HubSpot**, etc.)
• No custom API configuration needed
**Use Custom Tools when:**
• Your app is not listed
• You want to connect internal systems
• You need custom API workflows
## Connecting an App
To connect an app:
1. Select the desired app (e.g., Cal. com)
2. Click **Configure Authentication**
3. Choose an authentication method
4. Enter the required credentials
5. Click **Submit**
Once connected, the app’s actions become available for your AI agent.
# Pipedrive
Source: https://docs.sigmamind.ai/documentation/tools/pipedrive
# Poku Labs
Source: https://docs.sigmamind.ai/documentation/tools/poku-labs
# Recharge
Source: https://docs.sigmamind.ai/documentation/tools/recharge
# Shopify
Source: https://docs.sigmamind.ai/documentation/tools/shopify
# Stripe
Source: https://docs.sigmamind.ai/documentation/tools/stripe
# End Call
Source: https://docs.sigmamind.ai/end-call
The **End Call** tool allows your AI agent to terminate an active call programmatically — cleanly, professionally, and at exactly the right moment. Instead of leaving the call open indefinitely or relying on the customer to hang up, your agent can close the conversation gracefully once its job is done.
***
## Steps to Add
1. Open the **Agent Builder**
2. Click **+ Add Tool**
3. Select **End Call**
4. Fill in the **Instruction** field (described below)
5. Click **Add to Agent**
***
## Configuration Field
### Instruction *(When this tool should be invoked)*
This is the only configuration field for End Call — and it is the most important one.
The Instruction tells the AI agent **exactly when** it should hang up and terminate the call. The agent reads this instruction alongside the conversation context and decides at each turn whether the end condition has been met.
```text theme={null}
Enter instruction on when should AI invoke this tool
```
Write this as a clear, specific trigger condition — not a vague directive. The agent follows the instruction literally, so precision matters.
***
## Why the Instruction Field Matters
Without a well-written instruction, the agent either:
* **Ends calls too early** — cutting off a customer mid-sentence because a vague condition matched prematurely
* **Leaves calls open too long** — the conversation is finished but the agent keeps listening, wasting time and creating an awkward silence
A good instruction defines the **exact state of the conversation** at which hanging up is the right action.
***
## Instruction Writing Guide
### 1. End after task completion
Use this when the agent's primary goal has been accomplished and there is nothing left to do.
```text theme={null}
Call voice_end_call after the customer confirms their policy renewal and you have
provided the confirmation number.
```
```text theme={null}
End the call once the appointment has been successfully booked and the customer
has acknowledged the date and time.
```
```text theme={null}
Hang up after the customer confirms they have received the OTP and no further
assistance is needed.
```
***
### 2. End when the customer declines or is not interested
Use this for outbound calling scenarios — insurance renewals, campaigns, sales calls — where customers may not want to continue.
```text theme={null}
End the call if the customer says they are not interested, asks to be removed
from the list, or says "no thanks", "not now", "don't call again", or similar.
```
```text theme={null}
Call voice_end_call when the customer declines the renewal offer or says they
will call back later.
```
This prevents the agent from continuing to pitch or ask follow-up questions after a clear rejection, which would feel pushy and damage the customer experience.
***
### 3. End when the customer says goodbye
The most natural trigger — the customer signals the conversation is over.
```text theme={null}
End the call when the customer says goodbye, "thank you", "that's all",
"I'm done", or any other closing phrase that signals they are finished.
```
```text theme={null}
Hang up when the customer thanks you and there are no remaining open questions
or pending actions.
```
***
### 4. End when the customer is frustrated or unresponsive
Continuing a conversation with an angry or silent customer makes things worse. A graceful exit is the better outcome.
```text theme={null}
End the call if the customer becomes abusive, repeatedly asks to be left alone,
or is clearly not willing to continue the conversation.
```
```text theme={null}
Call voice_end_call if there is no response from the customer for more than
10 seconds after asking a question twice.
```
***
### 5. End after a successful transfer
Once a transfer has been initiated, the AI has completed its role. You can optionally add a closing line before terminating.
```text theme={null}
After successfully transferring the call to a human agent, end this AI session.
```
> Note: When using **Warm Transfer**, the AI drops off automatically once the bridge is established. Use `voice_end_call` for **Cold Transfer** scenarios or when the transfer fails and the AI needs to close out cleanly.
***
### 6. End on specific call outcomes *(outbound campaigns)*
For outbound calls — renewals, reminders, collections — combine end conditions into a single instruction:
```text theme={null}
End the call in any of the following situations:
- The customer confirms the renewal
- The customer declines the offer
- The customer asks to call back and you have logged the callback request
- The customer is not reachable (voicemail, no answer after greeting)
- The customer has provided all required information
```
***
## Combining Instruction with a Farewell
The `voice_end_call` tool terminates the call. To make the ending feel natural, write your agent's **closing line** in the main system prompt — not in the End Call instruction itself.
**In your main agent prompt:**
```text theme={null}
Before ending the call, always say a closing message such as:
"Thank you for your time. Have a great day!" or
"Your renewal is confirmed. We'll send a confirmation to your email. Goodbye!"
```
**In the End Call instruction:**
```text theme={null}
Call voice_end_call after delivering the closing message and the customer
acknowledges or the conversation reaches a natural stopping point.
```
This separation keeps the agent prompt responsible for **what to say** and the End Call tool responsible for **when to hang up**.
***
## Real-World Examples by Use Case
### Insurance Renewal Bot
```text theme={null}
Call voice_end_call in the following situations:
- The customer confirms the renewal and you have shared the confirmation details
- The customer declines the renewal offer
- The customer says they will call back or need more time
- The customer asks to be removed from the call list
- The customer says goodbye or thanks you and ends the conversation
```
### Appointment Booking Agent
```text theme={null}
End the call after:
- The appointment has been confirmed and the customer has acknowledged the slot
- The customer cancels and no rebooking is requested
- The customer says "that's all" or "I'm done"
```
### Collections / Payment Reminder Agent
```text theme={null}
Call voice_end_call when:
- The customer confirms the payment has been made
- The customer requests a callback and you have recorded the preferred time
- The customer disputes the amount and has been transferred to the billing team
- The customer refuses to engage and asks to end the call
```
### Outbound Survey Agent
```text theme={null}
End the call after the customer completes all survey questions and you have
confirmed their responses. Also end the call if the customer refuses to
participate or asks to opt out at any point.
```
***
## Common Mistakes to Avoid
| Mistake | Why It's a Problem | Better Approach |
| ----------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------ |
| `"End the call when done"` | Too vague — agent doesn't know what "done" means | Define the specific completion state |
| `"End after silence"` | Silence can happen mid-sentence or during thinking | Specify duration: `"no response for 10+ seconds after two prompts"` |
| `"End after saying goodbye"` | Agent may say goodbye before tasks are completed | Add: `"only after all tasks are complete and customer acknowledges"` |
| Not adding End Call at all | Call stays open indefinitely after conversation ends | Always add `voice_end_call` to every agent |
| Multiple conflicting end conditions | Agent may end calls at wrong moments | Order conditions by priority or use clear "any of the following" framing |
***
## Best Practices
* **Always add `voice_end_call` to every agent** — without it, the call will not terminate automatically after the conversation ends
* Write **specific, observable trigger conditions** — the agent needs to match language or conversation state, not guess intent
* **Separate farewell language from the end trigger** — put closing messages in the main prompt, not in this instruction
* For outbound agents, **list multiple end conditions** — customers can end calls in many different ways
* Combine with **voice\_transfer\_call** — if a transfer is attempted and fails, `voice_end_call` ensures the call doesn't stay open in a broken state
* Test end-of-call behavior in the **Test Voice** playground to confirm the agent terminates correctly across different conversation paths
***
## Example Configuration
| Field | Value |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Tool | `voice_end_call` |
| Instruction | End the call after the customer confirms their renewal, declines the offer, says goodbye, or asks to be removed from the call list. |
***
## Troubleshooting
| Issue | Fix |
| --------------------------------- | --------------------------------------------------------------------------------------- |
| Call never ends automatically | Confirm `voice_end_call` is added to the agent and the instruction is filled in |
| Agent ends call too early | Make the instruction more specific — add conditions that must all be true before ending |
| Agent ends call mid-sentence | Loosen the trigger — the current instruction may be matching too broadly |
| Awkward silence before hangup | Add a farewell message in the main agent prompt before the end condition is checked |
| Agent keeps talking after goodbye | Add `"customer says goodbye"` explicitly to the end condition list |
***
# Code Blocks
Source: https://docs.sigmamind.ai/essentials/code
Display inline code and code blocks
## Basic
### Inline Code
To denote a `word` or `phrase` as code, enclose it in backticks (\`).
```
To denote a `word` or `phrase` as code, enclose it in backticks (`).
```
### Code Block
Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language.
```java HelloWorld.java theme={null}
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````md theme={null}
```java HelloWorld.java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
````
# Images and Embeds
Source: https://docs.sigmamind.ai/essentials/images
Add image, video, and other HTML elements
## Image
### Using Markdown
The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
```md theme={null}
```
Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed.
### Using Embeds
To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images
```html theme={null}
```
## Embeds and HTML elements
Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility.
### iFrames
Loads another HTML page within the document. Most commonly used for embedding videos.
```html theme={null}
```
# Markdown Syntax
Source: https://docs.sigmamind.ai/essentials/markdown
Text, title, and styling in standard markdown
## Titles
Best used for section headers.
```md theme={null}
## Titles
```
### Subtitles
Best use to subsection headers.
```md theme={null}
### Subtitles
```
Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right.
## Text Formatting
We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it.
| Style | How to write it | Result |
| ------------- | ----------------- | ----------------- |
| Bold | `**bold**` | **bold** |
| Italic | `_italic_` | *italic* |
| Strikethrough | `~strikethrough~` | ~~strikethrough~~ |
You can combine these. For example, write `**_bold and italic_**` to get ***bold and italic*** text.
You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text.
| Text Size | How to write it | Result |
| ----------- | ------------------------ | ---------------------- |
| Superscript | `superscript` | superscript |
| Subscript | `subscript` | subscript |
## Linking to Pages
You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com).
Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/writing-content/text)` links to the page "Text" in our components section.
Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily.
## Blockquotes
### Singleline
To create a blockquote, add a `>` in front of a paragraph.
> Dorothy followed her through many of the beautiful rooms in her castle.
```md theme={null}
> Dorothy followed her through many of the beautiful rooms in her castle.
```
### Multiline
> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
```md theme={null}
> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
```
### LaTeX
Mintlify supports [LaTeX](https://www.latex-project.org) through the Latex component.
8 x (vk x H1 - H2) = (0,1)
```md theme={null}
8 x (vk x H1 - H2) = (0,1)
```
# Navigation
Source: https://docs.sigmamind.ai/essentials/navigation
The navigation field in docs.json defines the pages that go in the navigation menu
The navigation menu is the list of links on every website.
You will likely update `docs.json` every time you add a new page. Pages do not show up automatically.
## Navigation syntax
Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include `.mdx` in page names.
```json Regular Navigation theme={null}
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "Getting Started",
"pages": ["quickstart"]
}
]
}
]
}
```
```json Nested Navigation theme={null}
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "Getting Started",
"pages": [
"quickstart",
{
"group": "Nested Reference Pages",
"pages": ["nested-reference-page"]
}
]
}
]
}
]
}
```
## Folders
Simply put your MDX files in folders and update the paths in `docs.json`.
For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called `your-page.mdx`.
You cannot use `api` for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level `api` folder for internal server calls. A folder name such as `api-reference` would be accepted.
```json Navigation With Folder theme={null}
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "Group Name",
"pages": ["your-folder/your-page"]
}
]
}
]
}
```
## Hidden Pages
MDX files not included in `docs.json` will not show up in the sidebar but are accessible through the search bar and by linking directly to them.
# Reusable Snippets
Source: https://docs.sigmamind.ai/essentials/reusable-snippets
Reusable, custom snippets to keep content in sync
One of the core principles of software development is DRY (Don't Repeat
Yourself). This is a principle that apply to documentation as
well. If you find yourself repeating the same content in multiple places, you
should consider creating a custom snippet to keep your content in sync.
## Creating a custom snippet
**Pre-condition**: You must create your snippet file in the `snippets` directory.
Any page in the `snippets` directory will be treated as a snippet and will not
be rendered into a standalone page. If you want to create a standalone page
from the snippet, import the snippet into another file and call it as a
component.
### Default export
1. Add content to your snippet file that you want to re-use across multiple
locations. Optionally, you can add variables that can be filled in via props
when you import the snippet.
```mdx snippets/my-snippet.mdx theme={null}
Hello world! This is my content I want to reuse across pages. My keyword of the
day is {word}.
```
The content that you want to reuse must be inside the `snippets` directory in
order for the import to work.
2. Import the snippet into your destination file.
```mdx destination-file.mdx theme={null}
---
title: My title
description: My Description
---
import MySnippet from '/snippets/path/to/my-snippet.mdx';
## Header
Lorem impsum dolor sit amet.
```
### Reusable variables
1. Export a variable from your snippet file:
```mdx snippets/path/to/custom-variables.mdx theme={null}
export const myName = 'my name';
export const myObject = { fruit: 'strawberries' };
```
2. Import the snippet from your destination file and use the variable:
```mdx destination-file.mdx theme={null}
---
title: My title
description: My Description
---
import { myName, myObject } from '/snippets/path/to/custom-variables.mdx';
Hello, my name is {myName} and I like {myObject.fruit}.
```
### Reusable components
1. Inside your snippet file, create a component that takes in props by exporting
your component in the form of an arrow function.
```mdx snippets/custom-component.mdx theme={null}
export const MyComponent = ({ title }) => (
{title}
... snippet content ...
);
```
MDX does not compile inside the body of an arrow function. Stick to HTML
syntax when you can or use a default export if you need to use MDX.
2. Import the snippet into your destination file and pass in the props
```mdx destination-file.mdx theme={null}
---
title: My title
description: My Description
---
import { MyComponent } from '/snippets/custom-component.mdx';
Lorem ipsum dolor sit amet.
```
# Global Settings
Source: https://docs.sigmamind.ai/essentials/settings
Mintlify gives you complete control over the look and feel of your documentation using the docs.json file
Every Mintlify site needs a `docs.json` file with the core configuration settings. Learn more about the [properties](#properties) below.
## Properties
Name of your project. Used for the global title.
Example: `mintlify`
An array of groups with all the pages within that group
The name of the group.
Example: `Settings`
The relative paths to the markdown files that will serve as pages.
Example: `["customization", "page"]`
Path to logo image or object with path to "light" and "dark" mode logo images
Path to the logo in light mode
Path to the logo in dark mode
Where clicking on the logo links you to
Path to the favicon image
Hex color codes for your global theme
The primary color. Used for most often for highlighted content, section
headers, accents, in light mode
The primary color for dark mode. Used for most often for highlighted
content, section headers, accents, in dark mode
The primary color for important buttons
The color of the background in both light and dark mode
The hex color code of the background in light mode
The hex color code of the background in dark mode
Array of `name`s and `url`s of links you want to include in the topbar
The name of the button.
Example: `Contact us`
The url once you click on the button. Example: `https://mintlify.com/docs`
Link shows a button. GitHub shows the repo information at the url provided including the number of GitHub stars.
If `link`: What the button links to.
If `github`: Link to the repository to load GitHub information from.
Text inside the button. Only required if `type` is a `link`.
Array of version names. Only use this if you want to show different versions
of docs with a dropdown in the navigation bar.
An array of the anchors, includes the `icon`, `color`, and `url`.
The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor.
Example: `comments`
The name of the anchor label.
Example: `Community`
The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in.
The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color.
Used if you want to hide an anchor until the correct docs version is selected.
Pass `true` if you want to hide the anchor until you directly link someone to docs inside it.
One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
Override the default configurations for the top-most anchor.
The name of the top-most anchor
Font Awesome icon.
One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin"
An array of navigational tabs.
The name of the tab label.
The start of the URL that marks what pages go in the tab. Generally, this
is the name of the folder you put your pages in.
Configuration for API settings. Learn more about API pages at [API Components](/api-playground/demo).
The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url
options that the user can toggle.
The authentication strategy used for all API endpoints.
The name of the authentication parameter used in the API playground.
If method is `basic`, the format should be `[usernameName]:[passwordName]`
The default value that's designed to be a prefix for the authentication input field.
E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`.
Configurations for the API playground
Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple`
Learn more at the [playground guides](/api-playground/demo)
Enabling this flag ensures that key ordering in OpenAPI pages matches the key ordering defined in the OpenAPI file.
This behavior will soon be enabled by default, at which point this field will be deprecated.
A string or an array of strings of URL(s) or relative path(s) pointing to your
OpenAPI file.
Examples:
```json Absolute theme={null}
"openapi": "https://example.com/openapi.json"
```
```json Relative theme={null}
"openapi": "/openapi.json"
```
```json Multiple theme={null}
"openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]
```
An object of social media accounts where the key:property pair represents the social media platform and the account url.
Example:
```json theme={null}
{
"x": "https://x.com/mintlify",
"website": "https://mintlify.com"
}
```
One of the following values `website`, `facebook`, `x`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news`
Example: `x`
The URL to the social platform.
Example: `https://x.com/mintlify`
Configurations to enable feedback buttons
Enables a button to allow users to suggest edits via pull requests
Enables a button to allow users to raise an issue about the documentation
Customize the dark mode toggle.
Set if you always want to show light or dark mode for new users. When not
set, we default to the same mode as the user's operating system.
Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example:
```json Only Dark Mode theme={null}
"modeToggle": {
"default": "dark",
"isHidden": true
}
```
```json Only Light Mode theme={null}
"modeToggle": {
"default": "light",
"isHidden": true
}
```
A background image to be displayed behind every page. See example with
[Infisical](https://infisical.com/docs) and [FRPC](https://frpc.io).
# Examples
Source: https://docs.sigmamind.ai/examples
# Examples
## Cards in a column layout
This is an example of a card with an icon and a link. Clicking on this card brings you to the Columns page.
This is an example of a card with an icon and a link. Clicking on this card brings you to the Columns page.
This is an example of a card with an image.
☝️ Welcome to the content that you can only see inside the first tab.
You can add any number of components inside of tabs. For example, a code block:
```java HelloWorld.java theme={null}
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
✌️ Here's content that's only inside the second tab.
This one has a icon!
💪 Here's content that's only inside the third tab.
# Extract Dynamic Variables
Source: https://docs.sigmamind.ai/extract-dynamic-variable
The **Extract Dynamic Variables** tool captures specific values spoken by the customer during a live call and stores them as named variables. Once captured, these variables are available as `{{variable_name}}` in any tool or prompt within the same agent — no manual mapping required.
> Extracted variables are available as `{{variable_name}}` in any tool or prompt in this agent.
***
## When to Use
Configure this tool when your agent needs to:
* Capture a customer's name, email, or phone number from conversation
* Store a policy number, account ID, or booking reference before an API call
* Record a preferred date, time, or department for downstream routing
* Save any value the customer provides that another tool will need later
***
## Steps to Add
1. Open the **Agent Builder**
2. Click **+ Add Tool**
3. Select **Extract Dynamic Variables** from the tool menu
4. A configuration modal will appear — fill in all fields (described below)
5. Click **Add to Agent**
***
## Configuration Fields
### Instruction *(When this tool should be invoked)*
Write a clear instruction that tells the AI agent when to trigger the extraction. The agent reads this and decides at each turn of the conversation whether the condition has been met.
```text theme={null}
Invoke this tool after the user provides their name and address.
```
```text theme={null}
Extract variables once the customer confirms their policy number and preferred callback time.
```
Be specific about what the customer must have said before extraction happens. Vague instructions like *"extract when needed"* cause the tool to fire at the wrong moment.
***
### Variables
Each variable you want to capture is defined as a row with three fields:
#### `variable_name`
The identifier you will use to reference this value everywhere else in the agent. Must be in `snake_case` with no spaces.
```text theme={null}
customer_name
policy_number
preferred_date
callback_number
vehicle_type
```
Use descriptive names that clearly state what value is stored. Avoid short or ambiguous names like `val1` or `x` — they become confusing when used across multiple tools.
#### Datatype
The expected format of the captured value. Selecting the correct datatype helps the agent extract and validate the value accurately.
| Datatype | Description | Example |
| --------- | ---------------------------------- | ----------------------------- |
| `string` | Any text value | `"John Smith"`, `"POL-98271"` |
| `number` | Numeric value (integer or decimal) | `1200`, `3.5` |
| `date` | A calendar date | `"2026-06-10"` |
| `boolean` | True or false | `true`, `false` |
When in doubt, use `string` — it is the most flexible and works for most values including phone numbers, IDs, and reference codes.
#### What this captures *(description)*
A short, plain-language description of exactly what this variable should contain. The agent uses this description to understand what to listen for in the conversation.
```text theme={null}
caller's name
customer's 10-digit policy number
preferred callback date
vehicle make and model
whether the customer agreed to the renewal
```
Write this as if you are explaining it to someone who doesn't know the product. The clearer this is, the more accurately the agent extracts the right value.
***
### Adding Multiple Variables
Click **+ Add variable** to add more rows. Each row captures a different value from the conversation. You can add as many variables as needed in a single tool call.
For example, an insurance renewal agent might capture all of the following in one extraction:
| variable\_name | Datatype | What this captures |
| ------------------- | -------- | ---------------------------------------------- |
| `customer_name` | string | caller's full name |
| `policy_number` | string | 8-digit policy reference number |
| `vehicle_reg` | string | vehicle registration plate |
| `renewal_confirmed` | boolean | whether the customer agreed to renew |
| `preferred_payment` | string | preferred payment method (card, bank transfer) |
***
## Variable Format
Once defined, variables are referenced using double curly braces throughout the agent:
```text theme={null}
{{variable_name}}
```
They work anywhere inside the agent — in prompts, in tool instructions, in API endpoint URLs, in request body fields, and in header values.
**In a prompt:**
```text theme={null}
You are speaking with {{customer_name}}. Their policy number is {{policy_number}}.
```
**In an API endpoint URL:**
```text theme={null}
https://api.example.com/policies/{{policy_number}}
```
**In a request body:**
```json theme={null}
{
"name": "{{customer_name}}",
"policy": "{{policy_number}}",
"renewal": {{renewal_confirmed}}
}
```
***
## Extraction Timing
The agent extracts variables at the moment the instruction condition is met — not before. This means:
* The agent listens through the conversation normally
* When the trigger condition is satisfied (e.g., customer provides their name), the tool fires
* Extracted values are immediately available to all subsequent tools and prompts in the agent
Configure the Instruction carefully to ensure extraction happens at the right point — after the customer has provided the value, not before.
***
## Real-World Example
**Scenario:** An outbound insurance renewal agent that needs to confirm the customer's identity and capture their renewal decision before making an API call.
**Instruction:**
```text theme={null}
Invoke this tool after the customer confirms their name and policy number,
and has given a clear yes or no to the renewal offer.
```
**Variables:**
| variable\_name | Datatype | What this captures |
| ------------------ | -------- | ----------------------------------------- |
| `customer_name` | string | customer's full name as stated |
| `policy_number` | string | policy reference number (e.g., POL-XXXXX) |
| `renewal_decision` | boolean | whether the customer agreed to renew |
**Conversation flow:**
```text theme={null}
Agent: "Can I confirm your name and policy number?"
Customer: "Yes, I'm Priya Sharma. Policy number POL-44821."
Agent: "Would you like to renew your policy for another year?"
Customer: "Yes, please go ahead."
→ voice_extract_dynamic_variables fires
→ customer_name = "Priya Sharma"
→ policy_number = "POL-44821"
→ renewal_decision = true
→ Next tool (API call) uses {{customer_name}} and {{policy_number}} to update the system
```
***
## Best Practices
* Use `snake_case` for all variable names — no spaces, hyphens, or capital letters
* Write specific **What this captures** descriptions — the agent reads these literally to know what to listen for
* Add all related variables in a single tool rather than creating multiple extraction tools for the same conversation segment
***
## Troubleshooting
| Issue | Fix |
| ----------------------------------- | -------------------------------------------------------------------------------- |
| Variable not being extracted | Make the Instruction more specific — add explicit trigger phrases |
| Wrong value captured | Improve the **What this captures** description to be more precise |
| Variable shows as empty in API call | Check that the extraction tool runs before the API tool in the conversation flow |
| Agent extracts too early | Tighten the Instruction to require more of the conversation to complete first |
***
## Combining with Other Tools
| | How Variables Flow |
| ------------------------ | --------------------------------------------------------------------- |
| **Transfer Call** | Pass `{{customer_name}}` and context in Whisper Message |
| **Add Integration Tool** | Use `{{policy_number}}` or `{{customer_id}}` in API endpoint and body |
| **Navigate IVR** | Route using extracted `{{department_preference}}` |
| **End Call** | Reference extracted confirmation to decide when to close |
# Five9 Integration Guide
Source: https://docs.sigmamind.ai/five9-integration-guide
Connect Five9 to the SigmaMind Voice AI platform. Five9 dials your customers, bridges each answered call to a SigmaMind AI agent in real time, and hands qualified calls back to a live Five9 agent with full context.
## How It Works
```text theme={null}
Five9 Campaign dials customer
│
Customer answers
│
Five9 IVR Script runs (3rd Party Transfer module)
│
Five9 transfers the call to the SigmaMind SIP server
(+1XXXXXXXXXX@28y698lhv2f.sip.livekit.cloud)
│
SigmaMind receives inbound SIP call
│
SigmaMind Voice AI Agent speaks with the customer
│
AI qualifies the lead
│
Call handed back to a Five9 agent (Skill / ACD queue)
│
Agent resumes the conversation with full context
```
Unlike VICIdial, Five9 is a closed cloud contact center — you do not configure an Asterisk dialplan or a Remote Agent. Instead, the handoff to SigmaMind is performed by a **3rd Party Transfer** module inside a Five9 **IVR Script**, and the handoff back to a human agent is performed either by Five9 reclaiming the call (`Return After 3rd Party Call`) or by SigmaMind transferring into a Five9 inbound number. Both patterns are covered below.
On the SigmaMind side, only one inbound SIP call is ever visible — exactly as with VICIdial.
The number used in the Five9 transfer is the number you register in SigmaMind under **Phone Numbers → Connect via SIP Trunking**, entering your carrier or trunk's SIP termination URI in the **Terminal URI** field and mapping an AI agent against it. SigmaMind identifies the correct tenant and AI agent by matching the incoming call's number against the number you registered.
***
## SigmaMind SIP Server Details
All calls from Five9 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 the number Five9 will transfer the call to — the same number you register in SigmaMind under **Phone Numbers → Connect via SIP Trunking**, where:
* **Phone Number** = the number Five9 dials when it hands the call to SigmaMind
* **Terminal URI** = your carrier or trunk's SIP termination URI (e.g. `f111.dialmake.com`) — this points **back to your telephony provider / trunk**, not to SigmaMind
The SigmaMind SIP server (`28y698lhv2f.sip.livekit.cloud`) is what **Five9 transfers into** — it belongs in your Five9 routing only, not in this SigmaMind dashboard field.
SigmaMind does **not** support static IP whitelisting on its global SIP endpoint. Five9 requires IP-anchored connectivity for direct SIP trunks, so production Five9 deployments use one of the connection methods described next. See the [SIP Trunking page](/documentation/phone-number/sip-integration/sip-trunking) for full SIP server requirements.
***
## Choose Your Connection Method
Because Five9 is a managed cloud platform, the call has to physically reach the SigmaMind SIP server through one of two paths. Pick the one that matches your deployment.
### Method A — Dedicated SIP trunk via Five9 Point of Presence (recommended for production)
SigmaMind connects to your Five9 environment over a dedicated SIP trunk peered with the Five9 **Point of Presence (PoP)** serving your account. This keeps call media on a single, direct SIP path — no third-party carrier hop in the middle — which gives the lowest latency, the cleanest audio for the AI, and a static, allowlistable connection that passes enterprise security review.
Dedicated PoP trunking is provisioned with assistance from SigmaMind. To set it up, contact SigmaMind support and your Five9 specialist. Provisioning involves cross-allowlisting between the Five9 PoP and SigmaMind's regional SIP endpoints and is coordinated by both teams. Availability depends on the Five9 PoP region serving your account.
Use this method when:
* You are running production traffic at volume.
* Your security team requires static IP allowlisting for SIP.
* You want to avoid per-minute carrier charges on the AI leg.
### Method B — SIP trunk via your own carrier (Twilio / Telnyx Elastic SIP)
You front SigmaMind with an Elastic SIP Trunk on a carrier that SigmaMind already supports (Twilio or Telnyx). Five9 transfers the call to a number on that trunk, and the trunk's **Origination URI** forwards the call into the SigmaMind SIP server. This is the fastest way to get a working proof of concept and requires nothing special on the Five9 side beyond a standard transfer.
Use this method when:
* You are building a pilot or proof of concept.
* You do not yet need a dedicated PoP trunk.
* You already operate a Twilio or Telnyx SIP trunk.
With Method B, the carrier (Twilio/Telnyx) sits in the path as the SIP gateway. Configure its **Origination URI** to `sip:28y698lhv2f.sip.livekit.cloud` so inbound calls reach SigmaMind, and enable **SRTP**. See the [Twilio SIP Trunking guide](/documentation/phone-number/sip-integration/providers/twilio) or [Telnyx SIP Trunking guide](/documentation/phone-number/sip-integration/providers/telnyx).
***
## Prerequisites
Before starting, confirm you have the following ready:
* Admin access to your Five9 **VCC Administrator** (Campaigns, IVR Scripts, Skills, Connectors).
* A SigmaMind account with at least one AI agent configured and published.
* A connection method selected (Method A or Method B above), and the corresponding trunk provisioned:
* **Method A** — a dedicated PoP trunk arranged with SigmaMind support and your Five9 specialist.
* **Method B** — a Twilio or Telnyx Elastic SIP Trunk with its Origination URI pointed at `sip:28y698lhv2f.sip.livekit.cloud` and SRTP enabled.
* The number Five9 will transfer to, **registered in SigmaMind** under **Phone Numbers → Connect via SIP Trunking**, with an AI agent mapped against it.
* The **SigmaMind SIP server**: `28y698lhv2f.sip.livekit.cloud`.
* Your Five9 **Campaign** type confirmed (Outbound: Predictive / Power / Progressive / Preview).
* A Five9 **Skill / ACD queue** for the human agents who will take qualified transfers.
**Testing from outside the US:** If you are testing from a region with strict telecom geofencing, your local carrier may block calls to or from US numbers. Use a softphone (such as Zoiper) registered to your trunk to place a test call into the SigmaMind SIP server directly, bypassing carrier-level restrictions. See [Testing with a Softphone](#testing-with-a-softphone) below.
***
## Before You Begin: Register Your Number in SigmaMind
Before configuring Five9, register the number Five9 will transfer to 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** | The number Five9 will transfer to (e.g. `+13453453453`) |
| **Terminal URI** | Your carrier or trunk's SIP termination URI (e.g. `f111.dialmake.com`) — 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 or trunk — it is the address used to terminate SIP calls when the AI agent transfers a call back out. It is **not** the SigmaMind SIP server. The SigmaMind SIP server (`28y698lhv2f.sip.livekit.cloud`) is what Five9 transfers into — it belongs in your Five9 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 Five9.
***
## Step 1: Create the Inbound IVR Script in Five9
In Five9, the decision to send an answered customer to SigmaMind is made by an **IVR Script** bound to your campaign. The module that performs the handoff is the **3rd Party Transfer** module.
In the Five9 VCC Administrator, go to **IVR Scripts** and create a new script (e.g. `SigmaMind-FirstTouch`).
Add a **Query** module that calls the SigmaMind API to register a correlation reference for this call. Configure an **Authorization Profile** for your SigmaMind API key, set the request body to include a correlation ID and the caller's ANI, and parse the response into IVR variables using a RegEx function.
This step lets you fetch the AI's outcome later (see Step 5) to drive the handoff-back decision and the agent screen pop.
Drag a **3rd Party Transfer** module onto the canvas. This is the module that hands the customer to SigmaMind.
Configure the destination:
* **Method A (dedicated PoP trunk):** set the **3rd party number** to the SigmaMind number you registered. The number must be registered with Five9 so the call egresses over the dedicated SIP trunk (rather than the public PSTN).
* **Method B (carrier trunk):** set the **3rd party number** to the DID on your Twilio/Telnyx trunk whose Origination URI forwards to `sip:28y698lhv2f.sip.livekit.cloud`.
Select the **Send Data to 3rd Party** checkbox and choose the **KVList** variable that holds the lead fields you want to pass to SigmaMind. Five9 serializes this list into custom SIP headers on the transfer.
Name your keys with an `X-` prefix (e.g. `X-first_name`, `X-city`) so SigmaMind exposes them as dynamic variables — see Step 3.
If you want Five9 to take the customer back after the AI finishes and route to a human agent itself (the recommended handoff pattern — see Step 5, Option A), select the **Return After 3rd Party Call** checkbox. When the AI ends its leg, control returns to this IVR script at the node after the transfer.
Leave this **unchecked** if you instead want SigmaMind to perform the transfer to a Five9 agent (Step 5, Option B).
Save the script.
***
## Step 2: Bind the Campaign
Connect the IVR Script to the campaign that dials your customers.
Go to **Campaigns** and open the outbound campaign that will dial your list (Predictive, Power, Progressive, or Preview).
Configure the campaign so that connected (answered) calls are routed to the `SigmaMind-FirstTouch` IVR Script you created in Step 1.
Set the **Caller ID** customers will see. For initial testing, use conservative dial pacing and increase it only after confirming the end-to-end flow.
Save the campaign.
***
## Step 3: Pass Lead Data via SIP Headers (Optional but Recommended)
You can pass Five9 lead fields — customer name, city, state, phone number, account ID — 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. This is the same mechanism used in the VICIdial integration.
### 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 Five9
Five9 sends custom SIP headers when **Send Data to 3rd Party** is enabled on the 3rd Party Transfer module (Step 1). The headers come from the **KVList** variable you select.
**Part A — Test with a static value first**
In your IVR Script, populate the KVList with a single static key whose name starts 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 Five9 lead/contact field variables in the KVList. Common fields you may want to pass:
```text theme={null}
X-first_name: [Five9 contact field]
X-last_name: [Five9 contact field]
X-city: [Five9 contact field]
X-state: [Five9 contact field]
X-phone_number: [Five9 contact 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. Keep the KVList lean; pass a correlation ID and the few fields the agent needs, and fetch anything larger over the API. 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 4: Configure the AI Agent's Conversation and Qualification
In SigmaMind, your AI agent handles the first-touch conversation: qualifying the lead, collecting information, answering questions, and deciding whether a human is needed.
Write the agent's system prompt to qualify the lead against your criteria and to commit the qualification outcome (for example, by calling a tool or webhook) before the conversation ends.
* **For Option A (Five9 reclaims the leg):** the agent should end its own leg cleanly when finished (using the **End Call** voice action). This is what triggers Five9's `Return After 3rd Party Call` to resume.
* **For Option B (AI transfers to a Five9 agent):** the agent should invoke the **Transfer Call** voice action toward your Five9 inbound number (see Step 5, Option B).
Ensure the qualification result is written back (via the SigmaMind API or a webhook) immediately before the agent ends or transfers, so the data is available to Five9 for routing and the agent screen pop.
***
## Step 5: Configure the Handoff Back to a Five9 Agent
When the AI qualifies the call, it needs to reach a live Five9 agent. There are two patterns. Choose one based on whether you want Five9 or SigmaMind to own the handoff.
### Option A — Return After 3rd Party Call (recommended)
Five9 keeps ownership of the customer the entire time and takes the call back after the AI finishes. This is the cleanest pattern: no second call leg is created, and it works natively within Five9's routing.
In the 3rd Party Transfer module (Step 1), confirm **Return After 3rd Party Call** is checked.
After the transfer node, add a **Query** module that calls the SigmaMind API to retrieve the qualification outcome for this call (using the correlation reference you set in Step 1). Parse the result into IVR variables.
Add a **Case** module that branches on the qualification result — for example, `qualified` vs `not_qualified`.
For qualified calls, add a **Skill Transfer** module that routes the customer into the appropriate **Skill / ACD queue**. Five9 assigns the call to an available agent, and the call variables you populated (summary, intent, lead fields) appear in the agent's **screen pop**.
For non-qualified outcomes, disposition the call appropriately (e.g. end the call, schedule a callback, or add to a Do Not Call list).
### Option B — SigmaMind transfers to a Five9 inbound number
SigmaMind performs the transfer itself by dialing a Five9 inbound number (DNIS) that lands in a Five9 inbound campaign. Use this when you want a spoken, consultative (warm) handoff where the AI briefs the agent before connecting, or when `Return After 3rd Party Call` is not used.
Create an **Inbound Campaign**, bind it to an inbound IVR Script, and set its **DNIS** to the number SigmaMind will dial. The inbound IVR Script routes the call into your **Skill / ACD queue**.
In your AI agent, configure the **Transfer Call** voice action with the Five9 inbound number in E.164 format as the destination. Choose:
* **Cold transfer** — the AI connects the customer to the queue and exits.
* **Warm transfer** — the AI connects the agent first, plays a whisper message summarizing the call, then bridges the customer.
In the inbound IVR Script, add a **Query** module to fetch the AI's summary from SigmaMind (by correlation reference or ANI) and populate call variables for the agent screen pop, then route via **Skill Transfer**.
Both options deliver the AI's qualification and summary to the agent through Five9 **call variables** rendered in the **Agent Desktop screen pop**. The voice path carries a correlation reference; the rich summary is fetched from the SigmaMind API. Do not attempt to pass a full transcript through SIP headers.
***
## Step 6: Test the Integration End-to-End
Run the outbound campaign against a single test lead, or place a test call through your trunk. Answer on your test phone.
Your SigmaMind AI agent should begin speaking shortly after you answer. Speak a response and confirm the conversation flows naturally in both directions.
After the call, go to **Conversations → \[the call] → Dynamic Variables** in SigmaMind and confirm the lead fields you passed via SIP headers appear.
Trigger a qualifying outcome and confirm the call reaches a Five9 agent:
* **Option A:** confirm the IVR resumes after the AI ends, the Case branch routes to the Skill, and an agent rings with the screen pop populated.
* **Option B:** confirm the AI transfers to the Five9 inbound number, the whisper plays to the agent (warm), and the customer is bridged.
Confirm the call appears in SigmaMind **Conversations** (with transcript and recording) and in your Five9 reporting (with the agent disposition).
***
## Testing with a Softphone
If you are testing from a region where carrier-level geofencing prevents calls to or from US numbers, use a softphone registered to your trunk to dial the SigmaMind SIP server directly. This confirms SigmaMind picks up and the AI responds without needing a full Five9 campaign dial.
**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 trunk (Twilio/Telnyx for Method B, or the dedicated trunk for Method A), using the credentials your trunk provides.
Dial the registered SigmaMind number through the trunk so the call routes to `28y698lhv2f.sip.livekit.cloud`. Confirm SigmaMind picks up and the AI agent responds.
***
## Troubleshooting
### 1. The transferred call does not reach SigmaMind
* Confirm the **3rd party number** in the 3rd Party Transfer module matches the number registered in SigmaMind under **Phone Numbers → Connect via SIP Trunking**, and that an active, published AI agent is mapped against it.
* **Method A:** confirm the number is registered with Five9 so the call egresses over the dedicated SIP trunk, not the public PSTN.
* **Method B:** confirm the carrier trunk's **Origination URI** is `sip:28y698lhv2f.sip.livekit.cloud` and that **SRTP** is enabled.
* Go to **Conversations** in SigmaMind — if the call appears there, the SIP connection is working and the issue is on the SigmaMind agent configuration side.
### 2. The customer hears ringing or silence before the AI speaks
* A brief delay can occur while Five9 establishes the transfer leg. Because Five9 confirms a live answer before running the IVR Script, the customer should not experience a long wait, but verify your campaign's answer-detection settings.
* If silence persists, check codec and media settings on the trunk — prefer **G.711 µ-law** end to end to avoid transcoding.
### 3. 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 from Five9. Confirm **Send Data to 3rd Party** is enabled and the correct **KVList** is selected.
* Confirm the header name starts with `X-` — SigmaMind only processes headers with this prefix.
* The variable name in SigmaMind is the header name with `X-` stripped (e.g. `X-city` becomes `{{city}}`).
* Variables only appear in **Conversations → Dynamic Variables** if they are referenced in the agent prompt. Add `{{city}}` to the agent prompt and re-test.
### 4. The AI finishes but Five9 does not route to an agent (Option A)
* Confirm **Return After 3rd Party Call** is checked on the 3rd Party Transfer module.
* Confirm the AI agent ends its own leg cleanly (using the **End Call** voice action) — this is what triggers the return.
* Confirm the **Query** module after the transfer successfully retrieves the outcome, and that the **Case** module branches to the **Skill Transfer**.
* Confirm the qualification outcome was committed by the agent before it ended (Step 4).
### 5. The agent receives no context on screen pop
* Confirm the outcome/summary was written back to SigmaMind before the AI ended or transferred.
* Confirm the **Query** module populates the Five9 call variables that your Agent Desktop screen pop is configured to display.
* Confirm the correlation reference matches on both sides.
### 6. Call completes but no record appears in SigmaMind Conversations
* Confirm the transferred-to number 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.
***
## How Call Transfers Work
SigmaMind handles transfers natively. The behavior depends on which handoff option you configured:
* **Option A (Return After 3rd Party Call):** the AI ends its leg, and Five9 — which kept ownership of the customer the whole time — resumes its IVR Script and routes the customer to a Skill/agent. No second call leg is created, and the customer experiences a seamless continuation.
* **Option B (AI-initiated transfer):** the AI dials your Five9 inbound number and connects the customer (cold), or briefs the agent and then bridges the customer (warm). Your existing caller ID and trunk remain in the path.
In both cases the human agent resumes the conversation with the AI's qualification and summary available on screen.
***
## How Multiple Agents Work
To route different Five9 campaigns to different SigmaMind AI agents:
1. In SigmaMind, go to **Phone Numbers → Connect via SIP Trunking** and register a separate number for each campaign, entering the Terminal URI for each, and mapping each to the correct AI agent.
2. In Five9, create a separate IVR Script (or a separate 3rd Party Transfer destination) per campaign, transferring to the corresponding registered number.
3. Bind each IVR Script to the relevant campaign.
Each campaign routes through its own transfer destination, which reaches SigmaMind on its own registered number, which connects the corresponding AI agent.
***
## Architecture Reference
### Component Map
| Component | Role |
| ------------------------ | ---------------------------------------------------------------------------------------- |
| **Five9 Campaign** | Dials the customer list, manages pacing and answer detection |
| **Five9 IVR Script** | Decides routing; runs the 3rd Party Transfer to SigmaMind and the handoff-back logic |
| **3rd Party Transfer** | Hands the answered customer to the SigmaMind SIP server; sends lead data via SIP headers |
| **SigmaMind SIP Number** | Inbound entry point — mapped to a specific AI agent |
| **SigmaMind Agent** | The AI voice agent that speaks with the customer and qualifies the lead |
| **SIP Headers (X-)** | Carry lead data from Five9 to SigmaMind as dynamic variables |
| **Query / Case modules** | Fetch the AI outcome and branch on it for the handoff-back |
| **Skill Transfer** | Routes a qualified customer into a Five9 Skill / ACD queue |
| **Call Variables** | Deliver the AI's summary to the agent's Agent Desktop screen pop |
### Reference Values
| Value | Purpose |
| ------------------------------- | --------------------------------------------------------------- |
| `28y698lhv2f.sip.livekit.cloud` | SigmaMind SIP server hostname |
| `X-` prefix | Marks a SIP header for exposure as a SigmaMind dynamic variable |
### Connection Method Summary
| Method | Path | Best for |
| ------------------------------- | --------------------------------- | ------------------------------------------- |
| **A — Dedicated PoP SIP trunk** | Five9 PoP ⇄ SigmaMind (direct) | Production, security review, lowest latency |
| **B — Carrier Elastic SIP** | Five9 → Twilio/Telnyx → SigmaMind | Pilots, proofs of concept, existing trunks |
### Call Recording
| Side | What is recorded | When recording starts |
| ------------- | --------------------------------- | -------------------------------------------- |
| **Five9** | Full call per your Five9 settings | When the campaign places the outbound call |
| **SigmaMind** | Agent conversation only | When the SigmaMind AI agent connects via SIP |
Both recordings are independent. Five9's recording is useful for diagnosing routing or bridging issues. SigmaMind's recording shows exactly what the AI agent heard and said.
# Genesys
Source: https://docs.sigmamind.ai/genesys
# Introduction
Source: https://docs.sigmamind.ai/index
Welcome to the SigmaMind AI developer portal—your centralized hub to build, test, and deploy intelligent conversational agents across **voice, chat, and email**. Built for developers, BPOs, and implementation partners, SigmaMind creates AI that **does**, not just **responds**
***
## 🔍 Explore Our Platform
### **Platform Overview**
* End-to-end support for designing, testing, deploying, and monitoring AI agents
* Omnichannel support: voice calls, chat messaging, and email workflows built once, deployed everywhere.
### **Agent Builder**
* No-code, drag-and-drop UI with event triggers, intents, app actions, branches, waits, and personalized flows
* **Persona layer** controls tone, verbosity, escalation, and channel behavior.
### **Playground**
* Real-time simulator for testing conversational flows and payloads pre-launch
* Provides debugging tools, channel previews, and persona verification.
### **App Library**
* No-code integrations with Shopify, Zendesk, Gorgias, Google Sheets, Calendly, and more
* Enable agents to trigger real-world actions—refunds, scheduling, ticket updates, database queries.
***
## 💡 Use Cases & Industry Applications
| Use Case | Outcome |
| -------------------------- | ------------------------------------------------------------------ |
| **Customer Support** | 50–60% ticket automation; 70% faster first responses |
| **Lead Qualification** | Identify, score, and qualify leads—multi-channel support |
| **Appointment Scheduling** | 40% lower no‑shows; live calendar sync & reminders |
| **Home Services** | Scheduling, reminders, upsells for HVAC, cleaning, repairs |
| **Healthcare** | HIPAA‑friendly patient intake, reminders, re‑fills |
| **Outbound Campaigns** | Sales calls, payment reminders, churn reactivation across channels |
***
## 💰 Pricing
* **Build for free**, pay **only live or Playground conversations** no monthly fees.
* Usage-based billing across all channels—voice, chat, email.
***
## 📚 Docs Structure
1. **Getting Started**\
Set up your workspace, build an agent, deploy live.
2. **Agent Builder Guide**\
In-depth node definitions: Event Triggers, Intents, Branches, App Actions, Persona.
3. **Playground Walkthrough**\
How to simulate across channels, debug, catch edge cases.
4. **App Integration Guides**\
Configuring Shopify, Zendesk, Calendly, custom APIs.
5. **API & Webhooks**\
For advanced use-cases and extensibility.
6. **Analytics & Monitoring**\
Monitor CSAT, deflection rates, resolution times.
7. **Security & Compliance**\
SOC, GDPR, encryption, audit trails, multi-tenant controls.
***
## 📞 Support & Community
* **Discord**: Interactive community of developers and partners.
* **Email / Slack**: Direct support channels.
* **Case Studies**: Gardencup, CleanBoss, Betterbrand—real‑world impact stories.
***
## ✅ Why SigmaMind AI?
* **Build fast, test safer, launch smarter**: build flows in minutes, simulate before deploying.
* **Omnichannel with outcomes**: deploy voice, chat, email from one canvas.
* **Actions, not just answers**: agents that perform tasks, not just reply.
* **No-code to custom-code**: UI-first, but supports webhooks + APIs when needed.
* **Measure ROI**: actionable analytics to track automation, CSAT, and cost savings.
***
## 🎯 Quickstart
1. **Clone a template** (FAQ, scheduler, lead bot).
2. **Build in Agent Builder** and simulate via Playground.
3. **Add real actions** via App Library integrations.
4. **Launch across channels**.
5. **Monitor real-world outcomes**.
# MCP Tools Integration
Source: https://docs.sigmamind.ai/mcp/client
The **MCP Tools Integration** allows you to connect your SigmaMind agents to any Model Context Protocol (MCP) server. This enables your agents to access dynamic tools from platforms like Zapier, Make, Composio, and custom MCP servers without individual API configuration for each tool.
## Overview
MCP (Model Context Protocol) is a standardized protocol for connecting AI agents to external services and tools. By integrating an MCP server with your SigmaMind agent, you can:
* **Access hundreds of pre-built tools** from MCP providers
* **Execute actions dynamically** during agent conversations
* **Avoid repetitive API configuration** for each tool
* **Scale your agent capabilities** instantly
### How MCP Tools Work
```
User Request → Agent → MCP Server → Tool Action → External Service → Response → Agent → User
```
When you add an MCP tool to your agent:
1. SigmaMind connects to the MCP server
2. Available tools from the server are fetched dynamically
3. Agent can invoke any of these tools during conversations
4. Results are returned to the agent and integrated into responses
## Quick Setup
Follow these steps to add an MCP tool to your agent:
### Step 1: Get Your MCP Server URL
Obtain an MCP server URL from your provider:
**Zapier MCP:**
* Visit: [https://mcp.zapier.com/mcp/?client=sigmamind](https://mcp.zapier.com/mcp/?client=sigmamind)
* Generate and copy your MCP server URL
**Make MCP:**
* Log in to Make account
* Go to: Profile > API Access > Tokens
* Click "Add token" and copy the MCP URL
**Composio MCP:**
* Log in to: [https://mcp.composio.dev/dashboard](https://mcp.composio.dev/dashboard)
* Select tools you want to integrate
* Create server and copy the generated URL
**Custom MCP Server:**
* Ensure your MCP server is running
* Obtain the server endpoint URL (e.g., [https://your-server.com/mcp](https://your-server.com/mcp))
### Step 2: Add MCP Tool in SigmaMind
1. Open **Agent Builder**
2. Click **Manage Tools/Apps**
3. Click **Add Custom Tool/App**
4. Enter:
* **Tool/App name**: "Zapier Integration" (or your provider name)
* **Description**: "Access to MCP tools from Zapier"
5. Click **Submit Tool/App**
### Step 3: Configure Authentication
1. Click the newly created MCP tool
2. Click **Configure Authentication**
3. Select **Bearer Token** (most common for MCP servers)
4. Paste your MCP server URL as the token
5. Click **Submit Authentication**
### Step 4: Add Tool Actions
MCP servers expose tools dynamically. Rather than adding individual actions, the MCP server provides them automatically. However, you can test tool availability:
1. Click **Add Tool Actions**
2. Enter test values to verify connectivity
3. The MCP server responds with available tools
### Step 5: Add to Your Agent
1. Open your agent in **Agent Builder**
2. Click **Add Tool/Function Calls**
3. Select **App Tool Call**
4. Select your MCP tool from the list
5. Click **Submit**
Your agent now has access to all tools from the MCP server!
## Supported MCP Providers
### Zapier MCP
**7,000+ apps and 30,000+ actions**
Zapier's MCP server provides access to thousands of pre-built integrations. Setup:
1. Visit [https://mcp.zapier.com/mcp/?client=sigmamind](https://mcp.zapier.com/mcp/?client=sigmamind)
2. Generate your MCP server URL
3. Add to SigmaMind as MCP tool with Bearer Token authentication
4. Your agent instantly has access to Zapier's full ecosystem
**Available actions include:**
* Send emails
* Create calendar events
* Post to social media
* Update spreadsheets
* And thousands more
### Make MCP
**Custom Scenarios & Workflows**
Make allows you to build custom automations and expose them as MCP tools. Setup:
1. Create your scenarios in Make with defined inputs/outputs
2. Set scenarios to "Schedule on Demand"
3. Get your MCP Token from Profile > API Access > Tokens
4. Add to SigmaMind as MCP tool with Bearer Token authentication
**Use cases:**
* Custom business logic automation
* Multi-app workflows
* Data processing pipelines
* Scheduled tasks triggered by agents
### Composio MCP
**Popular Tool Integrations**
Composio provides pre-built connections to tools like Gmail, Slack, GitHub, Notion, and more. Setup:
1. Log in to [https://mcp.composio.dev/dashboard](https://mcp.composio.dev/dashboard)
2. Select tools you want to integrate (Gmail, Slack, etc.)
3. Complete authentication flows
4. Create server and copy the MCP server URL
5. Add to SigmaMind as MCP tool with Bearer Token authentication
**Supported integrations:**
* Gmail, Outlook (email)
* Slack, Teams (messaging)
* GitHub, GitLab (code)
* Notion, Asana (productivity)
* And many more
### Custom MCP Servers
You can build and deploy your own MCP server to expose custom tools. Setup:
1. Deploy your MCP server and ensure it's accessible
2. Obtain the server endpoint URL
3. Add to SigmaMind as MCP tool
4. Configure any required authentication headers
## Configuration
### Basic MCP Tool Configuration
In the **Manage Tools/Apps** section, configure your MCP tool:
**Tool Setup:**
| Field | Value |
| ------------------- | ---------------------- |
| Tool/App name | Zapier Integration |
| Description | Access to Zapier tools |
| Authentication Type | Bearer Token |
| Token | Your MCP server URL |
### Agent System Prompt
Include guidance in your agent's system prompt about MCP tools:
```
You have access to various integrated tools and services through Zapier and other platforms.
Available capabilities:
- Send emails and messages
- Create and manage calendar events
- Update documents and spreadsheets
- Post to social media
- Manage customer data
- Execute custom automations
When users request actions that require these tools:
1. Determine which tool is appropriate
2. Extract necessary information from the user request
3. Execute the tool with correct parameters
4. Confirm the action was completed
5. If tool fails, explain the issue and suggest alternatives
```
## How MCP Tools Execute
### Execution Flow
When your agent decides to use an MCP tool:
1. **Tool Selection** - Agent determines the appropriate MCP tool for the user's request
2. **Parameter Extraction** - Agent extracts values from conversation context
3. **Server Connection** - SigmaMind connects to the MCP server using your URL
4. **Tool Invocation** - MCP server invokes the requested tool with parameters
5. **Result Processing** - Results are returned to the agent
6. **Response Generation** - Agent incorporates results into its response to the user
### Request Headers
MCP requests include context headers for tracking:
* **X-Call-Id** - Included in voice calls to identify the specific call
* **X-Chat-Id** - Included in chat interactions to identify the chat
* **X-Session-Id** - Included if the chat is part of a session
These headers help track which agent interaction triggered each MCP tool invocation.
## Best Practices
### Security
* Treat MCP server URLs as sensitive credentials
* Store URLs in environment variables, never in code
* Regularly rotate API tokens from MCP providers
* Use HTTPS for all MCP connections
### Agent Instructions
* **Clear Prompts**: Tell your agent when and how to use MCP tools
* **Error Handling**: Include fallback instructions if tools fail
* **Confirmation**: For critical actions, have the agent confirm with users first
* **Transparency**: Inform users which tools are being used
### Performance
* **Test First**: Verify MCP tools work with test requests
* **Monitor Usage**: Track which tools are used and how often
* **Handle Delays**: Be aware MCP calls may take 2-5 seconds
* **Rate Limits**: Check rate limits on MCP provider accounts
## Troubleshooting
### MCP Tool Not Available
**Problem:** Agent can't access MCP tools
**Solutions:**
1. Verify MCP server URL is correct and accessible
2. Check Bearer Token authentication is properly configured
3. Ensure agent has been published after adding MCP tool
4. Refresh the dashboard to see changes
### Tool Execution Fails
**Problem:** MCP tool returns errors
**Solutions:**
1. Test the MCP server independently with cURL:
```bash theme={null}
curl -H "Authorization: Bearer YOUR_MCP_URL" \
https://your-mcp-server.com/mcp
```
2. Verify agent's system prompt provides correct tool names
3. Check MCP provider status page for outages
4. Review error message for specific issues
### Slow Response Times
**Problem:** MCP tools are slow
**Solutions:**
1. MCP calls typically take 2-5 seconds - this is normal
2. Check MCP provider's server status
3. Verify your network connection
4. Consider switching to faster MCP provider if needed
### Authentication Failed
**Problem:** MCP server rejects requests
**Solutions:**
1. Verify the MCP server URL/token is correct
2. Ensure you copied the entire URL without spaces
3. Check if the token has expired (regenerate if needed)
4. Verify Bearer Token is selected as authentication type
## Next Steps
1. Choose your MCP provider (Zapier, Make, Composio, or custom)
2. Generate your MCP server URL from the provider
3. Add MCP tool to SigmaMind with Bearer Token authentication
4. Update your agent's system prompt with tool instructions
5. Test MCP tool with sample user requests
6. Deploy and monitor usage
## Related Documentation
* [Manage Tools Overview](/tools/manage-tools-overview)
* [Add Custom Tools](/tools/add-custom-tool)
* [Authentication Methods](/tools/authentication-methods)
* [Agent Configuration](/agents/configuration)
## Resources
* **Zapier MCP**: [https://mcp.zapier.com](https://mcp.zapier.com)
* **Make MCP**: [https://developers.make.com/mcp-server](https://developers.make.com/mcp-server)
* **Composio MCP**: [https://composio.dev](https://composio.dev)
* **MCP Specification**: [https://modelcontextprotocol.io](https://modelcontextprotocol.io)
# MCP Server
Source: https://docs.sigmamind.ai/mcp/server
Complete installation guide for SigmaMind API MCP Server across all Agent IDEs
## Overview
SigmaMind provides a free [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI coding assistants to browse and search complete API documentation. This comprehensive guide covers installation instructions for all major coding assistants and best practices for integrating the MCP server into your development workflow.
The server is available at the following URL:
```
https://api.sigmamind.ai/mcp
```
## Key Features
The SigmaMind API MCP server provides the following capabilities:
* **API Documentation Access** - Browse and search complete SigmaMind API documentation in real-time
* **Endpoint Reference** - Quick access to all available endpoints and their parameters
* **Code Examples** - View practical examples for common API use cases
* **Authentication Guidance** - Reference authentication methods and token management
* **Error Handling** - Access troubleshooting guides and error code documentation
* **Real-time Updates** - Always access the most current API documentation
## Installation Guide
Follow the instructions below for your preferred coding assistant or IDE.
### Cursor
Click the button below to install the MCP server in [Cursor](https://www.cursor.com/):
[Install MCP Server in Cursor](https://cursor.com/docs/context/mcp)
Or add it manually to your Cursor settings with the following JSON in `~/.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"sigmamind-api": {
"command": "npx",
"args": [
"mcp-remote",
"https://api.sigmamind.ai/mcp",
"--header",
"X-API-KEY:${SIGMAMIND_API_KEY}"
],
"env": {
"SIGMAMIND_API_KEY": "your-api-key-here"
}
}
}
}
```
### Claude Code
Add the MCP server to your [Claude Code](https://claude.com/product/claude-code) configuration. Create or edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json theme={null}
{
"mcpServers": {
"sigmamind-api": {
"command": "npx",
"args": [
"mcp-remote",
"https://api.sigmamind.ai/mcp",
"--header", "X-API-KEY:${SIGMAMIND_API_KEY}"
],
"env": {
"SIGMAMIND_API_KEY": "your-api-key-here"
}
}
}
}
```
Verify the installation by running:
```bash theme={null}
claude mcp list
```
### VS Code
Add the MCP server to your [VS Code](https://code.visualstudio.com/) workspace by creating or editing `.vscode/mcp.json`:
```json theme={null}
{
"servers": {
"sigmamind-api": {
"command": "npx",
"args": [
"mcp-remote",
"https://api.sigmamind.ai/mcp",
"--header",
"X-API-KEY:${SIGMAMIND_API_KEY}"
],
"env": {
"SIGMAMIND_API_KEY": "your-api-key-here"
}
}
}
}
```
Alternatively, install it using the VS Code CLI:
```bash theme={null}
code --add-mcp '{"name":"sigmamind-api","type":"http","url":"https://api.sigmamind.ai/mcp"}'
```
### GitHub Copilot
[Copilot CLI](https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-copilot-cli) supports MCP servers via an interactive setup flow or by editing its config file directly.
To add the server interactively, start Copilot CLI and run `/mcp add`. When prompted, set the server URL to `https://api.sigmamind.ai/mcp`.
To configure it manually, create or edit `~/.copilot/mcp-config.json`:
```json theme={null}
{
"mcpServers": {
"sigmamind-api": {
"command": "npx",
"args": [
"mcp-remote",
"https://api.sigmamind.ai/mcp",
"--header", "X-API-KEY:${SIGMAMIND_API_KEY}"
],
"env": {
"SIGMAMIND_API_KEY": "your-api-key-here"
}
}
}
}
```
### Codex
Run the following command in your terminal to install the server in [OpenAI Codex](https://openai.com/codex/):
```bash theme={null}
codex mcp add --url https://api.sigmamind.ai/mcp sigmamind-api
```
### Gemini CLI
Run the following command in your terminal to install the server in [Gemini CLI](https://geminicli.com):
set your API key in an environment variable:
```bash theme={null}
export SIGMAMIND_API_KEY="your-api-key-here"
```
then add the MCP server:
```bash theme={null}
gemini mcp add \
--transport http \
--header "X-API-KEY:$SIGMAMIND_API_KEY" \
sigmamind-api \
https://api.sigmamind.ai/mcp
```
### Windsurf
[Windsurf](https://codeium.com/windsurf) is built on VS Code, so use the file-based configuration approach. Create or edit `.codeium/windsurf/mcp_config.json`:
```json theme={null}
{
"mcpServers": {
"sigmamind-api": {
"command": "npx",
"args": [
"mcp-remote",
"https://api.sigmamind.ai/mcp",
"--header",
"X-API-KEY:${SIGMAMIND_API_KEY}"
],
"env": {
"SIGMAMIND_API_KEY": "your-api-key-here"
}
}
}
}
```
Restart Windsurf after making changes.
### Antigravity
[Antigravity](https://antigravity.ai/) provides MCP server support through its configuration settings.
Create or edit `.gemini/antigravity/mcp_config.json` in your project:
```json theme={null}
{
"mcpServers": {
"sigmamind-api": {
"command": "npx",
"args": [
"mcp-remote",
"https://api.sigmamind.ai/mcp",
"--header",
"X-API-KEY:${SIGMAMIND_API_KEY}"
],
"env": {
"SIGMAMIND_API_KEY": "your-api-key-here"
}
}
}
}
```
Restart Antigravity after configuration changes.
### Kiro
[Kiro](https://kiro.ai/) is a code assistant that supports MCP servers. Configure it by creating or editing `.kiro/mcp-config.json`:
```json theme={null}
{
"mcpServers": {
"sigmamind-api": {
"command": "npx",
"args": [
"mcp-remote",
"https://api.sigmamind.ai/mcp",
"--header",
"X-API-KEY:${SIGMAMIND_API_KEY}"
],
"env": {
"SIGMAMIND_API_KEY": "your-api-key-here"
},
"disabled": false,
"autoApprove": []
}
}
}
```
Restart Kiro after making changes.
### Manual Installation
The MCP server is available at the following URL. Add this server to your MCP client of choice. If prompted, set the transport to `http` or `Streamable HTTP`.
```
https://api.sigmamind.ai/mcp
```
## Quick Start
After installing the MCP server, you can:
1. **Ask your AI assistant about the SigmaMind API** - It will automatically reference the latest documentation
2. **Get code examples** - Request implementation examples for specific use cases
3. **Troubleshoot integration issues** - Reference error codes and resolution steps
4. **Stay up-to-date** - Always access the most current API documentation
5. **Access endpoint reference** - View all available endpoints and their parameters
## Authentication
When using the SigmaMind API MCP server, keep the following in mind:
* Store your API key securely using environment variables.
* Never commit API keys to version control.
* The MCP server authenticates requests using the X-API-KEY HTTP header.
* Configure your MCP client to send the header, for example:
```bash theme={null}
--header "X-API-KEY:${SIGMAMIND_API_KEY}"
```
* Use separate API keys for development, staging, and production.
* Rotate API keys regularly for security
## Security Best Practices
### Environment Variables
Store your SigmaMind API key in an environment variable:
```bash theme={null}
export SIGMAMIND_API_KEY="your-api-key-here"
```
For local development, use a `.env` file (ensure it's added to `.gitignore`):
```
SIGMAMIND_API_KEY=your-api-key-here
```
### Repository Configuration
Never commit the following to version control:
* API keys or authentication tokens
* `.env` files with sensitive information
* Configuration files with credentials
## Common Use Cases
### Creating Outbound Calls
Use the MCP server to access the `/v1/calls` endpoint documentation for creating and managing outbound phone calls. Ask your AI assistant for examples of call creation and status tracking.
### Managing Campaigns
Reference the `/v1/campaigns` endpoint to learn how to create, update, delete, and manage campaigns. The MCP server provides real-time documentation and code examples.
### Phone Number Management
The `/v1/phone-numbers` endpoint documentation covers purchasing, managing, and configuring phone numbers. Access provisioning guides and best practices through the MCP server.
### Chat Completions
Access examples and best practices for using the `/v1/chats` endpoint for conversational AI. The MCP server provides authentication guidance and integration examples.
### Webhook Management
Learn how to register and manage webhooks using the `/v1/webhooks` endpoint. Reference real-time update patterns and event handling through the MCP server.
## Troubleshooting
### MCP Server Connection Issues
If the MCP server is not connecting:
* Verify the exact URL: `https://api.sigmamind.ai/mcp`
* Check your network connectivity and firewall settings
* Ensure your IDE or CLI tool has MCP support enabled
* Restart your IDE or CLI tool after configuration
* Check the IDE or tool logs for specific error messages
* Ensure the transport type matches your IDE’s MCP configuration
### Documentation Not Appearing
If API documentation is not appearing in your IDE:
* Confirm the MCP server is properly configured in your settings
* Verify the server URL is correct
* Restart your IDE or CLI tool
* Try a simple query to confirm the connection
* Check the MCP configuration file for syntax errors
### Authentication Failures
If you’re experiencing authentication issues:
* Ensure your API key is set in an environment variable
* Verify the MCP client sends the X-API-KEY header
* Confirm the .env file is loaded by your IDE or CLI
* Verify your API key has the required permissions
* Ensure the API key has not expired or been revoked
## Next Steps
* [Install the MCP server](#installation-guide) in your preferred coding environment
* Set up [Authentication](#authentication) with your API key
* Review the [API Reference](/api-reference) for complete endpoint documentation
# Navigate IVR
Source: https://docs.sigmamind.ai/navigate-ivr
The **Navigate IVR** tool allows your AI agent to automatically handle Interactive Voice Response (IVR) systems it encounters during a call. Instead of getting stuck at a phone menu, the agent listens to the IVR prompts and responds with the correct inputs — navigating menus on its own until it reaches a live human or the target destination.
> **Phone calls only.** This tool works exclusively for voice calls and is not available for web or chat agents.
***
## When to Use
Configure this tool when your agent needs to:
* Make an outbound call to a business that has an IVR phone menu
* Navigate a multi-level menu to reach a billing agent, support team, or specific department
* Bypass automated menus and connect directly to a human representative
* Handle outbound campaigns where the destination number has an IVR system
***
## Steps to Add
1. Open the **Agent Builder**
2. Click **+ Add Tool**
3. Select **Navigate IVR** from the tool menu
4. A configuration modal will appear — fill in all fields (described below)
5. Click **Add to Agent**
***
## Configuration Fields
### Instruction *(When this tool should be invoked)*
Write a clear instruction that tells the AI agent when to trigger IVR navigation. The agent uses this to decide the right moment to activate the tool during a live call.
```text theme={null}
Invoke this tool as soon as the outbound call connects and an IVR menu is detected.
```
```text theme={null}
Use the IVR navigator when the call connects and the system starts playing an automated menu
before a human agent is available.
```
Be specific — if the instruction is too broad, the agent may try to navigate IVR when talking to a human, or not trigger it at all when a menu appears.
***
### IVR Starts Conversation?
This setting tells the agent whether the IVR system is the **first thing that speaks** when the call connects, or whether the call connects to silence or ringing first.
| Option | When to Use |
| ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Yes** | The IVR plays an automated greeting immediately when the call connects (e.g., "Thank you for calling. Press 1 for Sales...") |
| **No** | The call connects with silence or ringing first, and the IVR starts after a delay or human pickup attempt |
#### Why This Matters
When **Yes** is selected, the agent knows to start listening for IVR prompts from the very first second of the call. It will not wait for a human greeting — it immediately enters navigation mode.
When **No** is selected, the agent waits for its turn to speak first (as configured in **Basic Settings → Who speaks first**) before checking for IVR prompts. This avoids misidentifying a human as an IVR system.
**Default:** `Yes`
Setting this incorrectly causes one of two problems:
* Set to **Yes** when a human answers → agent tries to navigate a person using DTMF tones
* Set to **No** when IVR answers immediately → agent misses the first prompt and fails to navigate
***
### Pause Delay (ms)
The number of milliseconds the agent waits **after detecting an IVR prompt** before responding. This simulates a natural pause and ensures the IVR has finished speaking before the agent sends its response.
**Default:** `2,000` ms (2 seconds)
| Pause Delay | Behaviour |
| -------------- | ------------------------------------------------------------------------ |
| `500–1000 ms` | Very fast response — may cut off longer IVR announcements |
| `2000 ms` | Standard — works for most IVR systems |
| `3000–5000 ms` | Slow response — use for IVR systems with long prompts or slow processing |
#### Why Pause Delay Matters
IVR systems are not instant. They play a recorded message and then wait for input. If the agent responds too quickly, the DTMF tone may be sent while the announcement is still playing — and some IVR systems reject early inputs.
If the agent responds too slowly, the IVR may interpret silence as a non-response and either repeat the menu or route to a default option.
**When to increase the delay:**
* The IVR plays a long welcome message before the menu options
* The destination uses an older PBX system with slow prompt processing
* The agent is consistently navigating to the wrong option
**When to decrease the delay:**
* The IVR responds quickly and your campaigns need faster connection times
* You've tested the flow and confirmed the IVR accepts early inputs without issue
***
## How the Agent Navigates IVR
Once the tool is triggered, the agent:
1. **Listens** for the IVR prompt (menu options, recorded announcements)
2. **Waits** for the configured Pause Delay
3. **Responds** with the correct DTMF key press or spoken input based on the prompt
4. **Repeats** for each menu level until the destination is reached
5. **Hands off** to the next tool (e.g., records a message, delivers information, transfers the customer in)
The agent uses the context of your system prompt and the IVR prompts it hears to decide which option to select at each step. You do not need to pre-map every menu level manually — the agent reasons through the options based on its goal.
***
## Real-World Example
**Scenario:** An outbound agent is calling a hospital to reschedule a patient appointment. The hospital line has a multi-level IVR.
**IVR flow:**
```text theme={null}
"Thank you for calling City Hospital."
"Press 1 for appointments."
"Press 2 for billing."
"Press 3 for emergency."
→ Agent presses 1
"Press 1 to book a new appointment."
"Press 2 to reschedule an existing appointment."
→ Agent presses 2
"Please hold while we connect you to scheduling."
→ Human agent answers
→ AI agent continues the conversation
```
**Configuration:**
| Field | Value |
| ------------------------ | -------------------------------------------------------------------------------------- |
| Instruction | Invoke this tool immediately when the call connects and an automated menu is detected. |
| IVR Starts Conversation? | Yes |
| Pause Delay | 2,000 ms |
***
## Combining with Other Tools
| Tool | How They Work Together |
| ----------------------------- | ------------------------------------------------------------------------------------ |
| **Extract Dynamic Variables** | Capture appointment details or customer intent before navigating IVR |
| **Transfer Call** | After IVR navigation connects to a human, transfer the customer in via warm transfer |
| **End Call** | If navigation fails or the IVR cannot be resolved, end the call cleanly |
***
## Best Practices
* Set **IVR Starts Conversation?** to **Yes** for most outbound use cases — the vast majority of business phone lines play an IVR immediately on connection
* Start with the **default 2,000 ms** Pause Delay and increase only if you observe navigation errors during testing
* Write a specific **Instruction** that references the call context (e.g., "when the call connects to the hospital line") to avoid the tool triggering on human conversations
* Test the full IVR flow using the **Test Voice** playground before deploying your campaign
* If the target IVR changes its menu structure, update the agent's system prompt to reflect the new options — no tool reconfiguration needed
***
## Troubleshooting
| Issue | Fix |
| ---------------------------------------- | ------------------------------------------------------------------------ |
| Agent not navigating at all | Check that the Instruction condition is specific enough to trigger |
| Agent presses the wrong option | Add more detail to your system prompt describing the correct menu path |
| IVR prompt cut off before agent responds | Increase Pause Delay by 500–1,000 ms |
| Agent treats human greeting as IVR | Set **IVR Starts Conversation?** to **No** |
| Navigation stops mid-flow | The IVR may have changed its menu — update the system prompt accordingly |
# NICE
Source: https://docs.sigmamind.ai/nice
# Notifications
Source: https://docs.sigmamind.ai/notifications
# Quickstart
Source: https://docs.sigmamind.ai/quickstart
Start building awesome documentation in under 5 minutes
## Setup your development
Learn how to update your docs locally and deploy them to the public.
### Edit and preview
During the onboarding process, we created a repository on your Github with
your docs content. You can find this repository on our
[dashboard](https://dashboard.mintlify.com). To clone the repository
locally, follow these
[instructions](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
in your terminal.
Previewing helps you make sure your changes look as intended. We built a
command line interface to render these changes locally.
1. Install the
[Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the
documentation changes locally with this command: `npm i -g mintlify`
2. Run the following command at the root of your documentation (where
`docs.json` is): `mintlify dev`
If you’re currently using the legacy `mint.json` configuration file, please update the Mintlify CLI:
`npm i -g mintlify@latest`
And run the new upgrade command in your docs repository:
`mintlify upgrade`
You should now be using the new `docs.json` configuration file. Feel free to delete the `mint.json` file from your repository.
### Deploy your changes
Our Github app automatically deploys your changes to your docs site, so you
don't need to manage deployments yourself. You can find the link to install on
your [dashboard](https://dashboard.mintlify.com). Once the bot has been
successfully installed, there should be a check mark next to the commit hash
of the repo.
[Commit and push your changes to
Git](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push)
for your changes to update in your docs site. If you push and don't see that
the Github app successfully deployed your changes, you can also manually
update your docs through our [dashboard](https://dashboard.mintlify.com).
## Update your docs
Add content directly in your files with MDX syntax and React components. You can use any of our components, or even build your own.
Add content to your docs with MDX syntax.
Add code directly to your docs with syntax highlighting.
Add images to your docs to make them more engaging.
Add templates to your docs to make them more reusable.
# Review Alerts
Source: https://docs.sigmamind.ai/review-alerts
# Review QA Issues
Source: https://docs.sigmamind.ai/review-qa-issues
# Set Escalation Rules
Source: https://docs.sigmamind.ai/set-escalation-rules
# Set Notifiers
Source: https://docs.sigmamind.ai/set-notifiers
# Set QA Rules
Source: https://docs.sigmamind.ai/set-qa-rules
# Playgroud overview
Source: https://docs.sigmamind.ai/test/playgroud-overview
# Test chat
Source: https://docs.sigmamind.ai/test/test-chat
# Test email
Source: https://docs.sigmamind.ai/test/test-email
# Test voice
Source: https://docs.sigmamind.ai/test/test-voice
# How to use Transfer Call
Source: https://docs.sigmamind.ai/transfer-call
The **Transfer Call** tool allows your AI agent to hand off an active call to a human agent, department, or any phone number — at exactly the right moment in a conversation. It supports both **Cold Transfer** (instant handoff) and **Warm Transfer** (assisted handoff with context sharing) to give you full control over how the transition happens.
> **Phone calls only.** This tool works exclusively for phone calls and is not supported for web-based chat or voice sessions.
***
## When to Use
Trigger this tool when:
* The customer asks to speak with a human agent
* The request requires human judgement or specialist knowledge
* The conversation needs escalation (e.g., complaint, complex query)
* Routing to a specific department is required — Sales, Support, Billing, Renewals, Claims
***
## Steps to Add
1. Open the **Agent Builder**
2. Click **+ Add Tool**
3. Select **Voice Tool Call**
4. From the **Select Action** dropdown, choose `voice_transfer_call`
5. Fill in all configuration fields (described below)
6. Click **Add to Agent**
***
## Step 1: Instruction *(When this tool should be invoked)*
Write a clear instruction that tells the AI agent when to trigger the transfer. The more specific you are, the more reliably the agent will initiate the transfer at the correct moment.
```text theme={null}
Transfer the call when the customer asks to speak with a human, expresses frustration,
or needs assistance that goes beyond what the AI can handle.
```
```text theme={null}
Transfer to the billing department when the customer raises a payment dispute
or questions their invoice amount.
```
Vague instructions like *"transfer when needed"* make it harder for the agent to decide. Always describe the **exact trigger condition**.
***
## Step 2: Transfer To
Defines where the call will be sent.
### Destination Options
| Option | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| **Static Destination** | A fixed phone number or SIP URI — always routes to the same endpoint |
| **Dynamic Routing** | Destination is resolved at runtime from a `{{variable_name}}` extracted during the conversation |
### Accepted Formats
* **Phone number (E.164 format):** `+919876543210`
* **SIP URI:** `sip:agent@yourdomain.com`
* **Dynamic variable:** `{{assigned_agent_number}}`
> All phone numbers must be in **E.164 international format**, including the country code (e.g., `+1` for US, `+91` for India).
### Extension Number *(Optional)*
After the main number connects, the extension routes the call to the correct internal team or agent — automatically, without the customer needing to press anything.
```text theme={null}
Main Number: +1-800-555-0199 ← connects to the company switchboard
Extension: 302 ← routes directly to the Billing team
```
#### Why the Extension Field Matters
Most business phone systems (PBX, RingCentral, 8x8, Vonage, Twilio) share a single main inbound number across departments. Without an extension, the AI agent connects to the front-line IVR or receptionist and stalls — requiring manual routing.
With the extension configured, the handoff is seamless: the agent dials the main number and immediately routes to the right desk, with no customer interaction needed.
#### When to Use the Extension
**Your business has multiple departments on one main line:**
```text theme={null}
Main: +1-888-200-1000
├── ext. 101 → Sales
├── ext. 202 → Customer Support
└── ext. 303 → Billing & Accounts
```
**You want to bypass the IVR entirely:** Many phone systems allow direct extension dialing, skipping IVR menus altogether. The customer saves 30–60 seconds and reaches the right person immediately.
**You're routing to a specific named agent:** If a customer has a dedicated account manager (e.g., ext. 415 for James in Renewals), the extension ensures they always land at the right person — not a random available agent.
**You use SIP-based infrastructure:** SIP URIs often require an extension to reach the correct endpoint. Without it, calls may fall back to a default destination.
#### Static vs. Dynamic Extension
**Static** — same extension on every transfer:
```text theme={null}
Extension: 302
```
Best for single-purpose bots where all transfers always go to one team.
**Dynamic** — extension resolved from conversation context:
```text theme={null}
Extension: {{department_extension}}
```
Pair this with **Extract Dynamic Variables** to map customer intent to the right extension at runtime:
| Customer Says | Extracted Intent | Extension Routed |
| --------------------------- | ---------------- | ---------------- |
| "I want to renew my policy" | `renewals` | `201` |
| "I need to file a claim" | `claims` | `305` |
| "I have a billing question" | `billing` | `410` |
| "I want to cancel" | `cancellations` | `500` |
This lets a single Transfer Call tool handle all your departments — no need to create a separate tool for each one.
***
## Step 3: Transfer Type
SigmaMind provides two transfer types. Choose based on whether context sharing is needed before the customer connects.
***
### Cold Transfer
The AI agent immediately routes the call to the destination and disconnects.
**What happens:**
* The AI initiates the transfer and exits the conversation instantly
* The customer hears ringing and connects directly to the destination
* No context or summary is shared with the receiving agent
**When to use Cold Transfer:**
* Simple department routing where no background is needed
* Fast escalations where speed matters more than context
* Internal lines where agents already have CRM access
```text theme={null}
Customer: "Can I speak to someone in support?"
→ AI triggers voice_transfer_call
→ Call routes to +1-800-555-0100
→ AI drops off immediately
→ Customer hears ringing, support agent picks up
```
***
### Warm Transfer
The receiving agent is connected first, context is shared privately, then the customer is bridged in. This creates a smooth, professional handoff experience.
Warm Transfer happens in **two distinct stages:**
***
## Stage 1: Connecting Stage
In the Connecting Stage, the receiving agent's line is dialed and connected — but the customer and the agent **cannot yet hear each other**. The customer is still on hold, listening to ringing or hold music.
This stage exists so the receiving agent can receive context **before** the customer joins, allowing them to prepare a response or pull up the right information.
```text theme={null}
[Connecting Stage]
Customer ──── on hold (hears ringing) ────►
AI ──► Agent connected
↓
Whisper Message played to agent only
```
### Whisper Message
The **Whisper Message** is a private audio message played **only to the receiving agent** during the Connecting Stage. The customer cannot hear it under any circumstances.
Use the Whisper Message to give the agent the context they need before they say hello — customer name, reason for calling, policy number, account history, or any other relevant detail.
**To enable Whisper Message:**
1. Toggle **Whisper Message** ON
2. Enter your message in the text box
3. Choose either **Static** or **Prompt** mode
#### Static Whisper Message
A fixed, pre-written message — the same text plays on every transfer.
```text theme={null}
You are being connected to a customer regarding an insurance renewal request.
Please review their policy and assist accordingly.
```
You can make static messages smarter by embedding dynamic variables:
```text theme={null}
You are being connected to {{customer_name}} regarding insurance policy {{policy_id}}.
The customer wants assistance with {{request_type}}.
Please have their account ready before greeting them.
```
Best for: predictable, structured use cases where the context format never changes.
#### Prompt Whisper Message
Instead of writing a fixed message, you provide an **instruction** — and SigmaMind AI automatically generates a contextual summary based on the actual conversation before playing it to the agent.
**Prompt instruction:**
```text theme={null}
Summarize the customer's request and include their name, issue, and requested service.
```
**What the system generates automatically (example output):**
```text theme={null}
Customer name is Rahul Sharma. He is calling to renew his car insurance policy
and wants clarification on premium pricing and coverage details.
```
**Prompt with variables:**
```text theme={null}
Provide a short summary for the receiving agent. Include customer name {{customer_name}},
service {{service_type}}, and request {{customer_request}}.
```
Best for: conversations where the context varies widely — complaints, complex queries, multi-topic calls — and a fixed script wouldn't cover every scenario.
> If the Whisper Message is left empty, the transfer will still proceed, but no context will be shared with the receiving agent. In this case, the Warm Transfer effectively behaves like a Cold Transfer.
***
## Stage 2: Bridged Stage
In the Bridged Stage, the call bridge is established and **both the customer and the receiving agent can now hear each other**. The AI agent drops off, and the human takes over the conversation.
This is the moment the transfer is truly complete.
```text theme={null}
[Bridged Stage]
Customer ◄──────────────────────────► Human Agent
(full duplex audio)
AI drops off
```
### Three-Way Message *(Bridge Message)*
At the moment of bridging, the AI can play one final message **heard by both the customer and the receiving agent** simultaneously. This ensures a clear, professional transition and eliminates any awkward silence or confusion about whether the connection has succeeded.
**To enable Three-Way Message:**
1. Toggle **Three-way Message** ON
2. Enter the message in the text box
3. Choose either **Static** or **Prompt** mode
#### Static Three-Way Message
A fixed announcement confirming the connection:
```text theme={null}
Thank you for waiting. You are now connected to our support specialist.
```
With dynamic variables:
```text theme={null}
Thank you for waiting, {{customer_name}}. You are now connected to our support specialist.
```
#### Prompt Three-Way Message
A dynamically generated message tailored to the specific call:
```text theme={null}
Generate a short, clear, and neutral three-way message to be played to both the customer
and the agent after the call is bridged. Confirm the connection is complete and invite
the conversation to continue. Keep it professional and concise.
```
With variables:
```text theme={null}
Generate a short, clear, and neutral three-way message to be played to both {{customer_name}}
and the agent after the call is bridged. Mention that {{customer_name}} is now connected
with the {{agent_role}} regarding {{call_reason}}.
Keep it professional, concise, and welcoming.
```
> All variables must always be written using double curly braces: `{{variable_name}}`
***
## Step 4: Custom Headers *(Optional)*
Custom Headers let you send structured metadata along with the call transfer. This information is **invisible to the customer** but available to the receiving agent's system, CRM, call center software, or backend automation.
Headers are sent as key-value pairs:
```text theme={null}
X-Intent: billing_issue
X-Language: en
X-Customer-Type: existing
X-Ticket-ID: 12345
X-Call-Source: outbound_campaign
X-Policy-ID: POL-98271
```
### When Custom Headers Are Useful
| Use Case | Header Example |
| ----------------------------------- | ------------------------------------- |
| Route to the right CRM queue | `X-Intent: claims_inquiry` |
| Tag language for multilingual teams | `X-Language: hi` |
| Associate call with a campaign | `X-Call-Source: renewal_campaign_Q2` |
| Pre-load customer record | `X-Customer-ID: CUS-00421` |
| Log call reason for reporting | `X-Call-Reason: cancellation_request` |
Headers provide structured context for automation, reporting, and agent preparation — all without requiring the customer to repeat themselves.
***
## Step 5: Add to Agent
Once all fields are configured, click **Add to Agent** to save the tool.
If the receiving agent does not answer or the transfer fails due to network issues, SigmaMind automatically retries the transfer based on your configured settings.
***
## Full Warm Transfer Execution Flow
```text theme={null}
Customer requests transfer
↓
AI triggers voice_transfer_call
↓
[Connecting Stage]
Receiving agent's line is dialed
Customer placed on hold (hears ringing)
↓
Whisper Message played to agent only
(Customer cannot hear this)
↓
[Bridged Stage]
Call bridge established
Both customer and agent can hear each other
↓
Three-way Message played to both parties
↓
AI drops off
Human agent continues the conversation
```
***
## Cold vs. Warm
| Feature | Cold Transfer | Warm Transfer |
| ---------------------------------- | -------------- | ---------------------------- |
| Agent connected before customer | ❌ | ✅ |
| Whisper Message to receiving agent | ❌ | ✅ |
| Three-way bridge announcement | ❌ | ✅ |
| Customer hears hold music | ❌ | ✅ |
| Context shared before handoff | ❌ | ✅ |
| Speed | Fastest | Slightly slower (seconds) |
| Best for | Simple routing | High-stakes or complex calls |
***
## Example Configurations
### Example 1 — Cold Transfer to Support
| Field | Value |
| ------------- | -------------------------------------------------- |
| Instruction | Transfer when the customer requests a human agent. |
| Transfer To | Static → `+1-800-555-0100` |
| Extension | `202` |
| Transfer Type | Cold Transfer |
***
### Example 2 — Warm Transfer with Whisper + Bridge Message
| Field | Value |
| ----------------- | --------------------------------------------------------------------------------------------------- |
| Instruction | Transfer when the customer raises a billing dispute or payment issue. |
| Transfer To | Static → `+1-800-555-0199` |
| Extension | `{{department_extension}}` |
| Transfer Type | Warm Transfer |
| Whisper Message | `You are being connected to {{customer_name}} regarding a billing dispute on policy {{policy_id}}.` |
| Three-way Message | `Thank you for waiting, {{customer_name}}. You are now connected with our billing specialist.` |
***
## Best Practices
* Write **specific trigger instructions** — vague conditions cause missed or premature transfers
* Use **Warm Transfer** for high-value calls, complaints, or any scenario where the receiving agent benefits from knowing context upfront
* Use **Prompt Whisper Messages** when call topics vary widely — the AI generates a tailored summary every time
* Pair **Dynamic Routing** with **Extract Dynamic Variables** to handle multi-department routing from a single transfer tool
* Use **Custom Headers** to pre-load CRM records or tag calls for analytics — reduces repeat questions for the customer
* Always enter phone numbers in **E.164 format** (`+[country code][number]`)
* Test transfer flows using the **Test Voice** playground before going live
***
## Troubleshooting
| Issue | Fix |
| ---------------------------------- | ------------------------------------------------------------------------------ |
| Transfer not triggering | Make the Instruction more specific and match actual conversation phrases |
| Call drops instead of transferring | Verify phone number is in correct E.164 format |
| Extension not connecting | Confirm the extension is active on your PBX/phone system and accepts auto-dial |
| Dynamic variable not resolving | Ensure **Extract Dynamic Variables** runs earlier in the agent flow |
| Whisper message not playing | Check that the Whisper Message toggle is ON and the message text is not empty |
| Warm transfer behaves like cold | Whisper Message is likely empty — add content to distinguish the stages |
| Three-way message not heard | Confirm the Three-way Message toggle is ON in the Bridged Stage settings |
# Tutorials
Source: https://docs.sigmamind.ai/tutorials/agents/overview
# Build Conversational AI Agents for Customer Support
Source: https://docs.sigmamind.ai/use-cases/appointment-booking
SigmaMind AI is a **no-code/low-code AI agent platform** designed to automate **customer support** across channels—**Email, Chat, Voice, Social, SMS**. This guide walks you through how to build, test, and deploy AI agents for common e-commerce use cases like **order status**, **cancel subscription**, and **returns**.
***
## 🚀 1. Platform Overview
SigmaMind offers two operational modes:
* **Autopilot**: Fully autonomous. AI reads tickets, drafts responses, performs actions (e.g. cancel order), and sends replies automatically.
* **Co‑pilot**: AI drafts responses, but human agents review and send them.
> 🧠 Use Autopilot for high-confidence, low-risk queries (e.g. shipping status), and Co‑pilot for edge cases or brand-sensitive queries.
***
## 🔌 2. Key Integrations
* **Shopify**: Access products, orders, subscriptions, customer data.
* **Helpdesk Platforms**: Zendesk, Gorgias, Gladly, Genesys — fetch tickets, respond, auto-tag or close.
* **Others**: Recharge (subscriptions), Loop Returns, Skio, etc.
***
## 🤖 3. Agent Capabilities
* Answer common queries: order status, shipping, returns.
* Perform actions: cancel orders, pause subscriptions.
* Suggest products or upsells.
* Automatically tag, escalate, or close tickets.
* Works across Email, Chat, Voice, SMS, and Social.
***
## 🧩 4. Agent Building Workflow
### A. Prerequisites
* Shopify store connected.
* Gorgias/Zendesk account linked.
* SigmaMind AI account with access to Agent Builder.
### B. Connect Data Sources
1. Login to [SigmaMind Dashboard](https://dashboard.sigmamind.ai).
2. Go to **App Integrations** → Connect:
* Shopify
* Optional: Recharge, Loop Returns
3. Connect Helpdesk (Gorgias/Zendesk)
### C. Training and Tuning
Upload FAQs, help docs, and real training conversations into the SigmaMind AI dashboard.
Use brand voice settings to configure:
* Formality
* Tone
* Personalization level
***
## ⚙️ 5. Building with Use Case Examples
### ✅ Use Case: **Order Status**
1. **Intent**: User asks “Where is my order?”
2. **Trigger**: New ticket with intent like “where is my order.” or "Inquiry about order status."
3. **Workflow**:
* AI fetches recent order from Shopify.
* Response generated: “Hi Sarah! Your order #12345 was shipped on June 24 via FedEx. Here's your \[tracking link].”
4. **Mode**: Autopilot (can send directly).
5. **Action**: None (info only).
### 🛑 Use Case: **Cancel Subscription**
1. **Intent**: “Please cancel my subscription.”
2. **Trigger**: Intent with "Request to Cancel Subscription” or "Request to cancel recurring order"
3. **Workflow**:
* AI calls Recharge API to cancel subscription.
* Response: “Hi James, your subscription has been successfully canceled. You won’t be charged moving forward.”
4. **Mode**: Autopilot or Co‑pilot (depending on risk).
5. **Action**: API call to Recharge → Cancel.
### 🔁 Use Case: **Initiate Return**
1. **Intent**: “I want to return my order.”
2. **Trigger**: Ticket with intent “request to return order”
3. **Workflow**:
* AI checks return eligibility via Shopify.
* If valid, generates a Loop Returns link.
* Response: “Sure! You can initiate your return here: \[return portal link].”
4. **Mode**: Autopilot.
5. **Action**: Shopify + Loop Returns coordination.
***
## 🧪 6. Testing Agents
### A. Simulate Conversations
1. Go to **Agent Builder → Test Playground**.
2. Simulate incoming ticket/message.
3. AI previews draft with response and actions.
4. Review response accuracy, tone, and logic path.
### B. Preview Actions
* Preview connected app calls (e.g. cancel subscription).
* Validate that payloads and execution match expectations.
* Set to **sandbox enviroment** during tests to avoid real-world changes.
***
## 🚀 7. Deployment & Monitoring
Once configured, enable the agent.
Monitor key performance metrics:
* % of tickets auto-resolved
* CSAT (customer satisfaction) scores
* Average resolution time
Adjust workflows and training materials as needed based on agent performance.
***
## 🤝 8. Developer/Partner Integration
SigmaMind AI supports a **Certified Partner Program**, enabling agencies to build branded conversational agents for clients with:
* Training
* Certifications
* Co-marketing support
***
## ✅ 9. Best Practices
* **Start Small**: Launch with Co‑pilot on high-volume FAQs.
* **Iterate**: Analyze auto-resolution errors, refine triggers and training.
* **Brand Consistency**: Use consistent tone via brand voice settings.
* **Guardrails**: Escalate complex or high-value cases to human agents.
* **Metrics**: Track automation rate, CSAT, resolution time, and saved agent hours.
***
## 🎯 10. Summary
SigmaMind AI empowers developers and customer support teams to build scalable, brand‑aware AI agents with **no-code workflows**, powerful integrations (Shopify, Gorgias, etc.), and flexible response modes.
Whether you want full automation (**Autopilot**) or decision support (**Co‑pilot**), SigmaMind’s platform enables **rapid deployment** and **continuous learning** for high-volume customer support.
# Build Conversational AI Agents for Customer Support
Source: https://docs.sigmamind.ai/use-cases/customer-support
SigmaMind AI is a **no-code/low-code AI agent platform** designed to automate **customer support** across channels—**Email, Chat, Voice, Social, SMS**. This guide walks you through how to build, test, and deploy AI agents for common e-commerce use cases like **order status**, **cancel subscription**, and **returns**.
***
## 🚀 1. Platform Overview
SigmaMind offers two operational modes:
* **Autopilot**: Fully autonomous. AI reads tickets, drafts responses, performs actions (e.g. cancel order), and sends replies automatically.
* **Co‑pilot**: AI drafts responses, but human agents review and send them.
> 🧠 Use Autopilot for high-confidence, low-risk queries (e.g. shipping status), and Co‑pilot for edge cases or brand-sensitive queries.
***
## 🔌 2. Key Integrations
* **Shopify**: Access products, orders, subscriptions, customer data.
* **Helpdesk Platforms**: Zendesk, Gorgias, Gladly, Genesys — fetch tickets, respond, auto-tag or close.
* **Others**: Recharge (subscriptions), Loop Returns, Skio, etc.
***
## 🤖 3. Agent Capabilities
* Answer common queries: order status, shipping, returns.
* Perform actions: cancel orders, pause subscriptions.
* Suggest products or upsells.
* Automatically tag, escalate, or close tickets.
* Works across Email, Chat, Voice, SMS, and Social.
***
## 🧩 4. Agent Building Workflow
### A. Prerequisites
* Shopify store connected.
* Gorgias/Zendesk account linked.
* SigmaMind AI account with access to Agent Builder.
### B. Connect Data Sources
1. Login to [SigmaMind Dashboard](https://dashboard.sigmamind.ai).
2. Go to **App Integrations** → Connect:
* Shopify
* Optional: Recharge, Loop Returns
3. Connect Helpdesk (Gorgias/Zendesk)
### C. Training and Tuning
Upload FAQs, help docs, and real training conversations into the SigmaMind AI dashboard.
Use brand voice settings to configure:
* Formality
* Tone
* Personalization level
***
## ⚙️ 5. Building with Use Case Examples
### ✅ Use Case: **Order Status**
1. **Intent**: User asks “Where is my order?”
2. **Trigger**: New ticket with intent like “where is my order.” or "Inquiry about order status."
3. **Workflow**:
* AI fetches recent order from Shopify.
* Response generated: “Hi Sarah! Your order #12345 was shipped on June 24 via FedEx. Here's your \[tracking link].”
4. **Mode**: Autopilot (can send directly).
5. **Action**: None (info only).
### 🛑 Use Case: **Cancel Subscription**
1. **Intent**: “Please cancel my subscription.”
2. **Trigger**: Intent with "Request to Cancel Subscription” or "Request to cancel recurring order"
3. **Workflow**:
* AI calls Recharge API to cancel subscription.
* Response: “Hi James, your subscription has been successfully canceled. You won’t be charged moving forward.”
4. **Mode**: Autopilot or Co‑pilot (depending on risk).
5. **Action**: API call to Recharge → Cancel.
### 🔁 Use Case: **Initiate Return**
1. **Intent**: “I want to return my order.”
2. **Trigger**: Ticket with intent “request to return order”
3. **Workflow**:
* AI checks return eligibility via Shopify.
* If valid, generates a Loop Returns link.
* Response: “Sure! You can initiate your return here: \[return portal link].”
4. **Mode**: Autopilot.
5. **Action**: Shopify + Loop Returns coordination.
***
## 🧪 6. Testing Agents
### A. Simulate Conversations
1. Go to **Agent Builder → Test Playground**.
2. Simulate incoming ticket/message.
3. AI previews draft with response and actions.
4. Review response accuracy, tone, and logic path.
### B. Preview Actions
* Preview connected app calls (e.g. cancel subscription).
* Validate that payloads and execution match expectations.
* Set to **sandbox enviroment** during tests to avoid real-world changes.
***
## 🚀 7. Deployment & Monitoring
Once configured, enable the agent.
Monitor key performance metrics:
* % of tickets auto-resolved
* CSAT (customer satisfaction) scores
* Average resolution time
Adjust workflows and training materials as needed based on agent performance.
***
## 🤝 8. Developer/Partner Integration
SigmaMind AI supports a **Certified Partner Program**, enabling agencies to build branded conversational agents for clients with:
* Training
* Certifications
* Co-marketing support
***
## ✅ 9. Best Practices
* **Start Small**: Launch with Co‑pilot on high-volume FAQs.
* **Iterate**: Analyze auto-resolution errors, refine triggers and training.
* **Brand Consistency**: Use consistent tone via brand voice settings.
* **Guardrails**: Escalate complex or high-value cases to human agents.
* **Metrics**: Track automation rate, CSAT, resolution time, and saved agent hours.
***
## 🎯 10. Summary
SigmaMind AI empowers developers and customer support teams to build scalable, brand‑aware AI agents with **no-code workflows**, powerful integrations (Shopify, Gorgias, etc.), and flexible response modes.
Whether you want full automation (**Autopilot**) or decision support (**Co‑pilot**), SigmaMind’s platform enables **rapid deployment** and **continuous learning** for high-volume customer support.
# Build Conversational AI Agents for Customer Support
Source: https://docs.sigmamind.ai/use-cases/lead-qualification
SigmaMind AI is a **no-code/low-code AI agent platform** designed to automate **customer support** across channels—**Email, Chat, Voice, Social, SMS**. This guide walks you through how to build, test, and deploy AI agents for common e-commerce use cases like **order status**, **cancel subscription**, and **returns**.
***
## 🚀 1. Platform Overview
SigmaMind offers two operational modes:
* **Autopilot**: Fully autonomous. AI reads tickets, drafts responses, performs actions (e.g. cancel order), and sends replies automatically.
* **Co‑pilot**: AI drafts responses, but human agents review and send them.
> 🧠 Use Autopilot for high-confidence, low-risk queries (e.g. shipping status), and Co‑pilot for edge cases or brand-sensitive queries.
***
## 🔌 2. Key Integrations
* **Shopify**: Access products, orders, subscriptions, customer data.
* **Helpdesk Platforms**: Zendesk, Gorgias, Gladly, Genesys — fetch tickets, respond, auto-tag or close.
* **Others**: Recharge (subscriptions), Loop Returns, Skio, etc.
***
## 🤖 3. Agent Capabilities
* Answer common queries: order status, shipping, returns.
* Perform actions: cancel orders, pause subscriptions.
* Suggest products or upsells.
* Automatically tag, escalate, or close tickets.
* Works across Email, Chat, Voice, SMS, and Social.
***
## 🧩 4. Agent Building Workflow
### A. Prerequisites
* Shopify store connected.
* Gorgias/Zendesk account linked.
* SigmaMind AI account with access to Agent Builder.
### B. Connect Data Sources
1. Login to [SigmaMind Dashboard](https://dashboard.sigmamind.ai).
2. Go to **App Integrations** → Connect:
* Shopify
* Optional: Recharge, Loop Returns
3. Connect Helpdesk (Gorgias/Zendesk)
### C. Training and Tuning
Upload FAQs, help docs, and real training conversations into the SigmaMind AI dashboard.
Use brand voice settings to configure:
* Formality
* Tone
* Personalization level
***
## ⚙️ 5. Building with Use Case Examples
### ✅ Use Case: **Order Status**
1. **Intent**: User asks “Where is my order?”
2. **Trigger**: New ticket with intent like “where is my order.” or "Inquiry about order status."
3. **Workflow**:
* AI fetches recent order from Shopify.
* Response generated: “Hi Sarah! Your order #12345 was shipped on June 24 via FedEx. Here's your \[tracking link].”
4. **Mode**: Autopilot (can send directly).
5. **Action**: None (info only).
### 🛑 Use Case: **Cancel Subscription**
1. **Intent**: “Please cancel my subscription.”
2. **Trigger**: Intent with "Request to Cancel Subscription” or "Request to cancel recurring order"
3. **Workflow**:
* AI calls Recharge API to cancel subscription.
* Response: “Hi James, your subscription has been successfully canceled. You won’t be charged moving forward.”
4. **Mode**: Autopilot or Co‑pilot (depending on risk).
5. **Action**: API call to Recharge → Cancel.
### 🔁 Use Case: **Initiate Return**
1. **Intent**: “I want to return my order.”
2. **Trigger**: Ticket with intent “request to return order”
3. **Workflow**:
* AI checks return eligibility via Shopify.
* If valid, generates a Loop Returns link.
* Response: “Sure! You can initiate your return here: \[return portal link].”
4. **Mode**: Autopilot.
5. **Action**: Shopify + Loop Returns coordination.
***
## 🧪 6. Testing Agents
### A. Simulate Conversations
1. Go to **Agent Builder → Test Playground**.
2. Simulate incoming ticket/message.
3. AI previews draft with response and actions.
4. Review response accuracy, tone, and logic path.
### B. Preview Actions
* Preview connected app calls (e.g. cancel subscription).
* Validate that payloads and execution match expectations.
* Set to **sandbox enviroment** during tests to avoid real-world changes.
***
## 🚀 7. Deployment & Monitoring
Once configured, enable the agent.
Monitor key performance metrics:
* % of tickets auto-resolved
* CSAT (customer satisfaction) scores
* Average resolution time
Adjust workflows and training materials as needed based on agent performance.
***
## 🤝 8. Developer/Partner Integration
SigmaMind AI supports a **Certified Partner Program**, enabling agencies to build branded conversational agents for clients with:
* Training
* Certifications
* Co-marketing support
***
## ✅ 9. Best Practices
* **Start Small**: Launch with Co‑pilot on high-volume FAQs.
* **Iterate**: Analyze auto-resolution errors, refine triggers and training.
* **Brand Consistency**: Use consistent tone via brand voice settings.
* **Guardrails**: Escalate complex or high-value cases to human agents.
* **Metrics**: Track automation rate, CSAT, resolution time, and saved agent hours.
***
## 🎯 10. Summary
SigmaMind AI empowers developers and customer support teams to build scalable, brand‑aware AI agents with **no-code workflows**, powerful integrations (Shopify, Gorgias, etc.), and flexible response modes.
Whether you want full automation (**Autopilot**) or decision support (**Co‑pilot**), SigmaMind’s platform enables **rapid deployment** and **continuous learning** for high-volume customer support.
# Vicidial Integration Guide
Source: https://docs.sigmamind.ai/vicidial-integration
# AI-Powered Call Center Automation for Scalable Customer Engagement
### **Overview of VICIdial**
VICIdial is a widely adopted open-source contact center solution designed to manage high-volume inbound and outbound calling operations. It is commonly used by sales teams, support centers, and contact centers to run efficient communication workflows at scale.
With capabilities such as predictive dialing, automated call distribution, IVR systems, and real-time reporting, VICIdial provides a flexible and cost-effective foundation for modern call center operations.
### Why Integrate VICIdial with Sigmamind AI
Integrating VICIdial with Sigmamind AI enhances traditional call center workflows with AI-powered automation and intelligence. This enables businesses to handle more conversations, improve efficiency, and deliver better customer experiences without increasing operational overhead.
This integration is ideal for:
* Outbound sales and lead generation teams
* Customer support and service operations
* Contact centers handling high call volumes
* Businesses adopting AI-driven communication
***
### Key Capabilities
#### 1. AI-Powered Voice Agents
Automate inbound and outbound calls using conversational AI agents that can engage customers 24/7.
#### 2. Intelligent Lead Qualification & Routing
Use AI to qualify leads in real time and route high-value prospects to the right teams.
#### 3. Enhanced Predictive Dialing
Boost VICIdial’s dialing efficiency with AI-driven decision-making and prioritization.
#### 4. Real-Time Agent Assist
Provide human agents with live suggestions, summaries, and contextual insights during calls.
#### 5. Advanced Call Analytics
Analyze conversations to extract insights, track performance, and optimize campaigns.
#### 6. Workflow Automation
Automatically sync call data with CRMs and internal systems for seamless operations.
***
### Key Benefits
* Reduce operational costs through automation
* Increase conversion rates and campaign performance
* Improve customer experience with AI-driven conversations
* Enhance agent productivity and efficiency
* Scale call center operations without additional infrastructure
***
## Telephony Setup (SIP Trunk Configuration)
To enable seamless communication between VICIdial and Sigmamind AI, you must configure and connect a SIP trunk using the **“Connect via SIP Trunking”** option in Sigmamind.
## Setup Steps
### 1. Create a SIP Trunk in VICIdial
Configure a SIP trunk in VICIdial (or your VoIP provider). This will generate:
* SIP Server / Host
* Terminal URI (or SIP endpoint)
* Username & Password (if authentication is enabled)
***
### 2. Add the Trunk in Sigmamind AI
In Sigmamind AI:
* Go to **Add Phone Number**
* Select **Connect via SIP Trunking**
* Fill in the details:
**Phone Number**\
→ Enter the number associated with your VICIdial trunk
**Terminal URI**\
→ Enter the SIP endpoint from VICIdial / your provider\
*(Example: sip:[your-trunk@provider.com](mailto:your-trunk@provider.com))*
**SIP Trunk Username (Optional)**\
→ Enter if your trunk requires authentication
**SIP Trunk Password (Optional)**\
→ Enter the corresponding password
Click **Save**
***
### How VICIdial Works with Sigmamind AI
#### End-to-End Call Flow
The integration between VICIdial and Sigmamind AI enables a seamless transition from outbound dialing to AI-driven conversations and human agent handoff.
***
### Step-by-Step Flow
#### 1. Outbound Call Initiated (VICIdial)
Vicidial initiates outbound calls using customer data from its internal lists or connected data sources via predictive or auto-dialing campaigns.
#### 2. Customer Connects
Once the customer answers the call, VICIdial detects a successful connection and triggers the next step in the call flow.
#### 3. Call Routed to Sigmamind AI (Inbound)
The active call is transferred to Sigmamind AI as an inbound call, where the AI system takes control of the interaction.
#### 4. AI Agent Handles the Conversation
Sigmamind AI engages the customer to:
* Qualify the lead
* Collect key information
* Answer common questions
* Guide the interaction based on predefined workflows
#### 5. Conditional Human Handoff
Based on predefined conditions (such as user intent, interest level, or escalation triggers), the system determines whether a human agent is required.
#### 6. Call Transfer to Human Agent
If needed, the call is seamlessly transferred to a live agent without losing conversation context, ensuring a smooth customer experience.
#### 7. Call Completion & Outcome Logging
The agent completes the interaction, and the outcome is logged for reporting, analytics, and future follow-ups.
***
### Call Flow Summary
```text theme={null}
VICIdial (Outbound Dialing)
↓
Customer Answers
↓
Call Routed to Sigmamind AI (Inbound)
↓
AI Agent Conversation
↓
(Conditional)
↓
Transfer to Human Agent
↓
Call Completion & Logging
```
# Vicidial Integration Guide
Source: https://docs.sigmamind.ai/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.
# Workspace
Source: https://docs.sigmamind.ai/workspace
## Manage Your Workspace and Team in SigmaMind AI
Create workspaces, invite members, and control access all in one place.
## Create a New Workspace
## Steps
1. From the dashboard, click on the **Settings**
2. Click **“Add New Workspace”**
3. Enter the **Workspace Name**
4. Click **“Create Workspace”**
***
## What Happens Next
* The workspace is created instantly
* You are added as an **Admin**
* You can switch between workspaces anytime
***
### View Workspace Details
### Steps
1. Go to **Settings**
2. Click on **Workspace → General**
## Details Available
* **Workspace Name** (editable)
* **Workspace ID** (auto-generated, read-only)
```
## Embeds and HTML elements