# Table of Contents
- [Introduction to GigaML | GigaML](#introduction-to-gigaml-gigaml)
- [Introduction | API References | GigaML](#introduction-api-references-gigaml)
- [Outbound Calls | API References | GigaML](#outbound-calls-api-references-gigaml)
- [Call Initialization | API References | GigaML](#call-initialization-api-references-gigaml)
- [Authentication & Security | API References | GigaML](#authentication-security-api-references-gigaml)
- [Get Call | API References | GigaML](#get-call-api-references-gigaml)
- [By call_id | API References | GigaML](#by-call-id-api-references-gigaml)
- [Get Tickets | API References | GigaML](#get-tickets-api-references-gigaml)
- [By external_conversation_id | API References | GigaML](#by-external-conversation-id-api-references-gigaml)
- [Dashboard | GigaML](#dashboard-gigaml)
- [Bootstrap | API References | GigaML](#bootstrap-api-references-gigaml)
- [Tickets | GigaML](#tickets-gigaml)
- [My agents | GigaML](#my-agents-gigaml)
- [Knowledge | GigaML](#knowledge-gigaml)
- [Versions | GigaML](#versions-gigaml)
- [Mobile Numbers | GigaML](#mobile-numbers-gigaml)
- [Uploading documents | GigaML](#uploading-documents-gigaml)
- [Creating a knowledge base | GigaML](#creating-a-knowledge-base-gigaml)
- [Creating an action | GigaML](#creating-an-action-gigaml)
- [Intents | GigaML](#intents-gigaml)
- [Custom Fields | GigaML](#custom-fields-gigaml)
- [APIs | GigaML](#apis-gigaml)
- [Voice agents | GigaML](#voice-agents-gigaml)
- [Policies | GigaML](#policies-gigaml)
- [Knowledge base | GigaML](#knowledge-base-gigaml)
- [Multi-Step Scenario Guide | GigaML](#multi-step-scenario-guide-gigaml)
- [API overview | GigaML](#api-overview-gigaml)
- [Scenarios | GigaML](#scenarios-gigaml)
- [Data sources | GigaML](#data-sources-gigaml)
- [Rules | GigaML](#rules-gigaml)
- [Brand | GigaML](#brand-gigaml)
- [Supporting docs | GigaML](#supporting-docs-gigaml)
- [Inbound Scenario Guide | GigaML](#inbound-scenario-guide-gigaml)
- [Personalization | GigaML](#personalization-gigaml)
- [Attaching an action | GigaML](#attaching-an-action-gigaml)
- [Phone | GigaML](#phone-gigaml)
- [Evaluation | GigaML](#evaluation-gigaml)
- [Test cases | GigaML](#test-cases-gigaml)
- [Experiments | GigaML](#experiments-gigaml)
- [Attaching a knowledge base | GigaML](#attaching-a-knowledge-base-gigaml)
- [Identities | GigaML](#identities-gigaml)
- [Test results | GigaML](#test-results-gigaml)
- [Review | GigaML](#review-gigaml)
- [Chat agents | GigaML](#chat-agents-gigaml)
- [Knowledge base | GigaML](#knowledge-base-gigaml)
- [Personalization | GigaML](#personalization-gigaml)
- [Global variables | GigaML](#global-variables-gigaml)
- [Advanced | GigaML](#advanced-gigaml)
- [Brand | GigaML](#brand-gigaml)
- [Multi-Step Scenario Guide | GigaML](#multi-step-scenario-guide-gigaml)
- [Identities | GigaML](#identities-gigaml)
- [Data sources | GigaML](#data-sources-gigaml)
- [Review | GigaML](#review-gigaml)
- [Code blocks | GigaML](#code-blocks-gigaml)
- [Initialization code | GigaML](#initialization-code-gigaml)
- [Evaluation | GigaML](#evaluation-gigaml)
- [API overview | GigaML](#api-overview-gigaml)
- [Attaching an action | GigaML](#attaching-an-action-gigaml)
- [Advanced | GigaML](#advanced-gigaml)
- [Supporting docs | GigaML](#supporting-docs-gigaml)
- [Conversation | GigaML](#conversation-gigaml)
- [Experiments | GigaML](#experiments-gigaml)
- [Policies | GigaML](#policies-gigaml)
- [Chat widget | GigaML](#chat-widget-gigaml)
- [Global variables | GigaML](#global-variables-gigaml)
- [Webhook events and payloads | GigaML](#webhook-events-and-payloads-gigaml)
- [Finding your agent template ID | GigaML](#finding-your-agent-template-id-gigaml)
- [Attaching a knowledge base | GigaML](#attaching-a-knowledge-base-gigaml)
- [Finding your agent template ID | GigaML](#finding-your-agent-template-id-gigaml)
- [Variable naming | GigaML](#variable-naming-gigaml)
- [Scenarios | GigaML](#scenarios-gigaml)
- [Implementation example | GigaML](#implementation-example-gigaml)
- [HTML implementation | GigaML](#html-implementation-gigaml)
- [Test cases | GigaML](#test-cases-gigaml)
- [Test results | GigaML](#test-results-gigaml)
- [Escalate ticket | GigaML](#escalate-ticket-gigaml)
- [Service endpoints | GigaML](#service-endpoints-gigaml)
- [Close a session | GigaML](#close-a-session-gigaml)
- [Client endpoints | GigaML](#client-endpoints-gigaml)
- [Rules | GigaML](#rules-gigaml)
- [Initialization code | GigaML](#initialization-code-gigaml)
- [Headless Agent | GigaML](#headless-agent-gigaml)
- [Inbound Scenario Guide | GigaML](#inbound-scenario-guide-gigaml)
- [Code blocks | GigaML](#code-blocks-gigaml)
- [Troubleshooting | GigaML](#troubleshooting-gigaml)
- [Receive a message | GigaML](#receive-a-message-gigaml)
- [Events | GigaML](#events-gigaml)
- [Send message | GigaML](#send-message-gigaml)
- [Adding the widget to your site | GigaML](#adding-the-widget-to-your-site-gigaml)
- [Conversation | GigaML](#conversation-gigaml)
- [Initiate a session | GigaML](#initiate-a-session-gigaml)
- [Message types | GigaML](#message-types-gigaml)
- [Configuring the widget | GigaML](#configuring-the-widget-gigaml)
- [chat_finished | GigaML](#chat-finished-gigaml)
- [External Telephony | GigaML](#external-telephony-gigaml)
- [call_finished | GigaML](#call-finished-gigaml)
- [Single-page application implementation | GigaML](#single-page-application-implementation-gigaml)
- [Post Conversation Code | GigaML](#post-conversation-code-gigaml)
- [Post Conversation Code | GigaML](#post-conversation-code-gigaml)
- [Email Protection | Cloudflare](#email-protection-cloudflare)
---
# Introduction to GigaML | GigaML
GigaML is the leader in AI customer support, providing zero hold time support at scale.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix#quick-start)
Quick start
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents)
**Voice Agents**
Build and manage an AI voice agent
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents)
**Chat Agents**
Get started with an AI chat agent
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget)
**Integrations**
Deploy low-code or fully customizable solutions
[NextDashboard](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/analytics/dashboard)
Last updated 4 months ago
---
# Introduction | API References | GigaML
Complete reference documentation for the GigaML API. The GigaML API allows you to programmatically access and control GigaML functionality.
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references#base-url)
Base URL
--------------------------------------------------------------------------------------
Copy
https://api.gigaml.com/v1
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references#authentication)
Authentication
--------------------------------------------------------------------------------------------------
All API requests require authentication using an API key. See the [Authentication](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references#authentication)
page for details.
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references#action-categories)
Action Categories
--------------------------------------------------------------------------------------------------------
* **Agents** - Create and manage AI agents
* **Chat** - Initialize and manage chat sessions
* **Knowledge Base** - Upload and manage knowledge bases
* **Voice** - Configure and control voice interactions
* **Conversations** - Retrieve conversation data across different channels
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references#common-endpoints)
Common Endpoints:
* [Outbound Calls](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/outbound-calls)
- Initiate an outbound voice call
* [Call Initialization](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/call-initialization)
- Send initialized values before transferring the call
* [Get Call](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/get-call)
- Retrieve detailed information about a voice call
Each API endpoint includes detailed information about request parameters, example requests, response formats, and error codes.
[NextAuthentication & Security](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/authentication-and-security)
Last updated 4 months ago
---
# Outbound Calls | API References | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/outbound-calls#post-voice-make-call)
Make outbound call
post
https://agents.gigaml.com/voice/make-call
Initiate an outbound voice call using GigaML's AI agents.
**Key Features:**
* Specify target phone number and calling number
* Configure which agent or agent template to use
* Provide initialization values for call context
* System waits up to 45 seconds for call to be answered
* Call considered failed if in "dialing" state for more than 20 seconds
**Requirements:**
* Either `agent_id` or `agent_template_id` must be provided
* Valid phone numbers in international format
Authorizations
bearerAuth
bearerAuth
Body
application/json
application/json
to\_numberstringRequired
The phone number to call (Required)
Example: `+15551234567`Pattern: `^\+\d{10,15}$`
from\_numberstringRequired
The phone number making the call (Required)
Example: `+18005551234`Pattern: `^\+\d{10,15}$`
agent\_idstringOptional
The ID of the agent that will handle the call (Optional - provide either agent\_id or agent\_template\_id)
Example: `agent_12345`
agent\_template\_idstringOptional
Template ID for the agent (Optional - provide either agent\_id or agent\_template\_id)
Example: `template_sales_001`
initialization\_valuesobjectOptional
Additional values to initialize the call (Optional).
Can include any custom fields relevant to your use case such as:
* Customer information
* Call context and purpose
* Lead or account data
* Priority levels
Example: `{"customer_name":"John Doe","account_id":"ACC12345","purpose":"follow_up_call"}`
Show properties
Responses
200
Call initiated successfully
application/json
Responseobject
Show properties
400
Bad request - Invalid payload or parameters
application/json
401
Unauthorized - Invalid or missing API key
application/json
500
Server error
application/json
post
/voice/make-call
HTTP
HTTPcURLJavaScriptPython
Copy
POST /voice/make-call HTTP/1.1
Host: agents.gigaml.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 202
{
"to_number": "+15551234567",
"from_number": "+18005551234",
"agent_template_id": "template_sales_001",
"initialization_values": {
"customer_name": "John Doe",
"account_id": "ACC12345",
"purpose": "follow_up_call"
}
}
Make call with specific agent ID
Make call with specific agent IDMake call with agent template
Test it
200
Call initiated successfully
Copy
{
"call_id": "a1b2c3d4-5678-90ab-cdef-ghijklmnopqr"
}
[PreviousAuthentication & Security](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/authentication-and-security)
[NextCall Initialization](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/call-initialization)
Last updated 4 months ago
---
# Call Initialization | API References | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/call-initialization#post-voice-initialize)
Initialize calls
post
https://agents.gigaml.com/voice/initialize
Send initialization values to GigaML before transferring the call.
Call this endpoint before you expect to transfer a call from a specific number to GigaML. When a call comes in from that number to GigaML's systems, the agent will be initialized with the provided values.
**Two methods available:**
1. **Standard method**: Include `from_number` - values expire after 1 hour
2. **Rolling phone number method**: Omit `from_number` - receive temporary number, values expire after 5 minutes
Authorizations
bearerAuth
bearerAuth
Body
application/json
application/json
from\_numberstringOptional
Phone number that will be calling (optional).
* **Include this field**: Standard method - values expire after 1 hour, matched by phone number + organization ID
* **Omit this field**: Rolling phone number method - receive temporary gigaml\_number, values expire after 5 minutes
Example: `+15551234567`Pattern: `^\+\d{10,15}$`
agent\_template\_idstringOptional
The ID of the agent template to use for this call
Example: `template_12345`
initialization\_valuesobjectRequired
Key-value pairs of initialization data for the voice agent.
Can include any custom fields relevant to your use case such as:
* Customer information (name, account ID)
* Call context (reason, priority)
* Previous interaction history
* Custom business data
Example: `{"customer_name":"John Doe","account_id":"ACC12345","reason_for_call":"Billing inquiry","previous_interactions":[{"date":"2023-06-15","topic":"Account setup"}]}`
Show properties
Responses
200
Call initialization successful
application/json
Responseone of
objectOptional
Response when from\_number is provided in the request
Show properties
or
objectOptional
Response when using rolling phone number method (from\_number omitted).
**Important notes:**
* The gigaml\_number and associated initialization values expire after 5 minutes
* You must transfer your call to the provided gigaml\_number
* Initialization values do not persist between calls with this method
Show properties
400
Bad request - Invalid payload
application/json
401
Unauthorized - Invalid or missing API key
application/json
500
Server error
application/json
post
/voice/initialize
HTTP
HTTPcURLJavaScriptPython
Copy
POST /voice/initialize HTTP/1.1
Host: agents.gigaml.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 252
{
"from_number": "+15551234567",
"agent_template_id": "template_12345",
"initialization_values": {
"customer_name": "John Doe",
"account_id": "ACC12345",
"reason_for_call": "Billing inquiry",
"previous_interactions": [\
{\
"date": "2023-06-15",\
"topic": "Account setup"\
}\
]
}
}
Standard initialization with phone number
Standard initialization with phone numberRolling phone number method
Test it
200
Call initialization successful
Copy
{
"status": "success",
"message": "Call initialized successfully"
}
Standard method success (with from\_number)
[PreviousOutbound Calls](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/outbound-calls)
[NextGet Call](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/get-call)
---
# Authentication & Security | API References | GigaML
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/authentication-and-security#how-to-create-and-manage-api-keys)
How to Create and Manage API Keys
--------------------------------------------------------------------------------------------------------------------------------------------------------------------
Create an API
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/authentication-and-security#creating-a-new-api)
Creating a new API
--------------------------------------------------------------------------------------------------------------------------------------
1. Navigate to your account by clicking your name in the bottom left corner of the sidebar
2. Select **Accounts** from the dropdown menu
3. Go to **Organization API Keys** in the navigation sidebar
4. Click the **New API key** button
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/authentication-and-security#setting-an-expiration-date)
Setting an Expiration Date
------------------------------------------------------------------------------------------------------------------------------------------------------
When creating a new API key, you'll be prompted to choose when the key should expire. Available options are:
* Two weeks
* One month
* Three months
* Six months
* One year
* Never (use with caution for security reasons)
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/authentication-and-security#important-security-notes)
Important Security Notes
--------------------------------------------------------------------------------------------------------------------------------------------------
* **You will only be able to view the API key once** after creation
* Make sure to copy and store it in a secure location (password manager recommended)
* Setting an expiration date is recommended for security best practices
* You can view and revoke API keys from the Organization API Keys page
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/authentication-and-security#viewing-existing-api-keys)
Viewing Existing API Keys
----------------------------------------------------------------------------------------------------------------------------------------------------
The API Keys page shows:
* A list of all active API keys
* When each key was created
* When each key expires
* Search functionality to find specific keys
Remember that for optimal security, it's best to use temporary API keys with expiration dates rather than permanent ones, and to regularly rotate your keys.
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/authentication-and-security#enable-ip-whitelisting)
Enable IP Whitelisting
----------------------------------------------------------------------------------------------------------------------------------------------
To enable IP whitelisting, contact a member of the Giga_ML_ team.
[PreviousIntroduction](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references)
[NextOutbound Calls](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/outbound-calls)
Last updated 4 months ago
---
# Get Call | API References | GigaML
Get Call API allows you to retrieve detailed information about calls including complete transcripts, metadata, and call analytics. This endpoint offers two retrieval methods to accommodate different integration scenarios:
* **Get Call by Call ID** uses GigaML's internal call identifier for direct lookups
* **Get Call by External Conversation ID** enables retrieval using external system identifiers such as Amazon Connect IDs or other integration IDs.
Both endpoints return comprehensive call data including conversation messages, sentiment analysis, agent information, call duration, and downloadable recording URLs, making it easy to access and analyze your voice interactions regardless of how the calls are identified in your system.
[PreviousCall Initialization](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/call-initialization)
[NextBy call\_id](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/get-call/by-call_id)
Last updated 4 months ago
---
# By call_id | API References | GigaML
get
https://api.gigaml.com/v1/external/get-call-by-call-id/{call\_id}
Retrieve detailed information about a voice call including the complete transcript, metadata, and call status using the internal call\_id
Authorizations
bearerAuth
bearerAuth
Path parameters
call\_idstringRequired
The unique identifier of the call
Example: `a1b2c3d4-5678-90ab-cdef-ghijklmnopqr`
Responses
200
Call data retrieved successfully
application/json
Responseobject
Complete call response including recording URL
Show properties
401
Invalid or missing API key
application/json
404
Call not found
application/json
500
Server error
application/json
get
/external/get-call-by-call-id/{call\_id}
HTTP
HTTPcURLJavaScriptPython
Copy
GET /v1/external/get-call-by-call-id/{call_id} HTTP/1.1
Host: api.gigaml.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Test it
200
Call data retrieved successfully
Copy
{
"call_id": "a1b2c3d4-5678-90ab-cdef-ghijklmnopqr",
"external_conversation_id": "connect-call-12345",
"call_medium": "voice",
"status": "closed",
"reason": "issue_resolved",
"created_at": "2025-05-01T14:23:45.000Z",
"closed_at": "2025-05-01T14:28:12.000Z",
"duration": 267,
"agent_id": "agent_12345",
"agent_name": "Customer Support Agent",
"from_number": "+15551234567",
"to_number": "+18005551234",
"sentiment": "happy",
"transfer_to": "",
"recording_url": "https://storage.gigaml.com/recordings/a1b2c3d4.mp3",
"messages": [\
{\
"role": "assistant",\
"content": [\
{\
"type": "text",\
"text": "Hello, thank you for calling GigaML support. How can I assist you today?"\
}\
],\
"timestamp": 1714567425000\
}\
],
"session_analysis": {
"sentiment_reasoning": [\
"The customer starts with a neutral tone when describing their account connection issue.",\
"The customer becomes more positive as the agent provides helpful instructions.",\
"By the end of the call, the customer expresses gratitude and satisfaction with the resolution."\
],
"summary": "Customer needed help connecting their account to a new device. The agent provided step-by-step instructions, and the issue was successfully resolved.",
"sentiment": "happy",
"tags": [\
"account connection",\
"device setup",\
"troubleshooting"\
]
},
"is_outbound": false
}
[PreviousGet Call](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/get-call)
[NextBy external\_conversation\_id](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/get-call/by-external_conversation_id)
Last updated 4 months ago
---
# Get Tickets | API References | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/get-tickets#get-integrations-get-tickets)
By start\_time and end\_time
get
https://backend.gigaml.com/integrations/get-tickets
Retrieve detailed information about your voice sessions including transcript and metadata for a given time period
Authorizations
bearerAuth
bearerAuth
Query parameters
start\_timeinteger · int64Required
Receive session beginning on or after this time stamp (Format - Epoch milliseconds)
Example: `1714567425000`
end\_timeinteger · int64Required
Receive session end on or before this time stamp (Format - Epoch milliseconds)
Example: `1714567431000`
Responses
200
Call data retrieved successfully
application/json
Responseobject\[\]
Voice session ticket with complete transcript and metadata
Show properties
400
Invalid or missing query params
application/json
401
Invalid or missing API key
application/json
404
Not found
application/json
500
Server error
application/json
get
/integrations/get-tickets
HTTP
HTTPcURLJavaScriptPython
Copy
GET /integrations/get-tickets?start_time=1714567425000&end_time=1714567431000 HTTP/1.1
Host: backend.gigaml.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Test it
200
Call data retrieved successfully
Copy
[\
{\
"call_id": "a1b2c3d4-5678-90ab-cdef-ghijklmnopqr",\
"external_conversation_id": "connect-call-12345",\
"call_medium": "voice",\
"status": "closed",\
"reason": "issue_resolved",\
"created_at": "2025-05-01T14:23:45.000Z",\
"closed_at": "2025-05-01T14:28:12.000Z",\
"duration": 267,\
"agent_id": "agent_12345",\
"agent_name": "Customer Support Agent",\
"from_number": "+15551234567",\
"to_number": "+18005551234",\
"sentiment": "happy",\
"transfer_to": "",\
"messages": [\
{\
"role": "assistant",\
"content": [\
{\
"type": "text",\
"text": "Hello, thank you for calling GigaML support. How can I assist you today?"\
}\
],\
"timestamp": 1714567425000\
},\
{\
"role": "user",\
"content": [\
{\
"type": "text",\
"text": "Hi, I'm having trouble connecting my account to my new device."\
}\
],\
"timestamp": 1714567431000\
}\
],\
"session_analysis": {\
"sentiment_reasoning": [\
"The customer starts with a neutral tone when describing their account connection issue.",\
"The customer becomes more positive as the agent provides helpful instructions.",\
"By the end of the call, the customer expresses gratitude and satisfaction with the resolution."\
],\
"summary": "Customer needed help connecting their account to a new device. The agent provided step-by-step instructions, and the issue was successfully resolved.",\
"sentiment": "happy",\
"tags": [\
"account connection",\
"device setup",\
"troubleshooting"\
]\
},\
"is_outbound": false\
}\
]
[PreviousBy external\_conversation\_id](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/get-call/by-external_conversation_id)
[NextBootstrap](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/bootstrap)
Last updated 4 months ago
---
# By external_conversation_id | API References | GigaML
get
https://api.gigaml.com/v1/external/get-call-by-external-conversation-id/{external\_conversation\_id}
Retrieve detailed information about a voice call including the complete transcript, metadata, and call status using an external\_conversation\_id (e.g., Amazon Connect ID or other integration ID)
Authorizations
bearerAuth
bearerAuth
Path parameters
external\_conversation\_idstringRequired
External system identifier (e.g., Amazon Connect ID or other integration ID)
Example: `connect-call-12345`
Responses
200
Call data retrieved successfully
application/json
Responseobject
Complete call response including recording URL
Show properties
401
Invalid or missing API key
application/json
404
Call not found
application/json
500
Server error
application/json
get
/external/get-call-by-external-conversation-id/{external\_conversation\_id}
HTTP
HTTPcURLJavaScriptPython
Copy
GET /v1/external/get-call-by-external-conversation-id/{external_conversation_id} HTTP/1.1
Host: api.gigaml.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Test it
200
Call data retrieved successfully
Copy
{
"call_id": "a1b2c3d4-5678-90ab-cdef-ghijklmnopqr",
"external_conversation_id": "connect-call-12345",
"call_medium": "voice",
"status": "closed",
"reason": "issue_resolved",
"created_at": "2025-05-01T14:23:45.000Z",
"closed_at": "2025-05-01T14:28:12.000Z",
"duration": 267,
"agent_id": "agent_12345",
"agent_name": "Customer Support Agent",
"from_number": "+15551234567",
"to_number": "+18005551234",
"sentiment": "happy",
"transfer_to": "",
"recording_url": "https://storage.gigaml.com/recordings/a1b2c3d4.mp3",
"messages": [\
{\
"role": "assistant",\
"content": [\
{\
"type": "text",\
"text": "Hello, thank you for calling GigaML support. How can I assist you today?"\
}\
],\
"timestamp": 1714567425000\
}\
],
"session_analysis": {
"sentiment_reasoning": [\
"The customer starts with a neutral tone when describing their account connection issue.",\
"The customer becomes more positive as the agent provides helpful instructions.",\
"By the end of the call, the customer expresses gratitude and satisfaction with the resolution."\
],
"summary": "Customer needed help connecting their account to a new device. The agent provided step-by-step instructions, and the issue was successfully resolved.",
"sentiment": "happy",
"tags": [\
"account connection",\
"device setup",\
"troubleshooting"\
]
},
"is_outbound": false
}
[PreviousBy call\_id](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/get-call/by-call_id)
[NextGet Tickets](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/get-tickets)
Last updated 4 months ago
---
# Dashboard | GigaML
The Dashboard provides visual analytics for your AI agents across voice, chat, and email channels. Switch between agent types and time frames to view key metrics including ticket status, customer sentiment, and performance data.
All charts are interactive and clickable. You can customize the layout by dragging and resizing components to suit your monitoring needs.
Dashboard
[PreviousIntroduction to GigaML](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix)
[NextTickets](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/analytics/tickets)
Last updated 4 months ago
---
# Bootstrap | API References | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/bootstrap#post-internal-bootstrap-rotate)
Rotate Bootstrap Key
post
https://backend.gigaml.com/internal/bootstrap/rotate
Exchange a one-time bootstrap token for an Org-scoped API key
Authorizations
bootstrapAuth
bootstrapAuth
Body
application/json
application/json
expires\_in\_secondsinteger · min: 1 · max: 5184000Optional
Lifetime of the new API key
Default: `2592000`
Responses
200
Successful key rotation
application/json
Responseobject
Show properties
400
Invalid request
application/json
401
Missing or malformed Authorization
application/json
403
Token issues
application/json
500
Server error
application/json
post
/internal/bootstrap/rotate
HTTP
HTTPcURLJavaScriptPython
Copy
POST /internal/bootstrap/rotate HTTP/1.1
Host: backend.gigaml.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 30
{
"expires_in_seconds": 2592000
}
Test it
200
Successful key rotation
Copy
{
"api_key_id": "a4fc8c0a-",
"api_key_token": "ksM7_DKf...",
"expires_at_seconds": 1751497932
}
[PreviousGet Tickets](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/api-references/get-tickets)
Last updated 4 months ago
---
# Tickets | GigaML
The Tickets page displays a comprehensive list of all customer interactions across voice, chat, and email channels. Each ticket represents a complete conversation between your AI agent and a customer, with detailed analytics and full conversation history.
Click on any ticket to view the full transcript, listen to call recordings, and see detailed performance metrics including latencies and agent configurations.
Tickets
[PreviousDashboard](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/analytics/dashboard)
[NextMy agents](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/my-agents)
Last updated 4 months ago
---
# My agents | GigaML
Log in to the [**GigaML Console**](https://console.gigaml.com/)
1. Navigate to the **Agents > My agents** section in the left sidebar
2. Click the **New Agent** button
3. Enter a name and description for your agent
4. Select **Voice** or **Chat** as the agent type
5. **Create** your agent
Create Voice Agent
[PreviousTickets](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/analytics/tickets)
[NextVersions](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/my-agents/versions)
Last updated 4 months ago
---
# Knowledge | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/knowledge#what-is-a-knowledge-base)
What is a Knowledge base
A knowledge base is a collection of custom documents containing domain-specific information. When integrated with your agents, knowledge bases enable more accurate and contextually relevant responses based on your own data.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/knowledge#why-do-we-need-knowledge-bases)
Why do we need Knowledge bases
* To quip agents with verified information rather than general knowledge
* To enable agents to answer complex, domain-specific questions
* To provide consistent and up-to-date information across user interactions
* **To customize agent capabilities for your particular use cases**
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/knowledge#how-agents-use-knowledge-bases)
How agents use Knowledge bases
* Agents search through documents to find relevant information
* They extract specific details to answer user questions accurately
* They provide real-time support using your verified information
* They can reference specific sources from your knowledge base when needed
[PreviousVersions](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/my-agents/versions)
[NextCreating a knowledge base](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/knowledge/creating-a-knowledge-base)
Last updated 4 months ago
---
# Versions | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/my-agents/versions#agent-states)
Agent States
Agents can exist in one of three states:
1. **Draft Mode** - The working version you're actively building
2. **Live Mode** - The published version available to external users
3. **Historical Version** - Previous published versions that have been archived
Versions
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/my-agents/versions#agent-building-process)
Agent Building Process
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/my-agents/versions#draft-mode)
Draft Mode
* All new agents start in draft mode
* You can edit and save your draft as many times as needed
* Changes in draft mode are not visible to external users but can be tested inside the playground
* Think of this as your "agent building mode"
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/my-agents/versions#publishing-an-agent)
Publishing an Agent
* When your agent is ready for production, use the publish button
* Publishing makes your agent publicly available to external users
* The previous live version (if any) becomes a historical version and a new draft is created that matches the published agent
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/my-agents/versions#managing-versions)
Managing Versions
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/my-agents/versions#viewing-version-history)
Viewing Version History
* Click the history icon to expand the agent history panel on the right
* View a chronological list of all published versions and the draft version
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/my-agents/versions#editing-agents)
Editing Agents
* **Draft Agent**: Edit via the history panel or the edit button at the top of the screen
* **Live Agent**: Click edit to open and modify the draft version
* **Historical Version**: Click edit to overwrite the current draft with this version
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/my-agents/versions#viewing-historical-versions)
Viewing Historical Versions
* All versions (live and historical) can be viewed in read-only mode
* Click on any version in the history panel to view it
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/my-agents/versions#republishing-historical-versions)
Republishing Historical Versions
* Any previously published version can be republished
* Republishing a historical version makes it the new live version
* The current live version becomes a historical version
* **Note:** Republishing does not affect your draft agent
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/my-agents/versions#important-notes)
Important Notes
* The draft agent and live agent are separate entities
* Changes to your draft do not affect the live agent until published
* Republishing a historical version does not overwrite your draft
* You can always return to working on your draft after viewing other versions
[PreviousMy agents](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/my-agents)
[NextKnowledge](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/knowledge)
Last updated 5 months ago
---
# Mobile Numbers | GigaML
1. Navigate to the **Agents > Phone Numbers** section in the **GigaML Console**
2. Click the **Add Number** button to create a new phone number
3. Select a provider (**Twilio** or **Telnyx**)
4. Choose a phone number from the available options
5. Select the voice agent you want to connect to the number
6. Save your configuration
The phone number will now be linked to your voice agent, allowing users to interact with your agent by calling the assigned number.
[PreviousCreating an action](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/apis/creating-an-action)
[NextIntents](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/intents)
Last updated 5 months ago
---
# Uploading documents | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/knowledge/uploading-documents#your-knowledge-base)
Your knowledge base
The knowledge base details page displays:
* A unique ID for your knowledge base (e.g., kb\_2b747…)
* The name of your knowledge base
* A list of all documents in your knowledge base
* Document metadata including title, source URL, tags, and last updated time
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/knowledge/uploading-documents#uploading-documents)
Uploading documents
1. Click the **Upload Documents** button in the top-right corner
2. In the modal that appears, you can:
1. Drag and drop a JSONL file into the designated area
2. Browse and select a JSONL file
3. The system will show a preview of the first few items
4. Review the file information (file name, size, number of documents)
5. Click **Import** to add the documents to your knowledge base
_Note: JSONL files must be 100MB or less._
Uploading Knowledge Base
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/knowledge/uploading-documents#example-documents)
Example documents
Documents can be imported via JSONL files with structured data. Each line in your JSONL file should contain a complete JSON object representing a document. Unlike JSON objects, JSONL files do not have opening and closing brackets:
Copy
{
"title": "Example Document 1",
"content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam auctor, nisl eget ultricies tincidunt, nisl nisl aliquam nisl, eget ultricies nisl nisl eget nisl. Sed vitae nisl eget nisl aliquam tincidunt.",
"tags": ["Lorem", "Ipsum"],
"source": "https://www.example.com/document1"
}
{
"title": "Example Document 2",
"content": "Praesent euismod, nisl eget ultricies tincidunt, nisl nisl aliquam nisl, eget ultricies nisl nisl eget nisl. Sed vitae nisl eget nisl aliquam tincidunt. Nullam auctor, nisl eget ultricies tincidunt.",
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/knowledge/uploading-documents#knowledge-base-documents)
Knowledge base documents
Field
Type
Required
Description
title
string
Yes
The title of your document
content
string
Yes
The content inside each document.
tags
string\[\]
No
Easily identifiable keywords associated with your document
source
string
No
The URL of the document
[PreviousCreating a knowledge base](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/knowledge/creating-a-knowledge-base)
[NextAPIs](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/apis)
Last updated 5 months ago
---
# Creating a knowledge base | GigaML
1. Click the **Create a knowledge base** button in the top-right corner of the **Agents > Knowledge** page.
2. In the modal that appears, enter the following information:
* **Name** - Enter a descriptive name for your knowledge base
* **Description** - Add details about what information this knowledge base contains
Your knowledge base will store documents that your agent will use to answer questions. Each knowledge base can contain multiple documents, and you can create multiple knowledge bases for different purposes or domains.
**Note:** Your agent can attach to and use multiple knowledge bases.
Creating Knowledge Base
[PreviousKnowledge](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/knowledge)
[NextUploading documents](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/knowledge/uploading-documents)
Last updated 7 months ago
---
# Creating an action | GigaML
Create an API
To start, click **Create an action** button in the top-right corner of the **Agents >** **Actions** page. An action can be tested, saved as a draft, and marked as live at any point.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/apis/creating-an-action#building-the-action)
Building the action
* Name your API here: Provide a name for your action in\_snake\_case.
* Description: Discuss what the action does. Note: This does not influence the action in any way.
* Method: GET, POST, PUT, or DELETE
* URL: Your actions endpoint. For any variable injection, you can {insert\_the\_variable\_in\_curly\_brackets} and your agent will interpret the correct variables during the conversation.
* HTTP Headers: Include any header keys and values here.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/apis/creating-an-action#data-inputs)
Data inputs
List any parameters the agent should receive in this action. All data inputs should be in valid JSON. **Save your changes.**
Copy
{
“type”: “object”,
“properties”: {
“full_name”: string,
“phone_number”: string
}
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/apis/creating-an-action#test-values)
Test values
Add a valid dictionary with all the required fields from data inputs above.
Copy
{
“type”: “object”,
“properties”: {
“full_name”: "Bob Smith",
“phone_number”: "+12345674488"
}
}
Next, test your action before deploying it, the response, whether success or error, will be provided.
Finally, deploy the action. This marks your action as **LIVE**. Live actions can be attached and used by your agents. If you are not ready to go live, you can save your action as a draft and access it later.
Remember, your agent can attach to multiple actions.
[PreviousAPIs](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/apis)
[NextMobile Numbers](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/mobile-numbers)
Last updated 5 months ago
---
# Intents | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/intents#overview)
Overview
Intents help you organize customer support issues by tracking what customers are trying to do and why they can't do it. Each intent represents a customer goal that cannot be completed, and tags identify the reasons preventing completion.
Example
Description
Intent: "Can't mark as delivered"
Customer's blocked goal
Tag: "App issue"
Root cause preventing the goal
Creating an Intent
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/intents#creating-intents)
Creating Intents
Create intents to categorize customer goals that can or cannot be completed:
1. Navigate to the Intents section
2. Click **Create intent**
3. Enter a category **Name**
4. Add a **Description** explaining the intent
5. Click **Create**
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/intents#managing-tags)
Managing Tags
------------------------------------------------------------------------------------------------
Tags identify the underlying reasons why intents cannot be completed:
Creating a Tag
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/intents#creating-tags)
Creating Tags
1. Go to the **Tags** tab
2. Click **Create tag**
3. Select which **Intent** this tag applies to
4. Enter a **Name** for the tag (the reason why)
5. Describe **When should this tag be applied?**
6. Click **Create tag**
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/intents#tag-structure)
Tag Structure
Field
Purpose
Example
Intent
Which customer goal this relates to
"Can't log in"
Name
The specific reason
"Password reset not working"
When to apply
Conditions for using this tag
"When customer mentions password reset fails"
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/intents#how-it-works)
How It Works
The system automatically analyzes customer conversations and applies the appropriate intents and tags based on what customers are trying to accomplish and the problems they encounter.
This categorization helps you:
* Identify common customer goals that fail or succeed
* Track the most frequent causes of issues
* Improve your product based on recurring problems
* Train agents on common issue patterns
[PreviousMobile Numbers](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/mobile-numbers)
[NextCustom Fields](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/custom-fields)
Last updated 4 months ago
---
# Custom Fields | GigaML
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/custom-fields#overview)
Overview
--------------------------------------------------------------------------------------------
Custom fields allow you to capture and track specific data points from customer interactions. Your AI agent can automatically extract and store this information during conversations for analysis and reporting.
Adding Custom Field
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/custom-fields#field-types)
Field Types
Choose the data type that matches the information you want to track:
Field Type
Description
Example Use Case
String
Text information
Customer feedback, product names
Number
Numeric values
Revenue amounts, order quantities
Boolean
True/false values
Whether customer requested callback
Select
Predefined options
Customer category, issue type
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/custom-fields#creating-custom-fields)
Creating Custom Fields
Add new custom fields to track specific conversation data:
1. Navigate to **Custom fields** in the sidebar
2. Click **Create custom field**
3. Complete the field configuration:
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/custom-fields#field-configuration)
Field Configuration
Setting
Purpose
Example
**Field name**
Unique identifier for the field
`late_checkout_requested`
**Field type**
Data type this field will store
Boolean
**Description**
What this field tracks
"Indicates whether customer requested late checkout"
**Examples**
Sample values to guide the AI
`true`, `false`
**Agent**
Which agent this field applies to
Select from your agents
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/custom-fields#adding-examples)
Adding Examples
Examples help the AI understand what data to extract:
1. In the **Examples** section, enter sample values
2. Click **Add example** or press Enter to save each example
3. Provide multiple examples to improve accuracy
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/custom-fields#managing-custom-fields)
Managing Custom Fields
View and organize your custom fields:
* **Search**: Find specific fields using the search bar
* **Field details**: See name, type, description, and associated agent
* **Edit**: Modify existing field settings
* **Agent assignment**: Track which agent each field belongs to
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/custom-fields#how-it-works)
How It Works
Once created, your AI agent automatically:
* Analyzes customer conversations
* Extracts relevant data based on your field definitions
* Stores the information for reporting and analysis
* Uses your examples to understand what data to capture
Custom fields appear in conversation analytics and can be used for filtering and reporting on customer interactions.
[PreviousIntents](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/intents)
[NextVoice agents](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents)
Last updated 4 months ago
---
# APIs | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/apis#what-is-knowledge-base)
What is an action?
Actions allow your agent to connect to any API you provide. Anything a human can do, such as authentication, booking a reservation, placing an order, so can an action.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/apis#why-we-need-knowledge-bases)
Why we need knowledge bases
* To enable agents to support complex end-to-end support queries
* To provide customers with a seamless, uninterrupted experience
* ####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/apis#how-agents-use-knowledge-bases)
To customize agent capabilities for your particular use cases
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/apis#how-agents-use-actions)
How agents use actions
* Agents call and use actions in real-time based on the current conversation
* They use specific details from the conversation or variable store to successfully return the right response, falling back to asking for more information if necessary
* They build off of previous actions to handle complex tasks (e.g. authentication to searching for availability at a hotel to making a reservation)
* They respond in real-time as appropriate
[PreviousUploading documents](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/knowledge/uploading-documents)
[NextCreating an action](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/apis/creating-an-action)
Last updated 5 months ago
---
# Voice agents | GigaML
[Policies](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies)
[Data sources](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/data-sources)
[Personalization](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization)
[Evaluation](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests)
[Advanced](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced)
[Review](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/review)
[PreviousCustom Fields](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/agents/custom-fields)
[NextPolicies](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies)
Last updated 5 months ago
---
# Policies | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies#overview)
Overview
Think of policies as your agent's instruction manual. It determines what information the agent can access, how it responds to different situations, when to escalate, and how to represent your brand voice.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies#customize-your-policies)
Customize your policies
Policies are customizable frameworks in markdown, allowing you to add your own formatting, lists, tables, and structure to easily guide how your AI agent should behave during customer interactions!
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies#formatting-markdown)
Formatting markdown
Customize your policies for your brand and business requirements.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies#adding-actions)
Adding actions
Add actions by typing '/' and tell the agent when to call the action.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies#referencing-global-variables)
Referencing global variables
Reference variables by typing '@' and tell the agent when to use default global variables like **@agent\_name** **or** **@current\_date** or global variables you created.
By default, both **agent\_name** or **current\_date** are always available.
[PreviousVoice agents](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents)
[NextScenarios](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios)
Last updated 7 months ago
---
# Knowledge base | GigaML
If you have not yet created a Knowledge base, please refer to Knowledge.
[PreviousData sources](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/data-sources)
[NextAttaching a knowledge base](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/data-sources/knowledge-base/attaching-a-knowledge-base)
Last updated 5 months ago
---
# Multi-Step Scenario Guide | GigaML
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/multi-step-scenario-guide#what-are-multi-step-scenarios)
What Are Multi-Step Scenarios?
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Multi-step scenarios are conversation scripts that handle complex interactions through structured steps. They ensure every customer gets consistent, professional service regardless of how they respond.
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/multi-step-scenario-guide#basic-structure)
Basic Structure
-----------------------------------------------------------------------------------------------------------------------------------------------------
Every scenario follows this pattern:
Copy
Step 1: Ask a question
→ If they say Yes: do this
→ If they say No: do that
→ If they're unsure: help them decide
Step 2: Handle their response
→ Always end with a polite closing
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/multi-step-scenario-guide#writing-steps)
Writing Steps
-------------------------------------------------------------------------------------------------------------------------------------------------
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/multi-step-scenario-guide#step-names)
Step Names
* **Main steps**: Step 1, Step 2, Step 3
* **Branches**: Step 2A, Step 2B, Step 2C
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/multi-step-scenario-guide#flow-control)
Flow Control
* **proceed to Step 2A** → moves to next step
* **end\_conversation** → ends the call
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/multi-step-scenario-guide#example)
Example
Copy
Step 1: Initial Question
* Ask: "Are you able to go back to the store?"
* If they say "Yes":
* proceed to Step 2A
* If they say "No":
* proceed to Step 2B
Step 2A: They Agreed
* Say: "Great! Please head back to [store]. Thanks and have a great day!"
* end_conversation
Step 2B: They Declined
* Say: "I understand. Thanks for your time and have a great day!"
* end_conversation
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/multi-step-scenario-guide#handle-all-responses)
Handle All Responses
---------------------------------------------------------------------------------------------------------------------------------------------------------------
Always account for these response types:
**Positive**: "Yes", "Sure", "Okay" **Negative**: "No", "Can't", "Won't" **Uncertain**: "Don't know", "Maybe", "Not sure"
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/multi-step-scenario-guide#when-they-say-no)
When They Say No
Don't give up immediately. Try once more with incentives:
Copy
* If they say "No":
* Say: "Are you sure? You'll get a bonus if you go back."
* If they change their mind: proceed to success step
* If they still refuse: proceed to end step
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/multi-step-scenario-guide#splitting-large-scenarios)
Splitting Large Scenarios
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------
For complex flows or different flows depending on a variable, we recommend to split it into separate files:
**Main file** (primary flow):
Copy
Step 1: Initial Contact
* Ask main question
* If Response A: execute scenario: success path
* If Response B: execute scenario: end path
**Supporting file** (success path):
Copy
Step 1: Success Response
* Say: "Perfect! Thanks and have a great day!"
* end_conversation
**Supporting file** (end path):
Copy
Step 1: End Response
* Say: "I understand. Thanks and have a great day!"
* end_conversation
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/multi-step-scenario-guide#essential-rules)
Essential Rules
-----------------------------------------------------------------------------------------------------------------------------------------------------
**Every path must end** with a closing statement + end\_conversation
**Use clear language** - "proceed to Step 2A" not "go to next part"
**Handle edge cases** - what if they give an unexpected answer?
**Be consistent** - same tone and format throughout
**Test all paths** - walk through every possible conversation
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/multi-step-scenario-guide#quick-checklist)
Quick Checklist
-----------------------------------------------------------------------------------------------------------------------------------------------------
Before publishing your scenario, make sure:
* Every response leads somewhere (no dead ends)
* All paths end with closing + end\_conversation
* Variables are properly formatted: @property\_name
* Tested the happy path and refusal path
* Language is professional but friendly
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/multi-step-scenario-guide#common-mistakes)
Common Mistakes
-----------------------------------------------------------------------------------------------------------------------------------------------------
**Missing endings** → Some paths don't reach end\_conversation **Unclear directions** → Use "proceed to Step X" **Inconsistent tone** → Keep the same voice throughout **Dead ends** → Every response needs a next step
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/multi-step-scenario-guide#example-template)
Example Template
-------------------------------------------------------------------------------------------------------------------------------------------------------
**Blank Template:**
Copy
# Scenario Name
Step 1: Opening
* Say: "Hi @name, I'm calling about [issue]. [Question]?"
* If positive response:
* proceed to Step 2A
* If negative response:
* proceed to Step 2B
Step 2A: Success Path
* Say: "Great! [Instructions]. Thanks @name, have a great day!"
* end_conversation
Step 2B: Alternative Path
* Say: "I understand. Thanks @name, have a great day!"
* end_conversation
**Filled Example:**
Copy
# Account Verification Protocol
Step 1: Initial Contact
* Say: "Hi @customer_name, I'm calling to verify some recent activity on your account. Can you confirm your email address for security purposes?"
* If they provide correct email:
* proceed to Step 2A
* If they provide incorrect email or refuse:
* If @security_level is "high":
* Say: "For your account security, I need to verify your identity. Can you provide the last four digits of your phone number on file?"
* If they provide correct digits:
* proceed to Step 2A
* If they provide incorrect digits or refuse:
* proceed to Step 2B
* If @security_level is "standard":
* proceed to Step 2B
Step 2A: Verification Successful
* Say: "Perfect! Your account has been verified successfully. Everything looks good on our end. Thanks for your time, @customer_name, and have a great day!"
* end_conversation
Step 2B: Verification Failed
* Say: "I understand your concern about security. For your protection, please visit our website or call our main number to complete verification. Thanks @customer_name, and have a great day!"
* end_conversation
Copy the blank template and customize for your needs.
[PreviousScenarios](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios)
[NextInbound Scenario Guide](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/inbound-scenario-guide)
Last updated 4 months ago
---
# API overview | GigaML
Have yet to created an action? Click here to create one.
[PreviousAttaching a knowledge base](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/data-sources/knowledge-base/attaching-a-knowledge-base)
[NextAttaching an action](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/data-sources/actions/attaching-an-action)
Last updated 5 months ago
---
# Scenarios | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios#overview)
Overview
Scenario policies house your Standard Operating Procedures (SOPs) for common customer interactions. Each scenario should be created as a separate markdown file.
Create a Scenario
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios#key-components)
Key components
1. **Scenario description**: Define when this scenario typically occurs and what triggers it.
2. **Handling steps:** Provide a sequential list of actions the agent should take when managing this scenario.
3. **Special considerations**: Note any exceptions, nuances, or special cases relevant to this scenario.
4. **Additional notes:** Link to helpful resources, systems, or information the agent may need.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios#calling-actions)
Calling actions
You can add instructions to call actions in any scenario by typing '/' and telling the agent when to call the action.
If you are unfamiliar with actions, you can learn more here.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios#accessing-global-variables)
Accessing global variables
Reference variables by typing '@' and tell the agent when to use default global variables like **@agent\_name** **or** **@current\_date** or global variables you created.**"**
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios#best-practices)
Best practices
1. Create separate markdown files for each distinct scenario
2. Use clear, step-by-step instructions
3. Include example customer inquiries and responses as well as how to handle them
4. Test and update scenario policies upon creation and as the SOP changes
While you aren't required to create a file per SOP, they significantly enhance your agent's ability to handle specific situations effectively.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios#example-scenario-general-information)
Example scenario - General information
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios#example-scenario-bell-desk)
Example scenario - Bell desk
[PreviousPolicies](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies)
[NextMulti-Step Scenario Guide](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/multi-step-scenario-guide)
Last updated 6 months ago
---
# Data sources | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/data-sources#knowledge-base)
Knowledge base
A knowledge base is a collection of custom documents containing domain-specific information. When integrated with your agents, knowledge bases enable more accurate and contextually relevant responses based on your own data.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/data-sources#actions)
Actions
An action allows your agent to perform public or private API requests with HTTP Methods, like authentication, make reservations, help process payments, manage user preferences, and any other business logic supported via API.
[PreviousRules](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/rules)
[NextKnowledge base](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/data-sources/knowledge-base)
Last updated 7 months ago
---
# Rules | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/rules#overview)
Overview
The rules policy establishes **strict** guidelines that govern your agent's decision-making processes. These rules take precedence over other policies when conflicts arise.
Create Rules
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/rules#key-components)
Key components
1. **Core principles**: Define the fundamental principles that guide all agent interactions
2. **Prohibited actions:** Specify what your agent should never do. Note that common prohibitions (violence, harassment, etc.) are handled automatically by default.
3. **Transfer rules**: Detail the exact procedures for executing transfers, including:
1. What to communicate to the customer before the transfer
2. What information to pass to the human agent or specialized department
3. How to introduce or what to do when connected with the human agent or specialized department
4. How to handle emotional or sensitive issues
4. **Data handling**: Establish how customer information should be processed and protected.
**Note:** Transfer reasons and associated phone numbers are maintained in **Personalization > Conversation > Transfers**. You can find more information about this here.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/rules#best-practices)
Best practices
* Be explicit and specific with the rules provided
* Test and iterate based on the agent's performance
* Consider regulatory requirements for your industry or actions that agent should never take associated with your business
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/rules#example-rules-policy)
Example rules policy
[PreviousBrand](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/messaging)
[NextData sources](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/data-sources)
Last updated 6 months ago
---
# Brand | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/messaging#overview)
Overview
Brand policies allow you to control what your agent says and how it communicates with customers. This is where you define your brand voice and establish consistent communication patterns.
Brand
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/messaging#key-components)
Key components
1. **Branded messages:** Define key phrases that reflect your company's values and positioning.
2. **Response guidelines**: Outline how your agent should respond to different types of inquiries, including
1. Tone and style guidelines
2. Appropriate level of formality
3. Response structure and preferences
3. **Disclosures:** Include any legal or compliance statements that need to be communicated.
4. **Sign-off messages:** Create consistent closing statements to end conversations professionally.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/messaging#best-practices)
Best practices
* Keep messages concise and conversational
* Incorporate you brand personality
* Test different phrasings to understand how the agent uses the messaging provided
* Ensure all required disclosures and messages are included.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/messaging#example-messaging-policy)
Example messaging policy
**Note:** Welcome messages are managed separately here.
[PreviousSupporting docs](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/general)
[NextRules](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/rules)
Last updated 5 months ago
---
# Supporting docs | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/general#overview)
Overview
Typically, your agent may need to have additional context or understanding about your business or the subject matter outside of the knowledge base. This may include the name of your business, when it was founded, or other frequently asked questions.
**Note:** You may still use the knowledge base to handle these inquiries, but giving your agent background FAQs can reduce latency.
Create General Information
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/general#best-practices)
Best practices
* Be explicit and specific with the general information provided
* Create separate markdown files for every necessary background section
* Test and iterate based on the agent's performance
* Do **NOT** dump all your knowledge base documents into this policy
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/general#example-general-information)
Example General Information
[PreviousInbound Scenario Guide](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/inbound-scenario-guide)
[NextBrand](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/messaging)
Last updated 5 months ago
---
# Inbound Scenario Guide | GigaML
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/inbound-scenario-guide#what-are-inbound-scenarios)
What Are Inbound Scenarios?
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Inbound scenarios are flexible conversation frameworks that help agents handle incoming customer calls effectively. Unlike outbound scripts, these provide guidance for responding to various customer intents while maintaining natural conversation flow rather than strict steps.
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/inbound-scenario-guide#basic-structure)
Basic Structure
--------------------------------------------------------------------------------------------------------------------------------------------------
Every inbound scenario follows this pattern:
Copy
When Customer says/asks: [trigger phrase or intent]
Response approach:
→ Provide solution or next steps (can be several bullet points)
→ Confirm resolution or offer alternatives
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/inbound-scenario-guide#writing-inbound-scenarios)
Writing Inbound Scenarios
----------------------------------------------------------------------------------------------------------------------------------------------------------------------
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/inbound-scenario-guide#scenario-naming)
Scenario Naming
* **Intent-based**: "How do I reset my password?" or "I forgot my password"
* **Problem-focused**: Clear description of the customer's issue or need
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/inbound-scenario-guide#response-flow-structure)
Response Flow Structure
* **Acknowledge** → Show you understand their concern
* **Provide** → Offer solutions, information, or next steps
* **Confirm** → Ensure the issue is resolved or properly escalated
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/inbound-scenario-guide#essential-principles)
Essential Principles
------------------------------------------------------------------------------------------------------------------------------------------------------------
**Stay flexible** - Follow customer's pace and needs, not rigid scripts
**Confirm understanding** - "Does this make sense?"
**Offer alternatives** - Always have a Plan B if first solution doesn't work
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/inbound-scenario-guide#common-patterns)
Common Patterns
--------------------------------------------------------------------------------------------------------------------------------------------------
Copy
1. Acknowledge the issue
3. Provide appropriate solution steps
4. Confirm resolution or offer additional assistance
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/inbound-scenario-guide#best-practices)
Best Practices
------------------------------------------------------------------------------------------------------------------------------------------------
Before using your inbound scenarios, ensure:
* Each scenario has a customer intent
* Solutions are explained in simple, actionable steps
* Every scenario includes confirmation or have an escalation path
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/inbound-scenario-guide#filled-in-example)
Filled in Example
------------------------------------------------------------------------------------------------------------------------------------------------------
Copy
# Account Access and Login Support
## Scenario 1: Password Reset Issues
**When customer's intent is:** "I can't reset my password" or "I don't remember my password"
**Response:**
* Verify the email address on their account matches what they're using
* If the email is correct, resend a new password reset link
* Have them check their spam/junk folder for the reset email
* Guide them through clicking the link and creating a new password
* The new password must be at least 8 characters with one uppercase letter, one number, and one special character
* Once they've created the new password, have them try logging in immediately to confirm it works
* Confirm issue resolution, if not, transfer_call
## Scenario 2: Account Locked Due to Security
**When customer's intent is:** "My account is locked" or "I got a security alert"
**Response:**
* Explain that accounts are typically locked after multiple failed login attempts or suspicious activity
* Once identity is confirmed, unlock the account in the system
* Guide them through logging in with their current password
* Recommend they update their password if they suspect it may have been compromised
* Enable additional security features like two-factor authentication to prevent future lockouts
## Scenario 3: Two-Factor Authentication Not Working
**When customer calls about:** "I'm not getting my verification code" or "My authenticator app isn't working"
**Response:**
* Acknowledge the verification issue and ask which method they're using (SMS, email, or authenticator app)
* If using SMS, verify the phone number on their account is correct and ask them to wait 2-3 minutes for delivery
* If using an authenticator app, guide them to refresh the app and ensure their device's time is set correctly
* Provide them with one of their backup codes if they have them saved
* Temporarily disable two-factor authentication so they can access their account
* Once they're logged in, help them set up two-factor authentication again and generate new backup codes
* Strongly recommend they save the backup codes in a secure location for future use
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/inbound-scenario-guide#template-structure)
Template Structure
--------------------------------------------------------------------------------------------------------------------------------------------------------
Copy
# [Call Flow Name]
## Scenario 1: [Issue Type]
**When customer's intent is:** "[Trigger phrases]"
**Response:**
* Guide through troubleshooting steps (This can be several steps)
* Ask if their issue has been resolved/transfer if needed
## Scenario 2: [Issue Type]
**When customer's intent is:** "[Trigger phrases]"
**Response:**
* Guide through troubleshooting steps (This can be several steps)
* Ask if their issue has been resolved/transfer if needed
## Scenario 3: [Issue Type]
**When customer's intent is:** "[Trigger phrases]"
**Response:**
* Guide through troubleshooting steps (This can be several steps)
* Ask if their issue has been resolved/transfer if needed
Use these templates as starting points and adapt them to your specific customer service needs and company processes.
[PreviousMulti-Step Scenario Guide](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/scenarios/multi-step-scenario-guide)
[NextSupporting docs](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/policies/general)
Last updated 2 months ago
---
# Personalization | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization#welcome-messages)
Welcome messages
* Welcome message: What the agent should say at the start of the conversation
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization#identities-configuration)
Identities configuration
* **Identities:** Associate multiple identities with your agent (e.g. Marissa, John, etc.)
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization#phone-configuration)
Phone configuration
* **SMS:** Controls if the agent can send SMS messages to the customer during calls
* **Keypad inputs:** Controls if the agent can process keypad inputs during calls
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization#conversation-configuration)
Conversation configuration
* **Transfers:** Controls if the agent can transfer the call to a human agent or department
* **Inactivity:** Controls how the agent will address inactive conversations
* **Voice hangups:** Controls when the agent should hangup the call
* **Speech:** Controls the agents language(s) and boosted words
* **Background noise:** Adds a background noise to the call
[PreviousAttaching an action](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/data-sources/actions/attaching-an-action)
[NextIdentities](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization/identities)
Last updated 6 months ago
---
# Attaching an action | GigaML
If you have not created an agent yet, refer to creating a voice agent.
1. Navigate to the **Agents > My agents** section in the sidebar and select your existing agent.
2. In your agent’s configuration page, go to **Data sources**.
3. Find the **APIs overview** section.
4. Click the **Add new API** button.
5. Select an existing live action.
6. Configure when the agent should call the action in any policies or executable code blocks.
You may add as many actions as necessary per agent.
Attatch an API
[PreviousAPI overview](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/data-sources/actions)
[NextPersonalization](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization)
Last updated 6 months ago
---
# Phone | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization/phone#send-sms)
Send SMS
When enabled, the agent can send SMS messages to the user during phone calls.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization/phone#keypad-inputs)
Keypad inputs
When enabled, the agent can process keypad inputs from the user during phone calls. Reach out to the GigaML team to enable this feature.
Phone Configuration
[PreviousIdentities](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization/identities)
[NextConversation](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization/conversation)
Last updated 4 months ago
---
# Evaluation | GigaML
[Experiments](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests/experiments)
[Test cases](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests/test-cases)
[Test results](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests/test-results)
[PreviousConversation](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization/conversation)
[NextExperiments](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests/experiments)
Last updated 5 months ago
---
# Test cases | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests/test-cases#attaching-a-test-case)
Attaching a test case
Test cases are based on prior conversations with an agent. Connect a prior conversation to your agent as a test case by going to **Tickets**, selecting any ticket row and pressing the **Test icon** near the top right hand corner of the ticket sheet.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests/test-cases#evaluating-a-test-case)
Evaluating a test case
Configure your test case in **Agents > My agents** by going to **Tests > Test cases** on the sidebar. Before running your tests, you may:
* **Evaluate Sections:** Disabling **Evaluate** in any Test Case Step will ensure that the step is not included in the test. You may want to do this when the test is evaluating a conversation and you do not want to test the opening message or a specific part of the conversation.
* **Should Pass / Fail:** Click the **Should Pass** or **Should Fail** badge to control the expected result of the test case. A test should pass if you are expecting the agent to be able to recreate the test case with limited variation. A test should fail if the agent is unable to recreate the test case with limited variation from the original.
* **Modifying Test Steps:** You may modify the agents response to the user's input for each step, including API calls and responses.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests/test-cases#running-test)
Running test
Run tests on all your test cases when you are ready by clicking **Run All**.
[PreviousExperiments](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests/experiments)
[NextTest results](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests/test-results)
Last updated 6 months ago
---
# Experiments | GigaML
* Navigate to the **Agents > My agents** section in the sidebar and select your existing agent.
* In your agent’s configuration sidebar, go to **Evaluation**.
* Find the **Experiments** section.
* Click the **Create experiment** button on the top right.
* Name your experiment
* Select a control agent and a variant.
* Configure the traffic percentage each agent would encounter and click **Create draft experiment**
* Click the three buttons on the right of the experiment, and either: activate, edit, or delete it.
[PreviousEvaluation](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests)
[NextTest cases](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests/test-cases)
Last updated 5 months ago
---
# Attaching a knowledge base | GigaML
If you have not created an agent yet, refer to creating a voice agent.
1. Navigate to the **Agents > My agents** section in the sidebar and select your existing agent.
2. In your agent’s configuration sidebar, go to **Data sources**.
3. Find the **Knowledge base** section.
4. Click the **Manage knowledge bases** button.
5. Select an existing knowledge base or knowledge bases. Press save changes.
6. Configure how many documents your agent will use from the knowledge base in responses by expanding any attached knowledge base.
You may add as many knowledge bases as necessary per agent.
Attatch a Knowledge Base
[](https://docs.gigaml.com/src/knowledge_base/3_uploading_documents)
[PreviousKnowledge base](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/data-sources/knowledge-base)
[NextAPI overview](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/data-sources/actions)
Last updated 5 months ago
---
# Identities | GigaML
* **Identities:** Configure an identity based on your specific needs:
* **Identity name:** The name your agent will provide when communicating with customers
* **Current voice:** The voice the agent is currently on
* **Gender:** The gender of the agent, which is especially important in gender-based languages
* **Timezone:** The agent's default timezone during conversations
* **Voice Speed:** Adjust the speaking speed of the identity
Identities
[PreviousPersonalization](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization)
[NextPhone](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization/phone)
Last updated 4 months ago
---
# Test results | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests/test-results#analyzing-results)
Analyzing results
Test results are provided in as a test group and are generated when you click **Run All** inside of Test Cases. You will be provided the status of each test result, whether it has passed or failed.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests/test-results#view-a-test-result)
View a test result
Click into any test result to get additional information, including:
* **Status:** Failed or Passed
* **Steps Completed:** Understand how many test steps were completed, otherwise steps completed should match the total number of possible steps if status is passed.
* **Expected to Pass:** Whether the test was expected to pass or fail.
* **Success rate:** The percentage of steps that passed successfully.
You can understand an ideal response to any test result step by expanding an individual step. You will be able to compare the ideal response to the newly generated test response in order to troubleshoot why the test step passed or failed.
[PreviousTest cases](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests/test-cases)
[NextAdvanced](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced)
Last updated 6 months ago
---
# Review | GigaML
1. Navigate to your agent in the **Agents > My agents** section
2. Start a call with your agent by clicking the **Test** button
3. Speak with your agent
4. Review the conversation flow, agent responses, and make adjustments
Review Agent
[PreviousCode blocks](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/code-blocks)
[NextChat agents](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents)
Last updated 4 months ago
---
# Chat agents | GigaML
[Policies](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies)
[Data sources](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/data-sources)
[Personalization](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/personalization)
[Evaluation](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests)
[Advanced](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced)
[Review](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/review)
[PreviousReview](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/review)
[NextPolicies](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies)
Last updated 7 months ago
---
# Knowledge base | GigaML
If you have not yet created a Knowledge base, please refer to Knowledge.
[PreviousData sources](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/data-sources)
[NextAttaching a knowledge base](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/data-sources/knowledge-base/attaching-a-knowledge-base)
Last updated 5 months ago
---
# Personalization | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/personalization#welcome-messages)
Welcome messages
* Welcome message: What the agent should say at the start of the conversation
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/personalization#identities-configuration)
Identities configuration
* **Identities:** Associate multiple identities with your agent (e.g. Marissa, John, etc.)
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/personalization#conversation-configuration)
Conversation configuration
* **Inactivity:** Controls how the agent will address inactive conversations
* **Chat hangups:** Controls when the agent should end the chat
* **Language:** Configure the agents language
[PreviousAttaching an action](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/data-sources/actions/attaching-an-action)
[NextIdentities](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/personalization/identities)
Last updated 6 months ago
---
# Global variables | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/global-variables#working-with-global-variables)
Working with global variables
Global variables provide a persistent state management system for AI agents throughout a conversation. They allow agents to access and update key information across turns, maintaining context from custom code executions, API calls, and user interactions. This includes:
* Policies
* API responses
* Custom code execution results
* User-provided information
* System initialization data
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/global-variables#global-variables-schema)
Global variables schema
Any valid flat, 1-level deep JSON schema is accepted.
Copy
// Getting started (minimum requirements)
{
"type": "object",
"properties": {}
}
// Example schema
{
"type": "object",
"title": "Hotel Schema",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [\
"propertyID",\
"currentDate",\
"phoneNumber"\
],
"properties": {
"propertyID": {
"type": "string",
"description": "Hotel property ID"
},
"currentDate": {
"type": "string",
"description": "Current date"
},
"phoneNumber": {
"type": "string",
"decription": "Phone number of the caller"
}
},
"description": "Schema for getting hotel property details"
}
[PreviousAdvanced](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced)
[NextInitialization code](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/initialization-code)
Last updated 6 months ago
---
# Advanced | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced#global-variables)
Global variables
The variable store is a mutable collection of key value pairs that the agent will have access to throughout the conversation. They can be preset prior to agent initialization, added, or updated during the session.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced#initialization-code)
Initialization code
Initialization code runs before the conversation starts, populating global variables and providing context to the agent immediately.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced#code-blocks)
Code blocks
Executable code blocks are the custom code required to support any action attached to your agent. You may describe the params required and expected response.
[PreviousTest results](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests/test-results)
[NextGlobal variables](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/global-variables)
Last updated 6 months ago
---
# Brand | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/messaging#overview)
Overview
Brand policies allow you to control what your agent says and how it communicates with customers. This is where you define your brand voice and establish consistent communication patterns.
Brand
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/messaging#key-components)
Key components
1. **Branded messages:** Define key phrases that reflect your company's values and positioning.
2. **Response guidelines**: Outline how your agent should respond to different types of inquiries, including
1. Tone and style guidelines
2. Appropriate level of formality
3. Response structure and preferences
3. **Disclosures:** Include any legal or compliance statements that need to be communicated.
4. **Sign-off messages:** Create consistent closing statements to end conversations professionally.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/messaging#best-practices)
Best practices
* Keep messages concise and conversational
* Incorporate you brand personality
* Test different phrasings to understand how the agent uses the messaging provided
* Ensure all required disclosures and messages are included.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/messaging#example-messaging-policy)
Example messaging policy
**Note:** Welcome messages are managed separately here.
[PreviousSupporting docs](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/general)
[NextRules](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/rules)
Last updated 5 months ago
---
# Multi-Step Scenario Guide | GigaML
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/multi-step-scenario-guide#what-are-multi-step-scenarios)
What Are Multi-Step Scenarios?
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Multi-step scenarios are conversation scripts that handle complex interactions through structured steps. They ensure every customer gets consistent, professional service regardless of how they respond.
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/multi-step-scenario-guide#basic-structure)
Basic Structure
----------------------------------------------------------------------------------------------------------------------------------------------------
Every scenario follows this pattern:
Copy
Step 1: Ask a question
→ If they say Yes: do this
→ If they say No: do that
→ If they're unsure: help them decide
Step 2: Handle their response
→ Always end with a polite closing
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/multi-step-scenario-guide#writing-steps)
Writing Steps
------------------------------------------------------------------------------------------------------------------------------------------------
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/multi-step-scenario-guide#step-names)
Step Names
* **Main steps**: Step 1, Step 2, Step 3
* **Branches**: Step 2A, Step 2B, Step 2C
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/multi-step-scenario-guide#flow-control)
Flow Control
* **proceed to Step 2A** → moves to next step
* **end\_conversation** → ends the call
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/multi-step-scenario-guide#example)
Example
Copy
Step 1: Initial Question
* Ask: "Are you able to go back to the store?"
* If they say "Yes":
* proceed to Step 2A
* If they say "No":
* proceed to Step 2B
Step 2A: They Agreed
* Say: "Great! Please head back to [store]. Thanks and have a great day!"
* end_conversation
Step 2B: They Declined
* Say: "I understand. Thanks for your time and have a great day!"
* end_conversation
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/multi-step-scenario-guide#handle-all-responses)
Handle All Responses
--------------------------------------------------------------------------------------------------------------------------------------------------------------
Always account for these response types:
**Positive**: "Yes", "Sure", "Okay" **Negative**: "No", "Can't", "Won't" **Uncertain**: "Don't know", "Maybe", "Not sure"
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/multi-step-scenario-guide#when-they-say-no)
When They Say No
Don't give up immediately. Try once more with incentives:
Copy
* If they say "No":
* Say: "Are you sure? You'll get a bonus if you go back."
* If they change their mind: proceed to success step
* If they still refuse: proceed to end step
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/multi-step-scenario-guide#splitting-large-scenarios)
Splitting Large Scenarios
------------------------------------------------------------------------------------------------------------------------------------------------------------------------
For complex flows or different flows depending on a variable, we recommend split into separate files:
**Main file** (primary flow):
Copy
Step 1: Initial Contact
* Ask main question
* If Response A: execute scenario: success path
* If Response B: execute scenario: end path
**Supporting file** (success path):
Copy
Step 1: Success Response
* Say: "Perfect! Thanks and have a great day!"
* end_conversation
**Supporting file** (end path):
Copy
Step 1: End Response
* Say: "I understand. Thanks and have a great day!"
* end_conversation
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/multi-step-scenario-guide#essential-rules)
Essential Rules
----------------------------------------------------------------------------------------------------------------------------------------------------
**Every path must end** with a closing statement + end\_conversation
**Use clear language** - "proceed to Step 2A" not "go to next part"
**Handle edge cases** - what if they give an unexpected answer?
**Be consistent** - same tone and format throughout
**Test all paths** - walk through every possible conversation
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/multi-step-scenario-guide#quick-checklist)
Quick Checklist
----------------------------------------------------------------------------------------------------------------------------------------------------
Before publishing your scenario, make sure:
* Every response leads somewhere (no dead ends)
* All paths end with closing + end\_conversation
* Variables are properly formatted: @property\_name
* Tested the happy path and refusal path
* Language is professional but friendly
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/multi-step-scenario-guide#common-mistakes)
Common Mistakes
----------------------------------------------------------------------------------------------------------------------------------------------------
**Missing endings** → Some paths don't reach end\_conversation **Unclear directions** → Use "proceed to Step X" **Inconsistent tone** → Keep the same voice throughout **Dead ends** → Every response needs a next step
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/multi-step-scenario-guide#example-template)
Example Template
------------------------------------------------------------------------------------------------------------------------------------------------------
**Blank Template:**
Copy
# Scenario Name
Step 1: Opening
* Say: "Hi @name, I'm calling about [issue]. [Question]?"
* If positive response:
* proceed to Step 2A
* If negative response:
* proceed to Step 2B
Step 2A: Success Path
* Say: "Great! [Instructions]. Thanks @name, have a great day!"
* end_conversation
Step 2B: Alternative Path
* Say: "I understand. Thanks {name}, have a great day!"
* end_conversation
**Filled Example:**
Copy
# Account Verification Protocol
Step 1: Initial Contact
* Say: "Hi @customer_name, I'm calling to verify some recent activity on your account. Can you confirm your email address for security purposes?"
* If they provide correct email:
* proceed to Step 2A
* If they provide incorrect email or refuse:
* If @security_level is "high":
* Say: "For your account security, I need to verify your identity. Can you provide the last four digits of your phone number on file?"
* If they provide correct digits:
* proceed to Step 2A
* If they provide incorrect digits or refuse:
* proceed to Step 2B
* If @security_level is "standard":
* proceed to Step 2B
Step 2A: Verification Successful
* Say: "Perfect! Your account has been verified successfully. Everything looks good on our end. Thanks for your time, @customer_name, and have a great day!"
* end_conversation
Step 2B: Verification Failed
* Say: "I understand your concern about security. For your protection, please visit our website or call our main number to complete verification. Thanks @customer_name, and have a great day!"
* end_conversation
Copy the blank template and customize for your needs.
[PreviousScenarios](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios)
[NextInbound Scenario Guide](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/inbound-scenario-guide)
Last updated 4 months ago
---
# Identities | GigaML
* **Identities:** Configure an identity based on your specific needs:
* **Agent Name:** The name your agent will provide when communicating with customers
Identities
[PreviousPersonalization](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/personalization)
[NextConversation](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/personalization/conversation)
Last updated 4 months ago
---
# Data sources | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/data-sources#knowledge-base)
Knowledge base
A knowledge base is a collection of custom documents containing domain-specific information. When integrated with your agents, knowledge bases enable more accurate and contextually relevant responses based on your own data.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/data-sources#actions)
Actions
An action allows your agent to perform public or private API requests with HTTP Methods, like authentication, make reservations, help process payments, manage user preferences, and any other business logic supported via API.
[PreviousRules](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/rules)
[NextKnowledge base](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/data-sources/knowledge-base)
Last updated 7 months ago
---
# Review | GigaML
1. Navigate to your agent in the **Agents > My agents** section
2. Start a conversation with your agent by clicking the **Start chat** button
3. Send messages to your agent
4. Review the conversation flow, agent responses, and make adjustments
Review Agent
[PreviousCode blocks](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/code-blocks)
[NextChat widget](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget)
Last updated 4 months ago
---
# Code blocks | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/code-blocks#overview)
Overview
When configured properly, code blocks let you programmatically:
* Make asynchronous API calls
* Run custom code in the cloud
* Process, store, and manage a JSON response
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/code-blocks#code)
Code
Code blocks update the global variables and provide context to the agent.
Copy
# Input schema the code block with receive
input_schema = dict() # JSON schema (flat, 1-level deep or empty)
# Initialize or process your global variables based on the logic required
store_updates = dict() # Type: dict (flat, 1-level deep)
assistant_message: str = "" # Type: str (usually a status or response message)
# Add your custom code here...
# Return a dictionary in the following format (required)
return {
"store_updates": store_updates, # Partial or full global variables (flat JSON schema - 1 level deep)
"assistant_message": assistant_message # Full API response or custom code response (string)
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/code-blocks#input-schema)
Input schema
The code block input schema is a valid flat, 1-level deep JSON schema telling the agent what values it can expect anytime during or before the conversation.
Copy
{
"type": "object",
"properties": {},
"required": []
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/code-blocks#example)
Example
Our agents can do anything a human support specialist can do. For example, you are the owner and operator a hotel and have asked Giga_ML_ to manage your reservation requests. You can easily add your business logic to a code block to allow your agents to receive and make reservation requests on your behalf.
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/code-blocks#reservation-request-input-schema)
Reservation request input schema
Copy
{
"type": "object",
"title": "Reservation Request Schema",
"required": [\
"propertyID",\
"startDate",\
"endDate",\
"guestFirstName",\
"guestLastName",\
"guestCountry",\
"guestZip",\
"guestEmail",\
"rooms",\
"adults",\
"children",\
"paymentMethod",\
"roomTypeID"\
],
"properties": {
"rooms": {
"type": "number",
"maximum": 4,
"minimum": 1,
"description": "Number of rooms for the reservation"
},
"adults": {
"type": "number",
"minimum": 1,
"description": "Number of adults for the reservation"
},
"endDate": {
"type": "string",
"description": "Check-out date in format YYYY-MM-DD (e.g., 2025-02-14)"
},
"children": {
"type": "number",
"minimum": 0,
"description": "Number of children for the reservation"
},
"guestZip": {
"type": "string",
"description": "ZIP Code"
},
"startDate": {
"type": "string",
"description": "Check-in date in format YYYY-MM-DD (e.g., 2025-02-14)"
},
"guestEmail": {
"type": "string",
"description": "Email of the guest who is making the reservation"
},
"guestPhone": {
"type": [\
"string",\
"null"\
],
"description": "Main phone number of the guest who is making the reservation"
},
"propertyID": {
"type": [\
"string",\
"null"\
],
"description": "Property ID",
"fetch_from_store": true
},
"roomTypeID": {
"type": [\
"string"\
],
"description": "ID for the room you are reserving"
},
"guestCountry": {
"type": "string",
"default": "US",
"maxLength": 2,
"minLength": 2,
"description": "Valid ISO-Code for Country (2 characters)"
},
"guestLastName": {
"type": "string",
"description": "Last name of the guest who is making the reservation"
},
"paymentMethod": {
"enum": [\
"cash",\
"credit",\
"ebanking",\
"pay_pal"\
],
"type": "string",
"description": "Payment Method of choice. MUST BE AN ENUM. Choices are cash, credit, ebanking, or pay_pal"
},
"guestFirstName": {
"type": "string",
"description": "First name of the guest who is making the reservation"
}
},
"description": "Schema for adding a reservation to the selected property"
}
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/code-blocks#reserversation-request-code)
Reserversation request code
Copy
assert propertyID is not None
assert startDate is not None
assert endDate is not None
assert guestFirstName is not None
assert guestLastName is not None
assert guestCountry is not None
assert guestZip is not None
assert guestEmail is not None
assert guestPhone is not None
assert roomTypeID is not None
rooms_obj = [\
{\
"roomTypeID": roomTypeID,\
"quantity": int(rooms)\
}\
]
adults_obj = [\
{\
"roomTypeID": roomTypeID,\
"quantity": int(adults)\
}\
]
children_obj = [\
{\
"roomTypeID": roomTypeID,\
"quantity": int(children)\
}\
]
response_str = await book_reservation(
propertyID=propertyID,
startDate=startDate,
endDate=endDate,
guestFirstName=guestFirstName,
guestLastName=guestLastName,
guestCountry=guestCountry,
guestZip=guestZip,
guestEmail=guestEmail,
guestPhone=guestPhone,
rooms=rooms_obj,
adults=adults_obj,
children=children_obj,
paymentMethod=paymentMethod,
)
response_json = json.loads(response_str)
store_updates = dict()
if response_json.get("success") != True:
assistant_message = f"Failed to make a reservation. Fix the issue based on this response: '{response_json}'. If you are unable to fix the issue, ask the customer if they'd like to speak to a senior staff member."
return {
"assistant_message": assistant_message,
"store_updates": store_updates,
}
store_updates["reservationID"] = response_json.get("reservationID")
store_updates["status"] = response_json.get("status")
store_updates["guestID"] = response_json.get("guestID")
store_updates["guestFirstName"] = response_json.get("guestFirstName")
store_updates["guestLastName"] = response_json.get("guestLastName")
store_updates["guestGender"] = response_json.get("guestGender")
store_updates["guestEmail"] = response_json.get("guestEmail")
store_updates["startDate"] = response_json.get("startDate")
store_updates["endDate"] = response_json.get("endDate")
store_updates["dateCreated"] = response_json.get("dateCreated")
store_updates["grandTotal"] = response_json.get("grandTotal")
assistant_message = f"Reservation created successfully. Reservation ID: {store_updates['reservationID']}"
return {
"assistant_message": assistant_message,
"store_updates": store_updates,
}
[PreviousPost Conversation Code](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code)
[NextReview](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/review)
Last updated 6 months ago
---
# Initialization code | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/initialization-code#implementation)
Implementation
* Initialization code runs before the conversation starts
* May access both code blocks and actions
* Returns a dictionary that updates the variable store
* All returned values MUST match keys defined in the variable store schema
Initialization Code
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/initialization-code#initialization-input-schema)
Initialization input schema
Unlike chat agents, voice agents do not have an initialization input schema, but do have access to the caller's and agent's phone number by default. You can access and return the phone number to the global variables like this:
Copy
# Initialization Function for Phone Calls
# ---------------------------------------
# This function runs at the start of each conversation to set up initial variables.
# Input:
# - For phone calls: 'to_number' (agent's phone) and 'from_number' (customer's phone) are automatically provided
# - For web calls: these numbers will be None
# Output:
# - Returns a dictionary of values that will be available throughout the conversation
# 1. Pull out the phone numbers (or get None on web calls)
agent_phone: str | None = initialization_values.get("to_number")
customer_phone: str | None = initialization_values.get("from_number")
# 2. Run your custom code here
# my_customer_preference = my_api_call(agent_phone)
# 3. Return dictionary with all information we want available in our global variables
# Values returned will be added to your global variables and can be used in API calls or interpolated into your policies
return {
"user_id": "user_12345",
"phone_number": customer_phone,
"weather_forecast": "Sunny. 78°F/25°C",
# "my_customer_preference": my_customer_preference
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/initialization-code#callable-functions)
Callable functions
The initialization code supports callable functions such as actions and code blocks. You may use initialization values provided and/or local variable generated in python. Multiple actions and/or code blocks may be used in your initialization code.
Copy
# Example - Callable function
# Remember these functions must exist in "Actions" or "Code blocks"
initialization_values = dict() # JSON schema (flat, 1-level deep or empty)
# Custom action provided that does not require an initialization value
popular_transactions = get_popular_transactions()
# Custom action provided requiring an initialization value
user_transactions = user_transactions(user_id=initialization_values['user_id'])
# Note: all actions return responses as strings
return {
"popular_transactions": popular_transactions,
"user_transactions": user_transactions
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/initialization-code#other-values)
Other values
You may write local code in the initialization code that is unrelated to the initialization input schema. Anything that can be generated in the initialization code can be used and saved to the global variables dictionary. This can include variables like the current date.
**Note: external packages are not supported at this time.**
Copy
# Example - Generating the current date on initialization
from datetime import datetime
# Get the current date formatted as "February 18, 2025"
current_date = datetime.now().strftime("%B %d, %Y")
# Optionally remove any leading zero from the day (if needed)
current_date = current_date.replace(" 0", " ")
# The global variables must have the value "current_date". You may pass a partial dictionary.
return {
"current_date": current_date,
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/initialization-code#return-format)
Return format
Initialization code is received (e.g. phone number) or generated (e.g. current date) before the conversation begins. Provide a partial or full dictionary to update global variables before the agent speaks.
Copy
{
"current_date": "04/25/2024", # Generate the current date in the hosted code
"phone_number": initialization_values.get("from_number") # Always provided and accessible on voice calls
"weather": "Sunny" # Can be returned via an API call
}
[PreviousGlobal variables](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/global-variables)
[NextPost Conversation Code](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code)
Last updated 6 months ago
---
# Evaluation | GigaML
[Experiments](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests/experiments)
[Test cases](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests/test-cases)
[Test results](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests/test-results)
[PreviousConversation](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/personalization/conversation)
[NextExperiments](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests/experiments)
Last updated 5 months ago
---
# API overview | GigaML
Have yet to created an action? Click here to create one.
[PreviousAttaching a knowledge base](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/data-sources/knowledge-base/attaching-a-knowledge-base)
[NextAttaching an action](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/data-sources/actions/attaching-an-action)
Last updated 5 months ago
---
# Attaching an action | GigaML
If you have not created an agent yet, refer to creating a voice agent.
1. Navigate to the **Agents > My agents** section in the sidebar and select your existing agent.
2. In your agent’s configuration page, go to **Data sources**.
3. Find the **APIs overview** section.
4. Click the **Add new API** button.
5. Select an existing live action.
6. Configure when the agent should call the action in any policies or executable code blocks.
You may add as many actions as necessary per agent.
Attatch an API
[PreviousAPI overview](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/data-sources/actions)
[NextPersonalization](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/personalization)
Last updated 6 months ago
---
# Advanced | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced#global-variables)
Global variables
The variable store is a mutable collection of key value pairs that the agent will have access to throughout the conversation. They can be preset prior to agent initialization, added, or updated during the session.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced#initialization-code)
Initialization code
Initialization code runs before the conversation starts, populating global variables and providing context to the agent immediately.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced#code-blocks)
Code blocks
Executable code blocks are the custom code required to support any action attached to your agent. You may describe the params required and expected response.
[PreviousTest results](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests/test-results)
[NextGlobal variables](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/global-variables)
Last updated 6 months ago
---
# Supporting docs | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/general#overview)
Overview
Typically, your agent may need to have additional context or understanding about your business or the subject matter outside of the knowledge base. This may include the name of your business, when it was founded, or other frequently asked questions.
**Note:** You may still use the knowledge base to handle these inquiries, but giving your agent background FAQs can reduce latency.
Create General Information
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/general#best-practices)
Best practices
* Be explicit and specific with the general information provided
* Create separate markdown files for every necessary background section
* Test and iterate based on the agent's performance
* Do **NOT** dump all your knowledge base documents into this policy
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/general#example-general-information)
Example General Information
[PreviousInbound Scenario Guide](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/inbound-scenario-guide)
[NextBrand](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/messaging)
Last updated 5 months ago
---
# Conversation | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization/conversation#welcome-messaging)
Welcome messaging
Includes messages and who speaks first, either the AI agent or the human.
Messages include:
* **Welcome message:** Customizable message from the agent when the conversation begins
* **Variation:** Whether the welcome message should be this **exact** message every time of a smart variation.
* **Delay:** The amount of time the agent should wait after the last message (or start of conversation) before saying the welcome message.
**Note:** You can chain welcome messages to let the agent have a train-of-thought at the start of the conversation and reference {agent\_name} in the message.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization/conversation#example-welcome-messages)
Example welcome messages
Welcome messages are flexible and may include [global variables](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/global-variables)
, such as:
* Hello, how many I help you today?
* Hi there, thank you calling {company\_name}.
* Hello, this is {agent\_name}. How may I assist you today!
* Hello, this is {agent\_name}, thank you for calling {company\_name}. How may I help you today?
**Note:** agent\_name is available in global variables by default. To use another global variable, such as company\_name, you would have to add it to the global variables configuration.
Welcome messaging
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization/conversation#transfers)
Transfers
Configure when and how conversations transfer to human agents.
* **Enable transfers:** When enabled, the agent can transfer the call
* **SIP REFER:** Option to use SIP REFER for transfers
* **Transfer reasons:**
* **Reason:** The specific reason that the agent should consider to transfer the call (e.g. The customer requests to speak with an agent)
* **Internal tag:** Tag used to filter and find tickets of this type on the dashboard
* **Transfer to number:** The number to transfer the call to (note: multiple transfer reasons can transfer calls to the same name)
Transfers
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization/conversation#inactivity)
Inactivity
Manage how your agent responds to periods of user inactivity:
* **Enable inactivity flow:** When enabled, the agent will address inactive conversations in the order provided.
* **Steps:** Define a sequence of messages or actions when users go quiet
* **Wait time since last message:** Duration of inactivity since the last inactivity message the agent should wait until executing the next step
* **Close conversation:** Automatically end conversations after inactivity steps complete
Inactivity Configuration
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization/conversation#voice-hangups)
Voice hangups
Specify when the agent should end the conversation:
* **Enable voice hangups:** When enabled, the agent can end the call
* **Reasons:** Specific reasons that the agent should consider to hangup
* **Internal tag:** Tag used to filter and find tickets of this type on the dashboard
Voice hangups
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization/conversation#speech)
Speech
Control the agents speech configuration:
* **Language:** The agent's language. Available options include:
* English (US)
* English (UK)
* English (India)
* Spanish (Latin America)
* Spanish (Spain)
* French
* Chinese
* German
* Hindi
* Japanese
* Portuguese (Portugal)
* Portuguese (Brazil)
* Russian
* Italian
* Korean
* Dutch
* Polish
* **Multilingual languages:** For advanced agents with multilingual capabilities:
* Multilingual (10+ languages)
**Note:** Languages are not limited to this list. The configuration currently reflects **tested** languages available for our agents. If you would like a language that is not on this list, please contact a member of the Giga_ML team._
* **Boosted words:** Words that you agent will prioritize understanding during conversations. This is especially useful for similar words or less common words known by LLMs.
Speech Configuration
[PreviousPhone](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/personalization/phone)
[NextEvaluation](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/tests)
Last updated 4 months ago
---
# Experiments | GigaML
* Navigate to the **Agents > My agents** section in the sidebar and select your existing agent.
* In your agent’s configuration sidebar, go to **Evaluation**.
* Find the **Experiments** section.
* Click the **Create experiment** button on the top right.
* Name your experiment
* Select a control agent and a variant.
* Configure the traffic percentage each agent would encounter and click **Create draft experiment**
* Click the three buttons on the right of the experiment, and either: activate, edit, or delete it.
[PreviousEvaluation](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests)
[NextTest cases](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests/test-cases)
Last updated 5 months ago
---
# Policies | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies#overview)
Overview
Think of policies as your agent's instruction manual. It determines what information the agent can access, how it responds to different situations, when to escalate, and how to represent your brand voice.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies#customize-your-policies)
Customize your policies
Policies are customizable frameworks in markdown, allowing you to add your own formatting, lists, tables, and structure to easily guide how your AI agent should behave during customer interactions!
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies#formatting-markdown)
Formatting markdown
Customize your policies for your brand and business requirements.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies#adding-actions)
Adding actions
Add actions by typing '/' and tell the agent when to call the action.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies#referencing-global-variables)
Referencing global variables
Reference variables by typing '@' and tell the agent when to use default global variables like **@agent\_name** **or** **@current\_date** or global variables you created.
By default, both **agent\_name** or **current\_date** are always available.
[PreviousChat agents](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents)
[NextScenarios](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios)
Last updated 7 months ago
---
# Chat widget | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget#installation)
Installation
Adding the chat widget to your website requires only two steps:
1. Configure the widget settings
2. Add the widget script to your page
[PreviousReview](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/review)
[NextHTML implementation](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/html-implementation)
Last updated 7 months ago
---
# Global variables | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/global-variables#working-with-global-variables)
Working with global variables
Global variables provide a persistent state management system for AI agents throughout a conversation. They allow agents to access and update key information across turns, maintaining context from custom code executions, API calls, and user interactions. This includes:
* Policies
* API responses
* Custom code execution results
* User-provided information
* System initialization data
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/global-variables#global-variables-schema)
Global variables schema
Any valid flat, 1-level deep JSON schema is accepted.
Copy
// Getting started (minimum requirements)
{
"type": "object",
"properties": {}
}
// Example schema
{
"type": "object",
"title": "Hotel Schema",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [\
"propertyID",\
"currentDate",\
"phoneNumber"\
],
"properties": {
"propertyID": {
"type": "string",
"description": "Hotel property ID"
},
"currentDate": {
"type": "string",
"description": "Current date"
},
"phoneNumber": {
"type": "string",
"decription": "Phone number of the caller"
}
},
"description": "Schema for getting hotel property details"
}
[PreviousAdvanced](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced)
[NextInitialization code](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/initialization-code)
Last updated 6 months ago
---
# Webhook events and payloads | GigaML
[call\_finished](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads/call_finished)
[chat\_finished](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads/call_finished-1)
[PreviousMessage types](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/message-types)
[Nextcall\_finished](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads/call_finished)
---
# Finding your agent template ID | GigaML
1. Navigate to your agent in the **Agents** section
2. Select an agent
3. Locate the unique agent template ID below its name. Copy it.
You can create an agent by following the Creating a chat agent or Creating a voice agent guide.
[PreviousHeadless Agent](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent)
[NextService endpoints](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints)
Last updated 7 months ago
---
# Attaching a knowledge base | GigaML
If you have not created an agent yet, refer to creating a voice agent.
1. Navigate to the **Agents > My agents** section in the sidebar and select your existing agent.
2. In your agent’s configuration sidebar, go to **Data sources**.
3. Find the **Knowledge base** section.
4. Click the **Manage knowledge bases** button.
5. Select an existing knowledge base or knowledge bases. Press save changes.
6. Configure how many documents your agent will use from the knowledge base in responses by expanding any attached knowledge base.
You may add as many knowledge bases as necessary per agent.
Attatch a Knowledge Base
[](https://docs.gigaml.com/src/knowledge_base/3_uploading_documents)
[PreviousKnowledge base](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/data-sources/knowledge-base)
[NextAPI overview](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/data-sources/actions)
Last updated 5 months ago
---
# Finding your agent template ID | GigaML
1. Navigate to your agent in the **Agents** section
2. Select an agent
3. Locate the unique agent template ID below its name. Copy it.
You can create an agent by following the Creating a chat agent or Creating a voice agent guide.
[PreviousSingle-page application implementation](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/single-page-application-implementation)
[NextConfiguring the widget](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/configuring-the-widget)
Last updated 7 months ago
---
# Variable naming | GigaML
The chat widget configuration **must** be assigned to a global variable named exactly **CHAT\_WIDGET\_CONFIG**. This is a strict requirement for the widget to function properly.
Copy
// CORRECT - This will work
window.CHAT_WIDGET_CONFIG = { /* configuration */ };
// INCORRECT - These will NOT work
window.chatWidgetConfig = { /* configuration */ };
window.CHAT_CONFIG = { /* configuration */ };
const config = { /* configuration */ };
[PreviousConfiguring the widget](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/configuring-the-widget)
[NextImplementation example](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/implementation-example)
Last updated 7 months ago
---
# Scenarios | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios#overview)
Overview
Scenario policies house your Standard Operating Procedures (SOPs) for common customer interactions. Each scenario should be created as a separate markdown file.
Create a Scenario
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios#key-components)
Key components
1. **Scenario description**: Define when this scenario typically occurs and what triggers it.
2. **Handling steps:** Provide a sequential list of actions the agent should take when managing this scenario.
3. **Special considerations**: Note any exceptions, nuances, or special cases relevant to this scenario.
4. **Additional notes:** Link to helpful resources, systems, or information the agent may need.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios#calling-actions)
Calling actions
You can add instructions to call actions in any scenario by typing '/' and telling the agent when to call the action.
If you are unfamiliar with actions, you can learn more here.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios#accessing-global-variables)
Accessing global variables
Reference variables by typing '@' and tell the agent when to use default global variables like **@agent\_name** **or** **@current\_date** or global variables you created.**"**
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios#best-practices)
Best practices
1. Create separate markdown files for each distinct scenario
2. Use clear, step-by-step instructions
3. Include example customer inquiries and responses as well as how to handle them
4. Test and update scenario policies upon creation and as the SOP changes
While you aren't required to create a file per SOP, they significantly enhance your agent's ability to handle specific situations effectively.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios#example-scenario-general-information)
Example scenario - General information
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios#example-scenario-bell-desk)
Example scenario - Bell desk
[PreviousPolicies](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies)
[NextMulti-Step Scenario Guide](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/multi-step-scenario-guide)
Last updated 6 months ago
---
# Implementation example | GigaML
Copy
useEffect(() => {
if (typeof window === "undefined") return;
// Ensure environment variables are set on window before script execution
window.CHAT_WIDGET_CONFIG = {
agent_template_id: "agent_template_6e8a9dd9-5185-4b75-9a10-6a4338c0d97e",
company_name: "GigaML",
tagline: "Ready when you are.",
icon_url: "https://gigaml-logo.s3.us-east-1.amazonaws.com/testLogo.png",
primary_color: "#000",
primary_text_color: "#fff",
secondary_color: "rgb(245 245 245)",
secondary_text_color: "#000",
default_questions: [\
{\
label: "I'm having issues logging in", // On click will send this message sent in your chat widget\
type: "message",\
route: null\
},\
{\
label: "Email support",\
type: "url", // Opens a new tab based on the url route provided\
route: "https://your-website-url.com"\
},\
]
};
}, []);
[PreviousVariable naming](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/variable-naming)
[NextAdding the widget to your site](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/adding-the-widget-to-your-site)
Last updated 2 months ago
---
# HTML implementation | GigaML
Copy
**Important:** The configuration object **must** be named **CHAT\_WIDGET\_CONFIG** for the widget to function properly. Using any other variable name will prevent the widget from loading correctly.
[PreviousChat widget](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget)
[NextSingle-page application implementation](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/single-page-application-implementation)
Last updated 2 months ago
---
# Test cases | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests/test-cases#attaching-a-test-case)
Attaching a test case
Test cases are based on prior conversations with an agent. Connect a prior conversation to your agent as a test case by going to **Tickets**, selecting any ticket row and pressing the **Test icon** near the top right hand corner of the ticket sheet.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests/test-cases#evaluating-a-test-case)
Evaluating a test case
Configure your test case in **Agents > My agents** by going to **Tests > Test cases** on the sidebar. Before running your tests, you may:
* **Evaluate Sections:** Disabling **Evaluate** in any Test Case Step will ensure that the step is not included in the test. You may want to do this when the test is evaluating a conversation and you do not want to test the opening message or a specific part of the conversation.
* **Should Pass / Fail:** Click the **Should Pass** or **Should Fail** badge to control the expected result of the test case. A test should pass if you are expecting the agent to be able to recreate the test case with limited variation. A test should fail if the agent is unable to recreate the test case with limited variation from the original.
* **Modifying Test Steps:** You may modify the agents response to the user's input for each step, including API calls and responses.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests/test-cases#running-test)
Running test
Run tests on all your test cases when you are ready by clicking **Run All**.
[PreviousExperiments](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests/experiments)
[NextTest results](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests/test-results)
Last updated 6 months ago
---
# Test results | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests/test-results#analyzing-results)
Analyzing results
Test results are provided in as a test group and are generated when you click **Run All** inside of Test Cases. You will be provided the status of each test result, whether it has passed or failed.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests/test-results#view-a-test-result)
View a test result
Click into any test result to get additional information, including:
* **Status:** Failed or Passed
* **Steps Completed:** Understand how many test steps were completed, otherwise steps completed should match the total number of possible steps if status is passed.
* **Expected to Pass:** Whether the test was expected to pass or fail.
* **Success rate:** The percentage of steps that passed successfully.
You can understand an ideal response to any test result step by expanding an individual step. You will be able to compare the ideal response to the newly generated test response in order to troubleshoot why the test step passed or failed.
[PreviousTest cases](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests/test-cases)
[NextAdvanced](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced)
Last updated 6 months ago
---
# Escalate ticket | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/client-endpoints/escalate-ticket#endpoint-details)
Endpoint details
Copy
PUT https://company_name.com/escalate_ticket_endpoint
Headers: Required authentication headers
Response codes:
200 OK: Ticket escalated successfully
404 Not Found: Ticket not found
401 Unauthorized: Invalid API key
500 Internal Server Error: Server error
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/client-endpoints/escalate-ticket#required-parameters)
Required parameters
Parameter
Type
Required
Description
`ticket_id`
string
Yes
A unique identifier for this conversation session
[PreviousSend message](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/client-endpoints/send-message)
[NextMessage types](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/message-types)
Last updated 7 months ago
---
# Service endpoints | GigaML
Endpoint
Method
Webhook
Description
`https://agents.gigaml.com/webhook/initiate-session`
POST
Service
Start a new conversation with an agent
`https://agents.gigaml.com/webhook/receive-message`
POST
Service
Receive a user message from the conversation
`https://agents.gigaml.com/webhook/close-session`
PUT
Service
End the conversation session
[PreviousFinding your agent template ID](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/finding-your-agent-template-id)
[NextInitiate a session](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/initiate-a-session)
Last updated 7 months ago
---
# Close a session | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/close-a-session#endpoint-details)
Endpoint details
Copy
PUT https://agents.gigaml.com/webhook/close-session
Response codes:
200 OK: Session closed successfully
404 Not Found: Session not found
401 Unauthorized: Invalid API key
500 Internal Server Error: Server error
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/close-a-session#request-parameters)
Request parameters
Parameter
Type
Required
Description
`ticket_id`
string
Yes
The identifier for the conversation session
`reason`
string
Yes
The reason for closing the session
`status`
string
Yes
Enum defining how the session was closed for logging
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/close-a-session#example-request)
Example request
Copy
{
"ticket_id": "unique-ticket-identifier",
"reason": "user_request",
"status": "COMPLETED"
}
[PreviousReceive a message](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/receive-a-message)
[NextClient endpoints](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/client-endpoints)
Last updated 7 months ago
---
# Client endpoints | GigaML
Endpoint
Method
Webhook
Description
`https://company_name.com/send_messge_endpoint`
POST
Client
Receive an agent message from the conversation
`https://company_name.com/escalate_ticket_endpoint`
POST
Client
Escalate the conversation
[PreviousClose a session](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/close-a-session)
[NextSend message](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/client-endpoints/send-message)
Last updated 7 months ago
---
# Rules | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/rules#overview)
Overview
The rules policy establishes **strict** guidelines that govern your agent's decision-making processes. These rules take precedence over other policies when conflicts arise.
Create Rules
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/rules#key-components)
Key components
1. **Core principles**: Define the fundamental principles that guide all agent interactions
2. **Prohibited actions:** Specify what your agent should never do. Note that common prohibitions (violence, harassment, etc.) are handled automatically by default.
3. **Transfer rules**: Detail the exact procedures for executing transfers, including:
1. What to communicate to the customer before the transfer
2. What information to pass to the human agent or specialized department
3. How to introduce or what to do when connected with the human agent or specialized department
4. How to handle emotional or sensitive issues
4. **Data handling**: Establish how customer information should be processed and protected.
**Note:** Transfer reasons and associated phone numbers are maintained in **Personalization > Conversation > Transfers**. You can find more information about this here.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/rules#best-practices)
Best practices
* Be explicit and specific with the rules provided
* Test and iterate based on the agent's performance
* Consider regulatory requirements for your industry or actions that agent should never take associated with your business
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/rules#example-rules-policy)
Example rules policy
[PreviousBrand](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/messaging)
[NextData sources](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/data-sources)
Last updated 6 months ago
---
# Initialization code | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/initialization-code#implementation)
Implementation
* Initialization code runs before the conversation starts
* May access both code blocks and actions
* Returns a dictionary that updates the variable store
* All returned values MUST match keys defined in the variable store schema
Initialization Code
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/initialization-code#initialization-input-schema)
Initialization input schema
The initialization input schema is a valid flat, 1-level deep JSON schema telling the agent what values it can expect prior to starting the conversation. This can include variables like unique IDs.
Copy
{
"type": "object",
"required": [],
"properties": {}
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/initialization-code#initialization-values)
Initialization values
Initialization values are received by the initialization code block as are based on the aforementioned input schema.
Copy
# Initialization Function for Chat Conversations
# ---------------------------------------------
# This function runs at the start of each conversation to set up initial variables.
# Input:
# - All values from your Input Schema are passed to this function
# - These values come from the initialization_values dictionary
# Output:
# - Returns a dictionary of values that will be available throughout the conversation
# 1. Extract variables from the input schema
some_variable = initialization_values.get("your_input_schema_variable_1")
another_variable = initialization_values.get("your_input_schema_variable_2")
# 2. You can add any custom processing logic here
# For example:
# user_preference = my_api_call(some_variable)
# 3. Return dictionary with all information we want available in our global variables
# Values returned will be added to your global variables and can be used in API calls or interpolated into your policies
return {
"some_variable": some_variable,
"another_variable": another_variable
# Add any additional variables you want to make available in global variables:
# "user_preference": user_preference
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/initialization-code#callable-functions)
Callable functions
The initialization code supports callable functions such as actions and code blocks. You may use initialization values provided and/or local variable generated in python. Multiple actions and/or code blocks may be used in your initialization code.
Copy
# Example - Callable function
# Remember these functions must exist in "Actions" or "Code blocks"
initialization_values = dict() # JSON schema (flat, 1-level deep or empty)
# Custom action provided that does not require an initialization value
popular_transactions = get_popular_transactions()
# Custom action provided requiring an initialization value
user_transactions = user_transactions(user_id=initialization_values['user_id'])
# Note: all actions return responses as strings
return {
"popular_transactions": popular_transactions,
"user_transactions": user_transactions
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/initialization-code#other-values)
Other values
You may write local code in the initialization code that is unrelated to the initialization input schema. Anything that can be generated in the initialization code can be used and saved to the global variables dictionary. This can include variables like the current date.
**Note: external packages are not supported at this time.**
Copy
# Example - Generating the current date on initialization
from datetime import datetime
# Get the current date formatted as "February 18, 2025"
current_date = datetime.now().strftime("%B %d, %Y")
# Optionally remove any leading zero from the day (if needed)
current_date = current_date.replace(" 0", " ")
# The global variables must have the value "current_date". You may pass a partial dictionary.
return {
"current_date": current_date,
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/initialization-code#return-format)
Return format
Initialization code is received (e.g. phone number) or generated (e.g. current date) before the conversation begins. Provide a partial or full dictionary to update global variables before the agent speaks.
Copy
{
"current_date": "04/25/2024", # Generate the current date in the hosted code
"order_id": order_id # Provided as an initialization value in the chat
"weather": "Sunny" # Can be returned via an API call
}
[PreviousGlobal variables](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/global-variables)
[NextPost Conversation Code](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code)
Last updated 6 months ago
---
# Headless Agent | GigaML
Use these endpoints enable you to initiate conversations, send messages, and manage sessions programmatically.
Endpoint
Method
Webhook
Description
`https://agents.gigaml.com/webhook/initiate-session`
POST
Service
Start a new conversation with an agent
`https://agents.gigaml.com/webhook/receive-message`
POST
Service
Receive a user message from the conversation
`https://agents.gigaml.com/webhook/close-session`
PUT
Service
End the conversation session
`https://company_name.com/send_messge_endpoint`
POST
Client
Receive an agent message from the conversation
`https://company_name.com/escalate_ticket_endpoint`
POST
Client
Escalate the conversation
All endpoints require authentication with your API key.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent#authentication)
Authentication
All webhook endpoints require authentication using an API key. Include your API key in the Authorization header as a Bearer token:
Copy
Authorization: Bearer YOUR_API_KEY
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent#integration-flow-overview)
Integration flow overview
1
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent#initiate-a-session)
Initiate a session
Start a conversation with the agent using our `/initiate-session` endpoint
2
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent#send-message)
Send message
The agent sends the user a welcome message using your `/send-message` endpoint
3
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent#receive-message)
Receive message
Receive user messages using the `/receive-message` endpoint
4
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent#send-message-1)
Send message
The agent sends the user a message using your `/send-message` endpoint
5
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent#close-the-session)
Close the session
End the conversation using the `/close-session` endpoint
[PreviousTroubleshooting](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/troubleshooting)
[NextFinding your agent template ID](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/finding-your-agent-template-id)
Last updated 6 months ago
---
# Inbound Scenario Guide | GigaML
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/inbound-scenario-guide#what-are-inbound-scenarios)
What Are Inbound Scenarios?
------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Inbound scenarios are flexible conversation frameworks that help agents handle incoming customer calls effectively. Unlike outbound scripts, these provide guidance for responding to various customer intents while maintaining natural conversation flow rather than strict steps.
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/inbound-scenario-guide#basic-structure)
Basic Structure
-------------------------------------------------------------------------------------------------------------------------------------------------
Every inbound scenario follows this pattern:
Copy
When Customer says/asks: [trigger phrase or intent]
Response approach:
→ Provide solution or next steps (can be several bullet points)
→ Confirm resolution or offer alternatives
* * *
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/inbound-scenario-guide#writing-inbound-scenarios)
Writing Inbound Scenarios
---------------------------------------------------------------------------------------------------------------------------------------------------------------------
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/inbound-scenario-guide#scenario-naming)
Scenario Naming
* **Intent-based**: "When Dasher calls about..." or "When customer reports..."
* **Problem-focused**: Clear description of the customer's issue or need
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/inbound-scenario-guide#response-flow-structure)
Response Flow Structure
* **Acknowledge** → Show you understand their concern
* **Provide** → Offer solutions, information, or next steps
* **Confirm** → Ensure the issue is resolved or properly escalated
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/inbound-scenario-guide#essential-principles)
Essential Principles
-----------------------------------------------------------------------------------------------------------------------------------------------------------
**Stay flexible** - Follow customer's pace and needs, not rigid scripts
**Listen actively** - Let customers fully explain before jumping to solutions
**Confirm understanding** - "So if I understand correctly, you're saying..."
**Offer alternatives** - Always have a Plan B if first solution doesn't work
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/inbound-scenario-guide#common-patterns)
Common Patterns
-------------------------------------------------------------------------------------------------------------------------------------------------
Copy
1. Acknowledge the issue
3. Provide appropriate solution steps
4. Confirm resolution or offer additional assistance
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/inbound-scenario-guide#best-practices)
Best Practices
-----------------------------------------------------------------------------------------------------------------------------------------------
Before using your inbound scenarios, ensure:
* Each scenario has a customer intent
* Solutions are explained in simple, actionable steps
* Every scenario includes confirmation or have an escalation path
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/inbound-scenario-guide#filled-in-example)
Filled in Example
-----------------------------------------------------------------------------------------------------------------------------------------------------
Copy
# Account Access and Login Support
## Scenario 1: Password Reset Issues
**When customer's intent is:** "I can't reset my password" or "I don't remember my password"
**Response:**
* Verify the email address on their account matches what they're using
* If the email is correct, resend a new password reset link
* Have them check their spam/junk folder for the reset email
* Guide them through clicking the link and creating a new password
* The new password must be at least 8 characters with one uppercase letter, one number, and one special character
* Once they've created the new password, have them try logging in immediately to confirm it works
* Confirm issue resolution, if not, transfer_call
## Scenario 2: Account Locked Due to Security
**When customer's intent is:** "My account is locked" or "I got a security alert"
**Response:**
* Explain that accounts are typically locked after multiple failed login attempts or suspicious activity
* Once identity is confirmed, unlock the account in the system
* Guide them through logging in with their current password
* Recommend they update their password if they suspect it may have been compromised
* Enable additional security features like two-factor authentication to prevent future lockouts
## Scenario 3: Two-Factor Authentication Not Working
**When customer calls about:** "I'm not getting my verification code" or "My authenticator app isn't working"
**Response:**
* Acknowledge the verification issue and ask which method they're using (SMS, email, or authenticator app)
* If using SMS, verify the phone number on their account is correct and ask them to wait 2-3 minutes for delivery
* If using an authenticator app, guide them to refresh the app and ensure their device's time is set correctly
* Provide them with one of their backup codes if they have them saved
* Temporarily disable two-factor authentication so they can access their account
* Once they're logged in, help them set up two-factor authentication again and generate new backup codes
* Strongly recommend they save the backup codes in a secure location for future use
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/inbound-scenario-guide#template-structure)
Template Structure
-------------------------------------------------------------------------------------------------------------------------------------------------------
Copy
# [Call Flow Name]
## Scenario 1: [Issue Type]
**When customer's intent is:** "[Trigger phrases]"
**Response:**
* Guide through troubleshooting steps (This can be several steps)
* Ask if their issue has been resolved/transfer if needed
## Scenario 2: [Issue Type]
**When customer's intent is:** "[Trigger phrases]"
**Response:**
* Guide through troubleshooting steps (This can be several steps)
* Ask if their issue has been resolved/transfer if needed
## Scenario 3: [Issue Type]
**When customer's intent is:** "[Trigger phrases]"
**Response:**
* Guide through troubleshooting steps (This can be several steps)
* Ask if their issue has been resolved/transfer if needed
Use these templates as starting points and adapt them to your specific customer service needs and company processes.
[PreviousMulti-Step Scenario Guide](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/scenarios/multi-step-scenario-guide)
[NextSupporting docs](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/policies/general)
Last updated 2 months ago
---
# Code blocks | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/code-blocks#overview)
Overview
When configured properly, code blocks let you programmatically:
* Make asynchronous API calls
* Run custom code in the cloud
* Process, store, and manage a JSON response
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/code-blocks#code)
Code
Code blocks update the global variables and provide context to the agent.
Copy
# Input schema the code block with receive
input_schema = dict() # JSON schema (flat, 1-level deep or empty)
# Initialize or process your global variables based on the logic required
store_updates = dict() # Type: dict (flat, 1-level deep)
assistant_message: str = "" # Type: str (usually a status or response message)
# Add your custom code here...
# Return a dictionary in the following format (required)
return {
"store_updates": store_updates, # Partial or full global variables (flat JSON schema - 1 level deep)
"assistant_message": assistant_message # Full API response or custom code response (string)
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/code-blocks#input-schema)
Input schema
The code block input schema is a valid flat, 1-level deep JSON schema telling the agent what values it can expect anytime during or before the conversation.
Copy
{
"type": "object",
"properties": {},
"required": []
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/code-blocks#example)
Example
Our agents can do anything a human support specialist can do. For example, you are the owner and operator a hotel and have asked Giga_ML_ to manage your reservation requests. You can easily add your business logic to a code block to allow your agents to receive and make reservation requests on your behalf.
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/code-blocks#reservation-request-input-schema)
Reservation request input schema
Copy
{
"type": "object",
"title": "Reservation Request Schema",
"required": [\
"propertyID",\
"startDate",\
"endDate",\
"guestFirstName",\
"guestLastName",\
"guestCountry",\
"guestZip",\
"guestEmail",\
"rooms",\
"adults",\
"children",\
"paymentMethod",\
"roomTypeID"\
],
"properties": {
"rooms": {
"type": "number",
"maximum": 4,
"minimum": 1,
"description": "Number of rooms for the reservation"
},
"adults": {
"type": "number",
"minimum": 1,
"description": "Number of adults for the reservation"
},
"endDate": {
"type": "string",
"description": "Check-out date in format YYYY-MM-DD (e.g., 2025-02-14)"
},
"children": {
"type": "number",
"minimum": 0,
"description": "Number of children for the reservation"
},
"guestZip": {
"type": "string",
"description": "ZIP Code"
},
"startDate": {
"type": "string",
"description": "Check-in date in format YYYY-MM-DD (e.g., 2025-02-14)"
},
"guestEmail": {
"type": "string",
"description": "Email of the guest who is making the reservation"
},
"guestPhone": {
"type": [\
"string",\
"null"\
],
"description": "Main phone number of the guest who is making the reservation"
},
"propertyID": {
"type": [\
"string",\
"null"\
],
"description": "Property ID",
"fetch_from_store": true
},
"roomTypeID": {
"type": [\
"string"\
],
"description": "ID for the room you are reserving"
},
"guestCountry": {
"type": "string",
"default": "US",
"maxLength": 2,
"minLength": 2,
"description": "Valid ISO-Code for Country (2 characters)"
},
"guestLastName": {
"type": "string",
"description": "Last name of the guest who is making the reservation"
},
"paymentMethod": {
"enum": [\
"cash",\
"credit",\
"ebanking",\
"pay_pal"\
],
"type": "string",
"description": "Payment Method of choice. MUST BE AN ENUM. Choices are cash, credit, ebanking, or pay_pal"
},
"guestFirstName": {
"type": "string",
"description": "First name of the guest who is making the reservation"
}
},
"description": "Schema for adding a reservation to the selected property"
}
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/code-blocks#reserversation-request-code)
Reserversation request code
Copy
assert propertyID is not None
assert startDate is not None
assert endDate is not None
assert guestFirstName is not None
assert guestLastName is not None
assert guestCountry is not None
assert guestZip is not None
assert guestEmail is not None
assert guestPhone is not None
assert roomTypeID is not None
rooms_obj = [\
{\
"roomTypeID": roomTypeID,\
"quantity": int(rooms)\
}\
]
adults_obj = [\
{\
"roomTypeID": roomTypeID,\
"quantity": int(adults)\
}\
]
children_obj = [\
{\
"roomTypeID": roomTypeID,\
"quantity": int(children)\
}\
]
response_str = await book_reservation(
propertyID=propertyID,
startDate=startDate,
endDate=endDate,
guestFirstName=guestFirstName,
guestLastName=guestLastName,
guestCountry=guestCountry,
guestZip=guestZip,
guestEmail=guestEmail,
guestPhone=guestPhone,
rooms=rooms_obj,
adults=adults_obj,
children=children_obj,
paymentMethod=paymentMethod,
)
response_json = json.loads(response_str)
store_updates = dict()
if response_json.get("success") != True:
assistant_message = f"Failed to make a reservation. Fix the issue based on this response: '{response_json}'. If you are unable to fix the issue, ask the customer if they'd like to speak to a senior staff member."
return {
"assistant_message": assistant_message,
"store_updates": store_updates,
}
store_updates["reservationID"] = response_json.get("reservationID")
store_updates["status"] = response_json.get("status")
store_updates["guestID"] = response_json.get("guestID")
store_updates["guestFirstName"] = response_json.get("guestFirstName")
store_updates["guestLastName"] = response_json.get("guestLastName")
store_updates["guestGender"] = response_json.get("guestGender")
store_updates["guestEmail"] = response_json.get("guestEmail")
store_updates["startDate"] = response_json.get("startDate")
store_updates["endDate"] = response_json.get("endDate")
store_updates["dateCreated"] = response_json.get("dateCreated")
store_updates["grandTotal"] = response_json.get("grandTotal")
assistant_message = f"Reservation created successfully. Reservation ID: {store_updates['reservationID']}"
return {
"assistant_message": assistant_message,
"store_updates": store_updates,
}
[PreviousPost Conversation Code](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code)
[NextReview](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/review)
Last updated 6 months ago
---
# Troubleshooting | GigaML
1. Verify that your agent template ID is correct
2. Ensure the configuration object is named exactly **CHAT\_WIDGET\_CONFIG**
3. Make sure the script is loading properly (check network tab in developer tools)
4. Check browser console for any error messages
[](https://docs.gigaml.com/src/agent_endpoints/4_message_types)
[PreviousAdding the widget to your site](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/adding-the-widget-to-your-site)
[NextHeadless Agent](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent)
Last updated 6 months ago
---
# Receive a message | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/receive-a-message#endpoint-details)
Endpoint details
Copy
POST https://agents.gigaml.com/webhook/receive-message
Response codes:
200 OK: Message queued successfully or message already processed
404 Not Found: Session not found
401 Unauthorized: Invalid API key
500 Internal Server Error: Server error
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/receive-a-message#request-parameters)
Request parameters
Parameter
Type
Required
Description
`ticket_id`
string
Yes
The identifier for the conversation session
`message_id`
string
Yes
A unique identifier for this message
`message`
object
Yes
The message object containing role, content, and timestamp
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/receive-a-message#message-object)
Message object
Field
Type
Required
Description
`role`
Literal\[“user”\]
Yes
The role of the message sender
`content`
string or array
Yes
The message content (text or structured content)
`timestamp`
number
No
Unix timestamp in milliseconds
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/receive-a-message#example-request)
Example request
Copy
{
"ticket_id": "unique-ticket-identifier",
"message_id": "unique-message-identifier",
"message": {
"role": "user",
"content": "User's message text",
"timestamp": 1742268182058
}
}
[PreviousInitiate a session](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/initiate-a-session)
[NextClose a session](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/close-a-session)
Last updated 7 months ago
---
# Events | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/events#overview)
Overview
The event data model for the GigaML AI Agent specifies how interactions between callers and the AI Agent are captured and logged. It covers conversation details, user inputs, AI Agent responses, and outcomes.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/events#purpose)
Purpose
The main goals of this data model are to:
* Log the complete flow of conversations
* Help debug AI Agent interactions
* Allow for performance monitoring and identify improvements
* Enable analysis of user and AI Agent behavior patterns
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/events#core-tracking-fields)
Core Tracking Fields
Field
Definition
Use Case
event\_id
Unique identifier for each event
Tracking/debugging events and flows
call\_id
Unique identifier for tracking a user's session from start to finish
Tracking/debugging events and flows
external\_conversation\_id
External conversation ID (ex. Amazon connect Contact ID which is created prior to transferring to GigaML)
Integration with AWS Connect
timestamp
Recorded date-time of event in ISO 8601 format (UTC), e.g., YYYY-MM-DDTHH:mm:ss.sssZ
Temporal analysis of interactions, human-readable logs
event\_order
Sequential order of the event within the call, starting from 1
Guarantees event sequence, aids debugging
event\_type
Type of event in the interaction flow (e.g., "assistant\_speech", "user\_speech", "transfer")
Understanding interaction flow and abandonment points
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/events#system-fields)
System Fields
Field
Definition
Use Case
agent\_id
Unique identifier for the AI agent managing the session
System tracking
agent\_version
Software or model version of the AI agent
Version tracking
parameters
Any additional metadata tied to the unique event, beyond dedicated fields like reason
Flexible field for event-specific data
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/events#optional-fields)
Optional Fields
These fields provide additional context depending on the event\_type.
Field
Definition
Use Case
message
Text or tool calls associated with the event. Source (AI Agent or user) depends on event\_type. Can include function calls and their arguments when the agent uses tools
Tracking spoken content, tool usage, and responses from both the AI Agent and the user
reason
The reason why the AI agent initiated a transfer or ended the conversation (e.g., "user requested transfer", "issue resolved", "escalation policy triggered"). Null if the user disconnected or if the event is not a transfer/end initiated by the agent
Understanding agent decision-making for transfers and call endings
language
ISO 639-1 two-letter language code (e.g., 'en' for English, 'es' for Spanish), ISO 639-2/639-3 three-letter code for less common languages, or 'multi' when multiple languages are detected or multilingual mode is enabled
Language-specific analysis and localization
dtmf\_input
The DTMF digits/characters pressed by the user during the interaction
Tracking and analyzing user menu selections and numeric inputs
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/events#potential-event_type-values)
Potential event\_type Values
The following are potential values for the event\_type field. The specific set used may depend on the final implementation details.
event\_type
Definition
Data Location
assistant\_speech
The AI Agent delivers a prompt or message
Content in message
user\_speech
The user provides a spoken response
Content in message
transfer
The call is transferred or redirected to another flow, queue, or number
Agent's motivation in reason
menu\_option\_chosen
If DTMF or specific keyword menus are used, this indicates a choice
Chosen option in parameters, DTMF value in dtmf\_input field
escalation\_triggered
The system triggers an escalation based on rules (e.g., too many retries)
Agent's motivation in reason, specific rule/details might be in parameters
call\_started
Marks the beginning of the call session within the GigaML system
\-
call\_ended
Marks the end of the call session. If ended by the agent, the motivation should be in reason. If ended by the user (hang-up), reason will be null
\-
error\_occurred
A system error happened during processing
Error details might be in parameters
tool\_call
The AI Agent makes a function/tool call to perform an action or retrieve information
Tool name, arguments, and call ID in message
tool\_response
The response received from a tool call
Response content in message, associated tool\_call\_id in parameters
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/events#implementation-notes)
Implementation Notes
* **call\_id**: call\_id is used for tracking the session.
* **external\_conversation\_id**: Present in external\_conversation\_id field from the source system.
* **parameters**: Available through custom\_fields. Can potentially consolidate multiple fields into a JSON string based on event\_type to hold additional context-specific details not covered by dedicated fields (e.g., error messages, transfer destinations, tool call IDs). Use the reason field for agent motivation in transfer/end events.
* **message**: Can store various content types including text, audio transcriptions, tool calls (with function name and arguments), and tool responses based on the OpenAIMessage model structure.
* **tool calls**: When the event\_type is "tool\_call", the message field should contain the relevant function information including name, arguments, and call ID.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/events#data-flow-architecture)
Data Flow Architecture
The event-level data model captures granular interactions within each call session:
1. Call initiation generates call\_id and external\_conversation\_id.
2. Each interaction or system step creates a new event record containing:
* A unique event\_id
* The timestamp (in ISO 8601 UTC format)
* The event\_order (sequential counter within the call)
* The appropriate event\_type and related fields (e.g., message for speech, reason for agent-initiated transfers/ends, parameters for additional context)
3. Events accumulate sequentially throughout the session, identified by the common call\_id, creating a complete timeline of the interaction.
4. The session concludes.
[Previouschat\_finished](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads/call_finished-1)
[NextExternal Telephony](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/external-telephony)
Last updated 6 months ago
---
# Send message | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/client-endpoints/send-message#endpoint-details)
Endpoint details
Copy
POST https://company_name.com/send_messge_endpoint
Headers: Required authentication headers
Response codes:
200 OK: Message queued successfully or message already processed
404 Not Found: Session not found
401 Unauthorized: Invalid API key
500 Internal Server Error: Server error
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/client-endpoints/send-message#request-parameters)
Request parameters
Parameter
Type
Required
Description
`ticket_id`
string
Yes
A unique identifier for this conversation session
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/client-endpoints/send-message#request-payload)
Request payload
Parameter
Type
Required
Description
`ticket_id`
string
Yes
A unique identifier for this conversation session
`message_id`
string
Yes
A unique identifier for this message
`message`
object
No
Message types
[](https://docs.gigaml.com/src/agent_endpoints/3_client_endpoints#escalate-ticket)
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/client-endpoints/send-message#example-request)
Example request
Copy
{
"message_id": "550e8400-e29b-41d4-a716-446655440000",
"ticket_id": "ticket-123456",
"message": {
"content": [\
{\
"type": "text",\
"name": "Agent Name",\
"text": "Hello, how can I help you today?"\
}\
],
"role": "assistant"
}
}
[PreviousClient endpoints](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/client-endpoints)
[NextEscalate ticket](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/client-endpoints/escalate-ticket)
Last updated 7 months ago
---
# Adding the widget to your site | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/adding-the-widget-to-your-site#for-static-websites-html)
For static websites (HTML)
1. Add the configuration script in the `` or `` section of your HTML:
Copy
1. Add the widget script right after your configuration:
Copy
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/adding-the-widget-to-your-site#for-react-applications)
For React applications
1. Create a component for the chat widget:
Copy
import { useEffect } from 'react';
const ChatWidget = () => {
useEffect(() => {
if (typeof window === "undefined") return;
// Configure the widget
window.CHAT_WIDGET_CONFIG = {
agent_template_id: "YOUR_AGENT_TEMPLATE_ID",
company_name: "Your Company",
// Add other required configuration options
};
// Load the script
const script = document.createElement('script');
script.src = "https://widget.gigaml.com/inject-gigaml.js";
script.defer = true;
document.head.appendChild(script);
// Clean up on unmount
return () => {
if (script.parentNode) {
document.head.removeChild(script);
}
};
}, []);
return null; // This component doesn't render anything
};
export default ChatWidget;
1. Import and use the component in your layout or main component:
Copy
import ChatWidget from './ChatWidget';
const App = () => {
return (
{/* Your app content */}
);
};
[PreviousImplementation example](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/implementation-example)
[NextTroubleshooting](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/troubleshooting)
Last updated 6 months ago
---
# Conversation | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/personalization/conversation#welcome-messaging)
Welcome messaging
Includes messages and who speaks first, either the AI agent or the human.
Messages include:
* **Welcome message:** Customizable message from the agent when the conversation begins
* **Variation:** Whether the welcome message should be this **exact** message every time of a smart variation.
* **Delay:** The amount of time the agent should wait after the last message (or start of conversation) before saying the welcome message.
**Note:** You can chain welcome messages to let the agent have a train-of-thought at the start of the conversation and reference {agent\_name} in the message.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/personalization/conversation#example-welcome-messages)
Example welcome messages
Welcome messages are flexible and may include [global variables](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/global-variables)
, such as:
* Hello, how many I help you today?
* Hi there, thank you calling {company\_name}.
* Hello, this is {agent\_name}. How may I assist you today!
* Hello, this is {agent\_name}, thank you for calling {company\_name}. How may I help you today?
**Note:** agent\_name is available in global variables by default. To use another global variable, such as company\_name, you would have to add it to the global variables configuration.
Messaging
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/personalization/conversation#inactivity)
Inactivity
Manage how your agent responds to periods of user inactivity:
* **Enable inactivity flow:** When enabled, the agent will address inactive conversations in the order provided.
* **Steps:** Define a sequence of messages or actions when users go quiet
* **Wait time since last message:** Duration of inactivity since the last inactivity message the agent should wait until executing the next step
* **Close conversation:** Automatically end conversations after inactivity steps complete
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/personalization/conversation#chat-hangups)
Chat hangups
Specify when the agent should end the conversation:
* **Enable chat hangups:** When enabled, the agent can end the chat
* **Reasons:** Specific reasons that the agent should consider to hangup
* **Internal tag:** Tag used to filter and find tickets of this type on the dashboard
Chat hangups
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/personalization/conversation#language)
Language
Control the agents speech configuration:
* **Language:** The agent's language. Available options include:
* English (US)
* English (UK)
* English (India)
* Spanish (Latin America)
* Spanish (Spain)
* French
* Chinese
* German
* Hindi
* Japanese
* Portuguese (Portugal)
* Portuguese (Brazil)
* Russian
* Italian
* Korean
* Dutch
* Polish
* **Multilingual languages:** For advanced agents with multilingual capabilities:
* Multilingual (10+ languages)
**Note:** Languages are not limited to this list. The configuration currently reflects **tested** languages available for our agents. If you would like a language that is not on this list, please contact a member of the Giga_ML team._
Language Configuration
[PreviousIdentities](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/personalization/identities)
[NextEvaluation](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/tests)
Last updated 4 months ago
---
# Initiate a session | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/initiate-a-session#endpoint-details)
Endpoint details
Copy
POST https://agents.gigaml.com/webhook/initiate-session
Response codes:
200 OK: Session initiated successfully or session already exists
401 Unauthorized: Invalid API key
500 Internal Server Error: Server error
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/initiate-a-session#request-parameters)
Request parameters
Parameter
Type
Required
Description
`ticket_id`
string
Yes
A unique identifier for this conversation session
`agent_template_id`
string
Yes
The ID of the agent template to use for this conversation
`initialization_values`
object
No
Optional key-value pairs your agent needs to start the conversation
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/initiate-a-session#example-request)
Example request
Copy
{
"ticket_id": "unique-ticket-identifier",
"agent_template_id": "your-agent-template-id",
"initialization_values": {
"customer_name": "John Doe",
"customer_email": "[email protected]"
}
}
[PreviousService endpoints](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints)
[NextReceive a message](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/service-endpoints/receive-a-message)
Last updated 6 months ago
---
# Message types | GigaML
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/message-types#text)
Text
Send a simple text-only message to the assistant.
Copy
{
"role": "user",
"content": "How can I reset my password?",
"timestamp": 1742268182058
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/message-types#image)
Image
Send a single image to the assistant for analysis or reference.
Copy
{
"role": "user",
"content": {
"type": "image",
"image_url": {
"url": "https://example.com/image.jpg"
}
},
"timestamp": 1742268182058
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/message-types#mixed-content)
Mixed content
Combine text and multiple images in a single message.
Copy
{
"role": "user",
"content": [\
{\
"type": "text",\
"text": "I'm having an issue with this product:"\
},\
{\
"type": "image",\
"image_url": {\
"url": "https://example.com/image1.jpg"\
}\
},\
{\
"type": "image",\
"image_url": {\
"url": "https://example.com/image2.jpg"\
}\
}\
],
"timestamp": 1742268182058
}
[PreviousEscalate ticket](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/headless-agent/client-endpoints/escalate-ticket)
[NextWebhook events and payloads](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads)
Last updated 7 months ago
---
# Configuring the widget | GigaML
**Parameter**
**Type**
**Required**
**Description**
agent\_template\_id
string
Yes
Your unique GigaML agent template ID
company\_name
string
Yes
Your company name displayed in the widget
primary\_color
string
Yes
Main color for buttons and highlights (hex or rgb)
primary\_text\_color
string
Yes
Text color for primary elements
secondary\_color
string
Yes
Secondary color for the widget (hex or rgb)
secondary\_text\_color
string
Yes
Text color for secondary elements
tagline
string
Yes
Short tagline displayed in the widget
icon\_url
string
Yes
URL to your company icon or logo
position
string
No
Widget position: “bottom-right” (default), “bottom-left”, “top-right”, “top-left”
org\_id
string
No
Your organization ID if applicable
default\_questions
array
No
Array of default questions or links
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/configuring-the-widget#variable-naming-requirement)
[](https://docs.gigaml.com/src/integrations/chat_widget/index#variable-naming-requirement)
[PreviousFinding your agent template ID](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/finding-your-agent-template-id)
[NextVariable naming](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/variable-naming)
Last updated 2 months ago
---
# chat_finished | GigaML
To subscribe to this event, talk to the GigaML team to enable this for you.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads/call_finished-1#webhook-payload-for-chat_finished)
Webhook payload for `chat_finished`
Here are the fields in the webhook payload:
Field
Type
Description
event
string
The name of the event ("chat\_finished")
external\_conversation\_id
string
Unique identifier for the chat from your Contact Center
conversation\_id
string
Unique identifier for the chat
created\_at
integer
Chat start time in epoch milliseconds
finished\_at
integer
Chat end time in epoch milliseconds
duration\_seconds
integer
Chat duration in seconds
chat\_medium
string
Medium of the chat (e.g. `websocket`)
agent\_template\_id
string
Identifier of the parent agent that handled the chat
agent\_id
string
Identifier of the agent that handled the chat
agent\_version
number
Semantic version of the agent configuration that ran the chat
experiment\_id
string
Experiment / A/B test identifier, if the chat was part of an experiment
error\_details
string
Error description (only when status == "FAILED")
api\_metrics
array
List of API/tool latency metrics collected during the chat
repeat\_session
boolean
True if there was another chat in the recent look-back window
messages
array
Complete transcript of the conversation
intent
string
Main topic of the conversation
session\_analysis
object
AI-generated analysis of the conversation containing summary, sentiment assessment, reasoning, tags, and custom fields
session\_analysis.summary
string
A concise 1-2 sentence summary of the conversation
session\_analysis.sentiment
string
Overall sentiment categorization (one of: `very_happy`, `happy`, `neutral`, `unhappy`)
session\_analysis.sentiment\_reasoning
array of strings
Detailed reasoning for the sentiment assessment
session\_analysis.resolution\_status
string
Chat resolution status (one of: `resolved`, `abandoned`, `transferred`, `not_applicable`)
session\_analysis.resolution\_reasoning
array of strings
Detailed reasoning for the resolution status assessment
session\_analysis.tags
array of strings
Topic tags identified in the conversation
session\_analysis.custom\_fields
array of objects
Customizable fields with various data types for additional conversation metadata
Here is a sample payload as well:
Copy
{
"event": "chat_finished",
"chat_data": {
"external_conversation_id": "6a30d98c-38f8-442e-b9a0-6fdb99da4f84",
"conversation_id": "a82742c9-5aca-49a5-b817-bc85220c017d",
"created_at": 1628611074000,
"finished_at": 1628611374000,
"duration_seconds": 300,
"chat_medium": "websocket",
"agent_template_id": "agent_96320bce-f535-472d-9040-1dafa91b1d21"
"agent_id": "agent_template_96320bce-f535-472d-9040-1dafa914gi35",
"agent_version": 1.0,
"experiment_id": "string",
"error_details": "string",
"api_metrics": [],
"repeat_session": false,
"messages": [\
{\
"role": "assistant",\
"content": "Hello! How can I help you today?",\
"timestamp": 1628611090000,\
"tool_call_id": "dskj852k1-38f8-442e",\
"tool_calls": [\
{\
"id": "845ujdd98c-38f8-442e-b9a0ffd9-6fdb99da4f84",\
"type": "function",\
"function": {\
"name": "authenticate_user",\
"description": "",\
"arguments": "{}"\
}\
}\
],\
"variable_store": "string"\
}\
],
"intent": "Unable to login",
"session_analysis": {
"summary": "The user was unable to login.",
"sentiment": "happy",
"sentiment_reasoning": ["Reason for conversation: The user had some issues logging in."],
"resolution_status": "resolved",
"resolution_reasoning": ["The chat was resolved during the conversation"],
"tags": ["authentication_issue"],
"custom_fields": [\
{\
"name": "is_login_issue",\
"field_type": "",\
"number_val": 0,\
"boolean_val": true,\
"string_val": "",\
"object_val": {}\
}\
]
}
}
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads/call_finished-1#authentication)
Authentication
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads/call_finished-1#custom-authentication-headers)
Custom Authentication Headers
You can configure custom authentication headers when setting up your webhook endpoint with our team
> X-API-Key: your\_configured\_api\_key Authorization: Bearer your\_configured\_token
These headers will be included in every webhook request sent to your endpoint, allowing you to authenticate requests according to your security requirements.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads/call_finished-1#securing-your-webhook-endpoint)
Securing Your Webhook Endpoint
For maximum security, we recommend:
1. Use HTTPS for your webhook endpoint
2. Maintain an allow list of GigaML IP addresses (available upon request)
Contact our support team to configure your webhook authentication settings.
[Previouscall\_finished](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads/call_finished)
[NextEvents](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/events)
Last updated 2 months ago
---
# External Telephony | GigaML
GigaML supports Elastic SIP trunking for telephony integration. This guide provides step-by-step instructions for connecting your SIP provider to our telephony server using Twilio as an example.
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/external-telephony#setup-instructions)
Setup Instructions
---------------------------------------------------------------------------------------------------------------------------
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/external-telephony#step-1-create-an-elastic-sip-trunk)
Step 1: Create an Elastic SIP Trunk
1. Log into your Twilio console
2. Navigate to **Elastic SIP Trunking** in the left sidebar
3. Click **Create new SIP Trunk**
4. Configure your trunk settings:
* Enable **SIP REFER** if you plan to use call transfers within the GigaML platform
* Complete the trunk creation process
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/external-telephony#step-2-configure-outbound-termination)
Step 2: Configure Outbound Termination
1. In your SIP trunk configuration, navigate to **Termination** (left sidebar)
2. Set up a **Termination SIP URI**
3. **Important**: Record this URI - you'll need to provide it to your GigaML account manager
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/external-telephony#step-3-set-up-authentication)
Step 3: Set Up Authentication
GigaML currently requires username/password authentication (IP ACL is not supported).
1. Create a new **Credential List** in your Twilio console
2. Generate or set a username and password
3. **Important**: Save these credentials securely - they'll be used for SIP server authentication
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/external-telephony#step-4-configure-inbound-origination)
Step 4: Configure Inbound Origination
1. Navigate to the **Origination** tab in your SIP trunk settings
2. Add GigaML's SIP URI as a new origination endpoint:
Copy
sip:1isdwx931hs.sip.livekit.cloud
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/external-telephony#step-5-attach-phone-numbers)
Step 5: Attach Phone Numbers
1. Purchase or assign existing phone numbers to your configured SIP trunk
2. Ensure all numbers you want to integrate are properly attached to the trunk
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/external-telephony#step-6-complete-setup-with-gigaml)
Step 6: Complete Setup with GigaML
Contact your GigaML account manager with the following information:
* **Phone numbers**: Complete list of mobile numbers to add to your organization
* **Termination URI**: Your termination SIP URI (required for outbound calling)
* **Authentication credentials**: Username and password from Step 3 (required for outbound)
* **Agent routing**: Specify which GigaML agent each phone number should route to
Expect setup completion within 1-2 business days after providing all required information.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/external-telephony#support)
Support
For technical assistance or questions about SIP integration, please contact your assigned GigaML account manager or reach out to our support team.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/external-telephony#additional-notes)
Additional Notes
* This integration supports both inbound and outbound calling
* All authentication must use username/password - IP ACL authentication is not currently supported
[PreviousEvents](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/events)
Last updated 4 months ago
---
# call_finished | GigaML
To subscribe to this event, talk to the GigaML team to enable this for you.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads/call_finished#webhook-payload-for-call_finished)
Webhook payload for `call_finished`
Here are the fields in the webhook payload:
Field
Type
Description
event
string
The name of the event ("call\_finished")
external\_conversation\_id
string
Unique identifier for the chat from your Contact Center
call\_id
string
Unique identifier for the call
created\_at
integer
Call start time in epoch milliseconds
finished\_at
integer
Call end time in epoch milliseconds
from\_number
string
Calling phone number
to\_number
string
Called phone number
duration\_seconds
integer
Call duration in seconds
call\_medium
string
Medium of the call (one of: `phone`, `websocket`)
is\_outbound
boolean
True if the call was dialled out by the agent
status
string
Final status of the call (one of: `USER_ENDED`, `AGENT_ENDED`, `TRANSFERRED`, `VOICEMAIL`, `FAILED`, `UNREACHABLE`)
agent\_id
string
Identifier of the agent that handled the call
agent\_version
number
Semantic version of the agent configuration that ran the call
experiment\_id
string
Experiment / A/B test identifier, if the call was part of an experiment
transfer\_to
string
Number the call was transferred to (if applicable)
reason
string
Reason for ending/transferring the call (one of the configured transfer reasons or a descriptive string)
error\_details
string
Error description (only when status == "FAILED")
api\_metrics
array
List of API/tool latency metrics collected during the call
repeat\_session
boolean
True if this caller had another call in the recent look-back window
messages
array
Complete transcript of the conversation
session\_analysis
object
AI-generated analysis of the conversation containing summary, sentiment assessment, reasoning, tags, and custom fields
session\_analysis.summary
string
A concise 1-2 sentence summary of the conversation
session\_analysis.sentiment
string
Overall sentiment categorization (one of: `very_happy`, `happy`, `neutral`, `unhappy`)
session\_analysis.sentiment\_reasoning
array of strings
Detailed reasoning for the sentiment assessment
session\_analysis.resolution\_status
string
Call resolution status (one of: `resolved`, `abandoned`, `not_applicable`, `transferred`)
session\_analysis.resolution\_reasoning
array of strings
Detailed reasoning for the resolution status assessment
session\_analysis.tags
array of strings
Topic tags identified in the conversation
session\_analysis.custom\_fields
array of objects
Customizable fields with various data types for additional conversation metadata
Here is a sample payload as well:
Copy
{
"event": "call_finished",
"call_data": {
"external_conversation_id": "6a30d98c-38f8-442e-b9a0-6fdb99da4f84",
"call_id": "a82742c9-5aca-49a5-b817-bc85220c017d",
"created_at": 1628611074000,
"finished_at": 1628611374000,
"from_number": "+12345678901",
"to_number": "+13456789012",
"duration_seconds": 300,
"recording_url": "https://call-recording.region.cloud.com/call-_+19163580455_F8eQp8HK8yTa-recording.mp4",
"call_medium": "phone",
"is_outbound": false,
"status": "TRANSFERRED",
"agent_id": "agent_ffde7836b-0edb-f899-ab9c-90812fjh478fd",
"agent_version": 1.0,
"experiment_id": "",
"transfer_to": "+18005949308",
"reason": "repeated_agent_request",
"error_details": "",
"api_metrics": [],
"repeat_session": false,
"messages": [\
{\
"role": "user",\
"content": "Hi! How can i help you today?",\
"timestamp": 1628611090000,\
"tool_call_id": "",\
"tool_calls": [\
{\
"id": "1284fkjft995adkgnvd",\
"type": "function",\
"function": {\
"name": "get_customers",\
"description": "Tool to get customers",\
"arguments": ""\
}\
}\
],\
"variable_store": ""\
}\
],
"session_analysis": {
"summary": "The call was transferred",
"sentiment": "neutral",
"sentiment_reasoning": ["The customer was transferred with minimal conversation"],
"resolution_status": "resolved",
"resolution_reasoning": ["The call was transferred"],
"tags": ["repeat_agent_request", "short_conversation"],
"custom_fields": [\
{\
"name": "string",\
"field_type": "string",\
"number_val": 0,\
"boolean_val": true,\
"string_val": "string",\
"object_val": {}\
}\
]
}
}
}
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads/call_finished#authentication)
Authentication
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads/call_finished#custom-authentication-headers)
Custom Authentication Headers
You can configure custom authentication headers when setting up your webhook endpoint with our team
> X-API-Key: your\_configured\_api\_key Authorization: Bearer your\_configured\_token
These headers will be included in every webhook request sent to your endpoint, allowing you to authenticate requests according to your security requirements.
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads/call_finished#securing-your-webhook-endpoint)
Securing Your Webhook Endpoint
For maximum security, we recommend:
1. Use HTTPS for your webhook endpoint
2. Maintain an allow list of GigaML IP addresses (available upon request)
Contact our support team to configure your webhook authentication settings.
[PreviousWebhook events and payloads](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads)
[Nextchat\_finished](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/webhook-events-and-payloads/call_finished-1)
Last updated 2 months ago
---
# Single-page application implementation | GigaML
Copy
// In your main layout component or index file
useEffect(() => {
// Define the configuration
window.CHAT_WIDGET_CONFIG = {
agent_template_id: "YOUR_AGENT_TEMPLATE_ID",
company_name: "Your Company",
primary_color: "#000000",
primary_text_color: "#ffffff",
position: "bottom-right",
tagline: "Ready when you are.",
icon_url: "https://your-icon-url.com/icon.png",
secondary_color: "rgb(245 245 245)",
secondary_text_color: "#000000",
org_id: "YOUR_ORG_ID", // Optional
default_questions: [\
{\
label: "I'm having issues logging in", // On click will send this message sent in your chat widget\
type: "message",\
route: null\
},\
{\
label: "Email support",\
type: "url", // Opens a new tab based on the url route provided\
route: "https://your-website-url.com"\
},\
]
};
// Load the script
const script = document.createElement('script');
script.src = "https://widget.gigaml.com/inject-gigaml.js";
script.defer = true;
document.head.appendChild(script);
// Clean up on component unmount
return () => {
if (script.parentNode) {
document.head.removeChild(script);
}
};
}, []);
[PreviousHTML implementation](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/html-implementation)
[NextFinding your agent template ID](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/integrations/chat-widget/finding-your-agent-template-id)
Last updated 2 months ago
---
# Post Conversation Code | GigaML
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#how-it-works)
How it Works
----------------------------------------------------------------------------------------------------------------------------------
* Conversation ends
* The platform processes the conversation and generates analysis
* Custom post-conversation code runs with access to all conversation data
* Any output or side effects from your code are executed
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#available-variables)
Available Variables
------------------------------------------------------------------------------------------------------------------------------------------------
_When your post-conversation code executes, you'll have access to these following pre-populated variables:_
**resolution\_result Object** - analyzes how the conversation concluded and provides detailed reasoning for the assessment.[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#resolution_result-object-analyzes-how-the-conversation-concluded-and-provides-detailed-reasoning-for)
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#object-properties)
Object Properties
Property
Type
Description
`resolution_reasoning`
`list[str]`
Contains detailed steps outlining the reasoning process for assessing the resolution status
`resolution_status`
`str`
Final status of the conversation
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#resolution-status-values)
Resolution Status Values
Status
Description
`"resolved"`
The customer's issue or request was successfully handled
`"unresolved"`
The customer's issue or request remains unresolved
`"not_applicable"`
This status is used when the conversation type does not require a resolution assessment
`"transferred"`
The conversation was forwarded to another department or agent for further handling
**analysis Object - performs sentiment analysis and generates a summary of the conversation.**[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#analysis-object-performs-sentiment-analysis-and-generates-a-summary-of-the-conversation)
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#object-properties-1)
Object Properties
Property
Type
Description
`sentiment_reasoning`
`list[str]`
Detailing the steps in the reasoning process for assessing sentiment
`summary`
`str`
A concise 1-2 sentence summary of the conversation capturing key points and outcomes
`sentiment`
`str`
Indicating the overall user sentiment
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#sentiment-values)
Sentiment Values
Sentiment
Description
`"positive"`
The user expressed satisfaction or positive emotions
`"negative"`
The user expressed frustration or dissatisfaction
`"neutral"`
The user maintained a neutral tone
`"mixed"`
The user expressed both positive and negative sentiments
**tags Object - contains a list of categorizations that help organize and analyze conversations for reporting and routing purposes.**[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#tags-object-contains-a-list-of-categorizations-that-help-organize-and-analyze-conversations-for-repo)
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#object-structure)
Object Structure
Property
Type
Description
`name`
`str`
The name or label of the tag used to classify the conversation
`description`
`str | None`
An optional field providing additional context or explanation for the tag
**custom\_fields Object - extracts and stores custom field values from conversations based on your organization's specific data collection needs.**[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#custom_fields-object-extracts-and-stores-custom-field-values-from-conversations-based-on-your-organi)
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#object-structure-1)
Object Structure
Property
Type
Description
`string_val`
`str | None`
Contains string values for text or selector type custom fields
`number_val`
`float | None`
Holds numeric values for number type custom fields
`boolean_val`
`bool | None`
Indicates a boolean (True/False) value for boolean type custom fields
**call\_data Object - contains comprehensive information about the call session, including metadata, messages, performance metrics, and analysis results.**[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#call_data-object-contains-comprehensive-information-about-the-call-session-including-metadata-messag)
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#main-object-properties)
Main Object Properties
Property
Type
Descriptioz
`call_id`
`str`
Unique identifier for the call
`created_at`
`int`
Unix timestamp when the call was created
`from_number`
`str`
Phone number that initiated the call
`to_number`
`str`
Phone number that received the call
`call_medium`
`str`
Medium through which the conversation occurred
`status`
`str`
Final status of the call
`agent_id`
`str`
Unique identifier for the AI agent
`agent_version`
`float`
Version of the agent used
`messages`
`list[object]`
Array of message objects in the conversation
`experiment_id`
`str | None`
ID for experimental features (if applicable)
`is_outbound`
`bool | None`
Whether the call was outbound
`external_conversation_id`
`str | None`
Third-party integration ID (if applicable)
`duration_seconds`
`int`
Total duration of the call in seconds
`finished_at`
`int`
Unix timestamp when the call ended
`transfer_to`
`str | None`
Phone number or destination for transfers
`api_metrics`
`list[object]`
Performance metrics for API/tool calls
`session_analysis`
`object`
Analysis results for the session
`repeat_session`
`bool`
Whether this is a repeat session
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#call-medium-values)
Call Medium Values
Medium
Description
`"chat"`
Text-based chat conversation
`"call"`
Voice phone call
`"email"`
Email conversation
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#call-status-values)
Call Status Values
Status
Description
`"started"`
Call has begun
`"user_ended"`
User terminated the call
`"agent_ended"`
Agent terminated the call
`"failed"`
Call failed to complete
`"transferred"`
Call was transferred to another destination
`"unreachable"`
Outbound call could not reach the destination
`"voicemail"`
Outbound call reached voicemail
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#messages-array-structure)
messages Array Structure
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#messages-object-properties)
Messages Object Properties
Property
Type
Description
`role`
`str`
Role of the message sender (user/assistant)
`content`
`str | list[object] | None`
Message content (text or mixed media)
`tool_call_id`
`str | None`
Tool call ID if the message is a tool call response
`tool_calls`
`list[object] | None`
Tool calls if the message contains tool invocations
`timestamp`
`int | None`
Message timestamp in epoch milliseconds
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#content-types-for-mixed-content)
Content Types (for mixed content)
Content Type
Properties
Description
`TextInput`
`type`: `"text"`
`text`: `str`
Plain text content
`ImageInput`
`type`: `"image_url"`
`image_url`: `object`
Image content with URL
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#api_metrics-array-structure)
api\_metrics Array Structure
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#api-metrics-object-properties)
API Metrics Object Properties
Property
Type
Description
`tool_name`
`str`
The name of the tool that was called
`duration_ms`
`float`
The duration of the tool call in milliseconds
`args`
`str`
Stringified arguments for hashing/debugging
`output`
`str`
Stringified output/hash to link back to message content
`success`
`bool`
Whether the tool call was successful
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#session_analysis-object-structure)
session\_analysis Object Structure
Property
Type
Description
summary
`str`
Concise summary of the conversation
sentiment
`str`
Overall user sentiment
sentiment\_reasoning
`list[str]`
Detailed reasoning for sentiment assessment
custom\_fields
`list[object]`
Custom field values extracted from conversation
tags
`list[str]`
Tags categorizing the conversation
**event List - provides a complete chronological log of all events that occurred during a conversation session.**[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#event-list-provides-a-complete-chronological-log-of-all-events-that-occurred-during-a-conversation-s)
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#event-type-values)
Event Type Values
Event Type
Description
`assistant_message`
Messages generated by the AI agent
`user_message`
Messages sent by the user
`tool_call`
API call/tool invocation by the agent
`session_started`
Marks the beginning of the session
`session_ended`
Marks the end of the session
`error_occurred`
Denotes any errors during the session
`transfer`
Events related to transferring conversations
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#shared-event-object-properties)
Shared Event Object Properties
Property
Type
Description
`event_id`
`str`
Unique identifier for the event
`session_id`
`str`
Links the event to its session
`external_conversation_id`
`str | None`
Third-party integration ID (if applicable)
`timestamp`
`int`
Unix time of the event occurrence
`event_order`
`int`
Sequence of the event in session
`event_type`
`str`
The type of event
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#additional-properties-by-event-type)
Additional Properties by Event Type
Event Type
Additional Properties
Type
Description
Assistant Message Events
`message`
`object`
Message sent by the assistant
User Message Events
`message`
`object`
Message sent by the user
Tool Call Events
`message`
`object`
Details of the tool/API call made
Tool Response Events
`message`
`object`
Details of the tool/API response
Error Events
`text`
`str`
Description of the error that occurred
Transfer Events
`reason`
`str`
Motivation for transfer
Transfer Events
`transfer_from`
`str | None`
Source of the transfer (agent/department)
Transfer Events
`transfer_to`
`str | None`
Destination of the transfer (agent/department)
Transfer Events
`dtmf_digits`
`str | None`
DTMF digits entered during transfer (phone calls)
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/post-conversation-code#example)
Example
------------------------------------------------------------------------------------------------------------------------
Copy
# External API configuration
API_KEY = 'your_api_key_here'
API_ENDPOINT = 'https://your-api.com/endpoint'
# Log conversation outcomes
print(f"Resolution: {resolution_result['resolution_status']}")
print(f"Sentiment: {analysis['sentiment']}")
# Process tags
applied_tags = [tag['name'] for tag in tags]
print(f"Tags applied: {applied_tags}")
# Create ticket for unresolved conversations
if resolution_result['resolution_status'] == "unresolved":
ticket_data = {
"title": "Follow-up Required",
"description": analysis['summary'],
"priority": "high" if analysis['sentiment'] == "negative" else "medium",
"tags": applied_tags
}
headers = {"Content-Type": "application/json"}
async with httpx.AsyncClient() as client:
response = await client.post(
API_ENDPOINT,
auth=(API_KEY, ""),
headers=headers,
data=json.dumps(ticket_data)
)
response_data = response.json()
print(f"Ticket created: {response_data}")
[PreviousInitialization code](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/initialization-code)
[NextCode blocks](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/voice-agents/advanced/code-blocks)
Last updated 5 months ago
---
# Post Conversation Code | GigaML
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#how-it-works)
How it Works
---------------------------------------------------------------------------------------------------------------------------------
* Conversation ends
* The platform processes the conversation and generates analysis
* Custom post-conversation code runs with access to all conversation data
* Any output or side effects from your code are executed
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#available-variables)
Available Variables
-----------------------------------------------------------------------------------------------------------------------------------------------
_When your post-conversation code executes, you'll have access to these following pre-populated variables:_
**resolution\_result Object** - analyzes how the conversation concluded and provides detailed reasoning for the assessment.[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#resolution_result-object-analyzes-how-the-conversation-concluded-and-provides-detailed-reasoning-for)
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#object-properties)
Object Properties
Property
Type
Description
`resolution_reasoning`
`list[str]`
Contains detailed steps outlining the reasoning process for assessing the resolution status
`resolution_status`
`str`
Final status of the conversation
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#resolution-status-values)
Resolution Status Values
Status
Description
`"resolved"`
The customer's issue or request was successfully handled
`"unresolved"`
The customer's issue or request remains unresolved
`"not_applicable"`
This status is used when the conversation type does not require a resolution assessment
`"transferred"`
The conversation was forwarded to another department or agent for further handling
**analysis Object - performs sentiment analysis and generates a summary of the conversation.**[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#analysis-object-performs-sentiment-analysis-and-generates-a-summary-of-the-conversation)
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#object-properties-1)
Object Properties
Property
Type
Description
`sentiment_reasoning`
`list[str]`
Detailing the steps in the reasoning process for assessing sentiment
`summary`
`str`
A concise 1-2 sentence summary of the conversation capturing key points and outcomes
`sentiment`
`str`
Indicating the overall user sentiment
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#sentiment-values)
Sentiment Values
Sentiment
Description
`"positive"`
The user expressed satisfaction or positive emotions
`"negative"`
The user expressed frustration or dissatisfaction
`"neutral"`
The user maintained a neutral tone
`"mixed"`
The user expressed both positive and negative sentiments
**tags Object - contains a list of categorizations that help organize and analyze conversations for reporting and routing purposes.**[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#tags-object-contains-a-list-of-categorizations-that-help-organize-and-analyze-conversations-for-repo)
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#object-structure)
Object Structure
Property
Type
Description
`name`
`str`
The name or label of the tag used to classify the conversation
`description`
`str | None`
An optional field providing additional context or explanation for the tag
**custom\_fields Object - extracts and stores custom field values from conversations based on your organization's specific data collection needs.**[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#custom_fields-object-extracts-and-stores-custom-field-values-from-conversations-based-on-your-organi)
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#object-structure-1)
Object Structure
Property
Type
Description
`string_val`
`str | None`
Contains string values for text or selector type custom fields
`number_val`
`float | None`
Holds numeric values for number type custom fields
`boolean_val`
`bool | None`
Indicates a boolean (True/False) value for boolean type custom fields
**call\_data Object - contains comprehensive information about the call session, including metadata, messages, performance metrics, and analysis results.**[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#call_data-object-contains-comprehensive-information-about-the-call-session-including-metadata-messag)
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#main-object-properties)
Main Object Properties
Property
Type
Descriptioz
`call_id`
`str`
Unique identifier for the call
`created_at`
`int`
Unix timestamp when the call was created
`from_number`
`str`
Phone number that initiated the call
`to_number`
`str`
Phone number that received the call
`call_medium`
`str`
Medium through which the conversation occurred
`status`
`str`
Final status of the call
`agent_id`
`str`
Unique identifier for the AI agent
`agent_version`
`float`
Version of the agent used
`messages`
`list[object]`
Array of message objects in the conversation
`experiment_id`
`str | None`
ID for experimental features (if applicable)
`is_outbound`
`bool | None`
Whether the call was outbound
`external_conversation_id`
`str | None`
Third-party integration ID (if applicable)
`duration_seconds`
`int`
Total duration of the call in seconds
`finished_at`
`int`
Unix timestamp when the call ended
`transfer_to`
`str | None`
Phone number or destination for transfers
`api_metrics`
`list[object]`
Performance metrics for API/tool calls
`session_analysis`
`object`
Analysis results for the session
`repeat_session`
`bool`
Whether this is a repeat session
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#call-medium-values)
Call Medium Values
Medium
Description
`"chat"`
Text-based chat conversation
`"call"`
Voice phone call
`"email"`
Email conversation
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#call-status-values)
Call Status Values
Status
Description
`"started"`
Call has begun
`"user_ended"`
User terminated the call
`"agent_ended"`
Agent terminated the call
`"failed"`
Call failed to complete
`"transferred"`
Call was transferred to another destination
`"unreachable"`
Outbound call could not reach the destination
`"voicemail"`
Outbound call reached voicemail
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#messages-array-structure)
messages Array Structure
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#messages-object-properties)
Messages Object Properties
Property
Type
Description
`role`
`str`
Role of the message sender (user/assistant)
`content`
`str | list[object] | None`
Message content (text or mixed media)
`tool_call_id`
`str | None`
Tool call ID if the message is a tool call response
`tool_calls`
`list[object] | None`
Tool calls if the message contains tool invocations
`timestamp`
`int | None`
Message timestamp in epoch milliseconds
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#content-types-for-mixed-content)
Content Types (for mixed content)
Content Type
Properties
Description
`TextInput`
`type`: `"text"`
`text`: `str`
Plain text content
`ImageInput`
`type`: `"image_url"`
`image_url`: `object`
Image content with URL
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#api_metrics-array-structure)
api\_metrics Array Structure
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#api-metrics-object-properties)
API Metrics Object Properties
Property
Type
Description
`tool_name`
`str`
The name of the tool that was called
`duration_ms`
`float`
The duration of the tool call in milliseconds
`args`
`str`
Stringified arguments for hashing/debugging
`output`
`str`
Stringified output/hash to link back to message content
`success`
`bool`
Whether the tool call was successful
####
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#session_analysis-object-structure)
session\_analysis Object Structure
Property
Type
Description
summary
`str`
Concise summary of the conversation
sentiment
`str`
Overall user sentiment
sentiment\_reasoning
`list[str]`
Detailed reasoning for sentiment assessment
custom\_fields
`list[object]`
Custom field values extracted from conversation
tags
`list[str]`
Tags categorizing the conversation
**event List - provides a complete chronological log of all events that occurred during a conversation session.**[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#event-list-provides-a-complete-chronological-log-of-all-events-that-occurred-during-a-conversation-s)
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#event-type-values)
Event Type Values
Event Type
Description
`assistant_message`
Messages generated by the AI agent
`user_message`
Messages sent by the user
`tool_call`
API call/tool invocation by the agent
`session_started`
Marks the beginning of the session
`session_ended`
Marks the end of the session
`error_occurred`
Denotes any errors during the session
`transfer`
Events related to transferring conversations
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#shared-event-object-properties)
Shared Event Object Properties
Property
Type
Description
`event_id`
`str`
Unique identifier for the event
`session_id`
`str`
Links the event to its session
`external_conversation_id`
`str | None`
Third-party integration ID (if applicable)
`timestamp`
`int`
Unix time of the event occurrence
`event_order`
`int`
Sequence of the event in session
`event_type`
`str`
The type of event
###
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#additional-properties-by-event-type)
Additional Properties by Event Type
Event Type
Additional Properties
Type
Description
Assistant Message Events
`message`
`object`
Message sent by the assistant
User Message Events
`message`
`object`
Message sent by the user
Tool Call Events
`message`
`object`
Details of the tool/API call made
Tool Response Events
`message`
`object`
Details of the tool/API response
Error Events
`text`
`str`
Description of the error that occurred
Transfer Events
`reason`
`str`
Motivation for transfer
Transfer Events
`transfer_from`
`str | None`
Source of the transfer (agent/department)
Transfer Events
`transfer_to`
`str | None`
Destination of the transfer (agent/department)
Transfer Events
`dtmf_digits`
`str | None`
DTMF digits entered during transfer (phone calls)
[](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/post-conversation-code#example)
Example
-----------------------------------------------------------------------------------------------------------------------
Copy
# External API configuration
API_KEY = 'your_api_key_here'
API_ENDPOINT = 'https://your-api.com/endpoint'
# Log conversation outcomes
print(f"Resolution: {resolution_result['resolution_status']}")
print(f"Sentiment: {analysis['sentiment']}")
# Process tags
applied_tags = [tag['name'] for tag in tags]
print(f"Tags applied: {applied_tags}")
# Create ticket for unresolved conversations
if resolution_result['resolution_status'] == "unresolved":
ticket_data = {
"title": "Follow-up Required",
"description": analysis['summary'],
"priority": "positive" if analysis['sentiment'] == "negative" else "neutral",
"tags": applied_tags
}
headers = {"Content-Type": "application/json"}
async with httpx.AsyncClient() as client:
response = await client.post(
API_ENDPOINT,
auth=(API_KEY, ""),
headers=headers,
data=json.dumps(ticket_data)
)
response_data = response.json()
print(f"Ticket created: {response_data}")
[PreviousInitialization code](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/initialization-code)
[NextCode blocks](https://docs.gigaml.com/4K0ngGwBJ6wtOdANZAix/build/chat-agents/advanced/code-blocks)
Last updated 4 months ago
---
# Email Protection | Cloudflare
Please enable cookies.
Email Protection
================
You are unable to access this email address docs.gigaml.com
-----------------------------------------------------------
The website from which you got to this page is protected by Cloudflare. Email addresses on that page have been hidden in order to keep them from being accessed by malicious bots. **You must enable Javascript in your browser in order to decode the e-mail address**.
If you have a website and are interested in protecting it in a similar way, you can [sign up for Cloudflare](https://www.cloudflare.com/sign-up?utm_source=email_protection)
.
* [How does Cloudflare protect email addresses on website from spammers?](https://developers.cloudflare.com/waf/tools/scrape-shield/email-address-obfuscation/)
* [Can I sign up for Cloudflare?](https://developers.cloudflare.com/fundamentals/setup/account/create-account/)
Cloudflare Ray ID: **99a736067a83063b** • Your IP: Click to reveal 54.237.218.47 • Performance & security by [Cloudflare](https://www.cloudflare.com/5xx-error-landing)
---