> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementum.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Phone Integration
> Enable phone call functionality for your agents using Twilio integration
## Overview
Agent Phone Integration allows you to connect your conversational AI agents to phone numbers, enabling customers to call and interact with your agents directly. This feature uses Twilio as the phone service provider to handle incoming calls and route them to your configured agents.
To control how your agent behaves during calls—including idle messages, inactivity timeouts, and unrecognized caller responses—configure [Voice Properties](#voice-properties) in the agent's settings.
***
## Prerequisites
Before setting up phone integration for your agents, ensure you have:
Twilio integration configured in your organization settings with active credentials by an organization admin
At least one agent created and configured in your app with proper training instructions
A phone number provisioned in your Twilio account - you can also provision through the platform
***
## Setting Up Phone Integration
Navigate to your **Organization Settings** and ensure you have a Twilio phone provider configured:
1. Go to **Organization Settings** → **Integrations** → **Phone**
2. If no phone providers are configured, click **Phone Provider** to add Twilio credentials
3. Verify your Twilio integration shows as active
Your Twilio integration must show as "Active" before proceeding to the next step.
Add a phone service from your app:
1. Open your App in Elementum.
2. Click **App Details**.
3. In the **Phone Services** section, add a new service. Choose how the number is sourced:
Let Elementum provision a new number through your Twilio integration:
1. Start adding a phone service and select provisioning a new number.
2. Complete the service fields (see next step).
Platform provisioning handles Twilio configuration for the new number automatically.
Use a number you already have in Twilio:
1. Start adding a phone service and choose to use an existing number.
2. Enter the number from your Twilio account.
3. Complete the remaining service fields (see next step).
The number must be available and not in use by other Twilio applications.
When you add or edit a phone service, set:
* **Number Type**: New number (platform-provisioned) or existing Twilio number
* **Area Code**: Geographic area code when provisioning a new number
* **Phone Provider**: Your organization's configured Twilio provider
* **Agent**: The agent that handles calls on this service
* **Default Language**: Primary language for calls on this service
* **Additional Supported Languages**: Optional extra languages beyond the default. See [Supported Languages](#supported-languages). Enabling many languages may reduce performance.
Select the LLM for the voice agent. Current options include **GPT-4o Mini** and **Grok 4 Fast Non-Reasoning**. Models use platform-level configuration; custom credentials are not configured here.
When enabled, the platform generates an initial greeting the agent speaks when a call connects. You can also set a custom first message on the agent instead.
Click **Save** when finished.
Control who can interact with your voice agent by setting caller access on each phone service. Open **App Details**, click **Edit** next to the phone service you want to configure, and select a **Caller Access** option:
* **Open**: Any caller can reach the agent (default).
* **Known Callers Only**: Only callers whose phone number matches a number listed in your organization's user profiles can connect.
* **Known Caller with PIN Verification**: Callers must enter a PIN at the beginning of the call. Users set their PIN in **User Settings** → **Security** → **Phone Authentication PIN**. See [Phone Authentication PIN](#phone-authentication-pin).
Click **Save**.
For **Known Callers Only** and **Known Caller with PIN Verification**, make sure phone numbers are added to personal user profiles within User Settings.
In your app, click **Intelligence** in the left navigation menu. Select or create a voice agent, then configure how it behaves during phone conversations:
* **Training Instructions**: Specific guidance for phone interactions (e.g., "Keep responses concise for phone calls")
* **First Message**: Custom greeting message (if not using auto-generation)
* **Conversation Timeout**: Set timeout duration for inactive calls
* **End Call Training**: Instructions for how the agent should end conversations
* **Background Sound**: Turn ambient call background sound on or off. Enabled by default.
See [Best Practices](#best-practices) for phone agent training guidance.
***
## Configure App Phone Services Settings
Manage phone services in your app:
1. Open your App in Elementum.
2. Click **App Details**.
3. In the **Phone Services** section, manage or configure a service using the following fields:
* Number Type
* Area Code
* Phone Provider
* Agent
* Default Language
* Additional Supported Languages
From **Phone Services**, you can see provisioned numbers, which agent is assigned, service status, and call activity or logs.
Open the service you want to change, update the fields above (including voice model or first-message options if shown), then click **Save**.
Remove a service from the list when you no longer need it. Confirm if prompted.
**Note**: Removing a service in Elementum does not release the number from your Twilio account. Release numbers in Twilio if needed.
After these steps, open [**Automations**](/workflows/automation-system#building-your-first-automation) in your app's menu to add Phone Agent actions to your workflows.
***
## Voice Properties
Voice Properties control how the agent behaves during phone call interactions. These settings appear in the **Configure** page for any agent used with a phone integration.
| Setting | Description |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Idle Message** | Message the agent speaks when the caller has not responded within the idle message timeout period. |
| **Idle Message Timeout (seconds)** | How long the agent waits for a response before speaking the idle message. Default is 12 seconds. |
| **Inactivity Timeout Message** | Message the agent speaks before ending the call due to prolonged inactivity. |
| **Inactivity Timeout (seconds)** | How long the agent waits after the idle message before ending the call. Default is 60 seconds. |
| **Unrecognized Phone Number Message** | Message spoken when the caller's phone number cannot be matched to a user in the system. Used when caller access is restricted to known callers. |
| **LLM Model** | The AI model that powers the voice conversation. Available options include **GPT-4o Mini** and **Grok 4 Fast Non-Reasoning**. |
| **Background Sound** | Turn ambient call background sound on or off. Default is **On**. |
To configure Voice Properties:
1. In your app, click **Intelligence** in the left navigation menu.
2. Select the agent you want to configure.
3. Click **Configure**.
4. Scroll to the **Voice Properties** section.
5. Update the desired fields and click **Save**.
Voice Properties only apply when the agent is used through a phone service. For broader agent configuration (instructions, tools, permissions), see [Building Agents](./agents-experience).
***
## Agent Tools for Phone Calls
You configure agent tools—including tools used on phone calls—while you [build and configure the agent](/ai-agents/agents-experience). The **endConversation** tool below is specific to phone interactions.
### EndConversation Tool
Agents have access to a special **endConversation** tool specifically designed for phone interactions.
**Purpose:**
* Allows agents to proactively end phone calls when appropriate
* Provides clean closure for support interactions
* Prevents calls from remaining open unnecessarily
* Ensures proper conversation lifecycle management
**Critical Configuration**: Train your agents on when and how to use the endConversation tool for optimal user experience.
```text Example Training Instructions theme={null}
When you have fully resolved the caller's question or completed the requested task,
use the endConversation tool to end the call. Always provide a brief summary
of what was accomplished and any next steps before ending the conversation.
```
Use the endConversation tool when:
* Support issue has been fully resolved
* Caller's question has been completely answered
* Required information has been collected
* Follow-up actions have been clearly communicated
* Caller confirms satisfaction with the resolution
***
## Initiating Outbound Calls
Beyond receiving inbound calls, agents can proactively initiate outbound calls to customers as part of automated workflows. This enables your agents to make follow-up calls, appointment reminders, and other proactive outreach automatically.
### Overview
The **Initiate Call** automation action allows workflows to trigger outbound phone calls from your AI agents. It uses the same agent and phone service configuration as inbound calls.
The action is fire-and-forget: the workflow continues immediately without waiting for the call to complete. Use the **Agent Conversation Ended** trigger in a separate automation to act on call outcomes (see [Workflow Triggers](#workflow-triggers)).
### How It Works
1. **Workflow Trigger**: An automation workflow reaches an "Initiate Call" action
2. **Call Initiated**: The system asynchronously starts a phone call to the specified number
3. **Agent Conducts Call**: Your configured AI agent handles the conversation
4. **Workflow Continues**: The workflow proceeds to the next action without waiting
5. **Call Outcome Captured**: Use the Agent Conversation Ended trigger in another automation to process results
### Configuring the Initiate Call Action
When adding an "Initiate Call" action to your workflow, you'll configure:
**Action Name**
* Descriptive name for the call action to identify it in your workflow
**AI Agent**
* Select which agent will conduct the call
* The agent must be properly trained for phone interactions
* Agent will have access to any context you provide
**Phone Service**
* Choose which phone service/number will be used to place the call
* Must be a phone service you've already configured in your app
**Phone Number to Call**
* Specify the recipient's phone number
* Can use:
* **Record Field**: `{{customer.phone_number}}`
* **Previous Task Output**: `{{search_customer.phone}}`
* **Static Value**: `+1-555-123-4567`
**Default Language**
* Set the primary language for the call
* Agent will conduct conversation in this language
**Related Record**
* Associate the call with a specific record
* Provides context for the agent and enables better record keeping
* Agent can access related record data during the call
**Additional Context**
* Provide specific instructions or information for the agent
* Examples:
* "This is a follow-up call for support ticket #12345"
* "Customer requested callback about billing issue"
* "Appointment reminder for 2pm tomorrow"
* Helps the agent conduct a more informed conversation
### Example Workflows
```text High Priority Support Callback theme={null}
TRIGGER: Support Ticket Created
→ IF priority = "High"
→ Initiate Call
→ Agent: Support Agent
→ Phone Service: Main Support Line
→ Phone Number: {{ticket.customer_phone}}
→ Related Record: {{ticket.id}}
→ Context: "Follow up on high-priority ticket {{ticket.number}}"
→ Language: English
→ Continue with other workflow actions
```
```text Appointment Reminder theme={null}
TRIGGER: Scheduled Event (1 hour before appointment)
→ Initiate Call
→ Agent: Appointment Reminder Agent
→ Phone Service: Appointment Line
→ Phone Number: {{appointment.customer_phone}}
→ Related Record: {{appointment.id}}
→ Context: "Remind customer about {{appointment.type}} at {{appointment.time}}"
→ Language: English
```
```text Order Confirmation Callback theme={null}
TRIGGER: Order Status Changed to "Shipped"
→ IF customer.prefers_phone_updates = true
→ Initiate Call
→ Agent: Customer Service Agent
→ Phone Service: Customer Service Line
→ Phone Number: {{order.shipping_phone}}
→ Related Record: {{order.id}}
→ Context: "Order {{order.number}} has shipped with tracking {{order.tracking_number}}"
→ Language: {{customer.preferred_language}}
```
### Fire-and-Forget Execution
You cannot reference call outcomes in the same workflow. Create a separate automation with the **Agent Conversation Ended** trigger to act on call results.
**Example: processing call outcomes in a separate automation**
```text theme={null}
TRIGGER: Agent Conversation Ended
→ IF conversation.type = "Voice"
→ Post Comment (on related record)
→ Comment: "Call completed: {{conversation.summary}}"
→ IF conversation contains "needs follow-up"
→ Create Record (Follow-up Task)
```
### Best Practices for Outbound Calls
* **Agent Training**: Train agents specifically for outbound scenarios with appropriate opening statements and call objectives
* **Context Matters**: Always provide relevant context to help the agent conduct meaningful conversations
* **Timing Considerations**: Consider time zones and appropriate calling hours in your workflow logic
* **Fallback Handling**: Use Agent Conversation Ended to detect no-answers and create follow-up tasks
**Agent Training Tips for Outbound Calls:**
```text Example Outbound Agent Instructions theme={null}
You are making an outbound call to the customer. Start by:
1. Introducing yourself and the company
2. Stating the purpose of your call clearly
3. Confirming you're speaking with the right person
4. Proceeding with the conversation objective
Keep the call focused and respect the customer's time. If they're unavailable,
offer to call back at a better time or provide alternative contact methods.
Use the endConversation tool when you've completed the call objective or if
the customer requests to end the call.
```
### Monitoring Outbound Calls
Outbound calls create app records and transcripts like inbound calls. Use the **Chat/Conversation** interface on the call record to review transcripts and metadata. Use **Agent Conversation Ended** triggers to create follow-up tasks, send notifications, or generate analytics (see [Integration with Workflows](#integration-with-workflows)).
### Common Use Cases
Automatically call customers before scheduled appointments to confirm attendance and reduce no-shows.
Proactively reach out to customers after support tickets are resolved to ensure satisfaction.
Notify customers about important order status changes when immediate communication is critical.
Contact customers with overdue payments with friendly reminders and payment options.
Conduct automated satisfaction surveys or gather feedback through phone conversations.
Alert customers about urgent issues, security concerns, or time-sensitive matters.
***
## Supported Languages
Set **Default Language** on each phone service. Use **Additional Supported Languages** when you need more than one language on that service.
Enabling additional languages can reduce performance; enable only if your use case requires it.
### Available Languages
* Arabic
* Chinese (Mandarin) — Simplified and Traditional
* Chinese (Cantonese) — Traditional
* Dutch
* English
* French
* German
* Hindi
* Hungarian
* Indonesian
* Italian
* Japanese
* Korean
* Portuguese
* Russian
* Spanish
* Thai
* Turkish
* Vietnamese
### Performance Considerations
When using multiple languages: test thoroughly, monitor call quality and response times, and prefer single-language mode when possible for best performance.
***
## Testing Your Phone Integration
### Testing Call Flow
1. **Make a Test Call**: Dial your provisioned phone number
2. **Verify Connection**: Ensure the call connects and the agent responds
3. **Test Agent Responses**: Interact with the agent to verify it follows training instructions
4. **Check Call Logs**: Review call logs in your app to ensure data is captured correctly
### Troubleshooting Common Issues
**Common Solutions:**
* Verify Twilio integration is active
* Check that the phone number is properly registered
* Ensure your Twilio account has sufficient credits
**Common Solutions:**
* Verify the agent is properly configured and active
* Check that the LLM model is available
* Review training instructions for phone-specific guidance
**Common Solutions:**
* Reduce **Additional Supported Languages** if not needed
* Review agent training to ensure responses are concise
* Check Twilio service status
***
## Integration with Workflows
Automations can trigger outbound calls and process call outcomes. For outbound call setup, see [Initiating Outbound Calls](#initiating-outbound-calls).
### Call Data Capture
When a phone call is received or initiated, a record is automatically created in your app with call information:
* Phone number (caller or recipient)
* Call start time
* Call duration
* Call direction (inbound or outbound)
* Agent assigned to the call
No additional configuration is required.
### Workflow Triggers
Use the **Initiate Call** action in your automations to trigger outbound phone calls based on business events:
**Common Triggers:**
* Record Created (e.g., high-priority support ticket)
* Record Updated (e.g., order status changed)
* Scheduled Event (e.g., appointment reminders)
* Approval Completed (e.g., callback after approval)
* Time-Based (e.g., daily follow-up calls)
See the [Initiating Outbound Calls](#initiating-outbound-calls) section for complete configuration details.
Use the **Agent Conversation Ended** trigger in your automations to process phone call outcomes for both inbound and outbound calls:
**What You Get:**
* Complete call transcript
* Conversation duration and metadata
* Call direction (inbound/outbound)
* Agent responses and customer interactions
* Call outcome and resolution status
**Automation Examples:**
* Create support tickets based on call content
* Send follow-up emails with call summary
* Route urgent issues to appropriate teams
* Update CRM systems with conversation details
* Generate call reports for management
* Create follow-up tasks for unsuccessful outbound calls
* Track callback completion for outbound reminders
### Viewing Phone Conversations
Call recordings are not available. To review call content, open the record created for the call and use **Chat/Conversation** in the record details to view the **Voice** conversation type, direction (inbound/outbound), and full transcript.
### Call Analytics
Use **Agent Conversation Ended** triggers to build metrics such as call volume (by direction), response times, satisfaction scoring, resolution rates, and agent performance. Capture call data in the trigger, then use AI actions and calculations to produce reports; use the call direction field to segment inbound vs. outbound.
***
## Security and Compliance
### Caller Authentication
Caller access settings restrict who can interact with your voice agent. Configure these on each phone service in **App Details**. See [Setting Up Phone Integration](#setting-up-phone-integration) for setup steps.
### Run As Current User
When an agent is configured with **Run As Current User** permissions, the agent operates with the same data access and permissions as the caller. For this to work with voice agents, callers must have a phone number added to their personal user profile within User Settings so the platform can identify them.
If a caller's phone number is not listed in their user profile, the platform cannot match the caller to a user and the call will not authenticate.
### Phone Authentication PIN
Users who call an agent configured with **Known Caller with PIN Verification** must enter a PIN at the start of the call. To set up a PIN:
1. Go to **User Settings** → **Security**.
2. Set a **Phone Authentication PIN**.
Admins can guide users to this setting when enabling PIN-protected phone services.
### Data Protection and Compliance
* All phone conversations are processed according to your data retention policies
* Sensitive information handling follows your organization's security guidelines
* Call content is available as transcripts in the **Chat/Conversation** interface on the call record; call recordings are not accessible to customers
* Ensure your phone interactions comply with local regulations
* Consider consent requirements for call data and transcripts
* Review data processing agreements with Twilio
***
## Best Practices
* **Be Concise**: Phone conversations require shorter, clearer responses
* **Confirm Information**: Always repeat back important details
* **Use Verbal Cues**: Include phrases like "Let me help you with that" or "I understand"
* **Provide Clear Next Steps**: End calls with specific action items
* **Use endConversation**: Train agents to properly close calls using the endConversation tool when resolution is complete
* **Single Language**: Use single language mode for better performance unless multilingual support is essential
* **Specific Training**: Provide phone-specific training instructions separate from chat training
* **Regular Testing**: Periodically test your phone integration to ensure quality
* **Regular Review**: Check call logs and agent performance regularly
* **Update Training**: Refine agent training based on call outcomes
* **Twilio Management**: Monitor Twilio usage and costs
* **Backup Numbers**: Consider having backup phone numbers for high-availability scenarios
***
By following this guide, you can successfully integrate phone functionality with your agents, providing customers with another channel to access your AI-powered support and services.