> ## 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 > Connect agents to phone numbers for inbound and outbound calls ## Overview Before you connect agents to phone numbers, an Organization Admin must configure a phone provider (**Twilio** or **SIP Trunking**) in **Organization Settings** → **Voice**. See [Set up Phone Integrations for Agents](/administration/set-up-phone-integrations-for-agents). After a provider is in place, Agent Phone Integration lets callers reach an agent by phone and lets automations place outbound calls. Use this order in your app: 1. **Build a voice agent** (the agent must exist before a number can be routed to it). 2. **Configure a phone number in your app** — add a phone service under **App Details**, provision or import the number, and assign the agent. 3. Optionally add **Initiate Call** automations for outbound calls (same process for Twilio and SIP). This page covers building the agent, configuring the app phone number, testing, outbound calls, and caller authentication. *** ## Prerequisites * A phone provider (**Twilio** or **SIP Trunking**) configured in **Organization Settings** → **Voice** by an Organization Admin — see [Set up Phone Integrations for Agents](/administration/set-up-phone-integrations-for-agents) * An agent in your app, or a plan to create one under [Build a voice agent](#build-a-voice-agent) before you assign a phone number * Optional: an existing number to import (Twilio number, or a number on your SIP trunk) instead of platform provisioning The app hosting your phone-enabled agent must not have its **Status** field set to **Required**. Inbound calls automatically create records, and this creation fails when a required Status value is enforced. Remove the Required constraint from the Status field before enabling phone services on the app. *** ## Build a voice agent Create and train the agent before you assign a phone number. For general agent creation (instructions, tools, permissions), see [Building Agents](./agents-experience). 1. In your app, click **Intelligence** in the left navigation menu. 2. Create or select the agent that will handle phone calls. 3. Configure phone-specific behavior: * **Training Instructions**: State that this is a phone agent, and keep guidance concise for spoken conversation * **First Message**: Custom greeting if you are not using auto-generation on the phone service * **End Call Training**: Instructions for how the agent should end conversations 4. Click **Configure**, set [Voice Properties](#voice-properties) (idle messages, timeouts, model, background sound), and click **Save**. Prefer **GPT-4o Mini** for low-latency voice unless you need another available model. See [Best Practices](#best-practices) for phone agent training guidance. ### Voice Properties Voice Properties control how the agent behaves during phone calls. They appear in **Configure** for any agent used with a phone service. | 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** (recommended for low-latency voice) and **Grok 4 Fast Non-Reasoning**. | | **Background Sound** | Turn ambient call background sound on or off. Default is **On**. | Voice Properties only apply when the agent is used through a phone service. ### EndConversation tool Agents have access to an **endConversation** tool for phone interactions. Train the agent to use it when the caller's request is resolved so calls close cleanly. You configure tools while you [build the agent](/ai-agents/agents-experience). Train your agents on when and how to use the endConversation tool. ```text Example Training Instructions theme={null} You are a phone agent. Keep spoken responses short and clear. 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 *** ## Configure a phone number in your app After you have a voice agent and an Organization Admin has [configured a phone provider](/administration/set-up-phone-integrations-for-agents), add a phone service under **App Details** → **Phone Services**. Each service is a phone number tied to an agent, with language and caller access options. ### Provision a phone number 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 [Phone service fields](#phone-service-fields)). Platform provisioning through Twilio creates **US toll-free** numbers. Twilio configuration for the new number is handled automatically when your organization Twilio provider is connected. Use a number you already have (for example, in Twilio) or bring numbers via [SIP Trunking](/administration/set-up-phone-integrations-for-agents#add-a-phone-provider): 1. Start adding a phone service and choose to use an existing number. 2. Enter the number. 3. Complete the remaining service fields (see [Phone service fields](#phone-service-fields)). For Twilio, the number must be available and not in use by other Twilio applications. ### Phone service fields When you add or edit a phone service, set: * **Number Type**: New number (platform-provisioned) or existing number * **Area Code**: Geographic area code when provisioning a new number (where applicable) * **Phone Provider**: Your organization's configured provider (**Twilio** or **SIP Trunking**) * **Agent**: The agent that handles calls on this service (must already exist) * **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 on the phone service if shown. Options match [Voice Properties](#voice-properties) (**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. ### Configure caller access 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). * **Employee ID with OTP Authentication**: Any caller can reach the agent without a pre-registered phone number. The caller provides their employee ID, receives a one-time password by email, and speaks or types the OTP to authenticate. See [Employee ID with OTP Authentication](#employee-id-with-otp-authentication). 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. See [Profile](/administration/profile). ### Manage phone services From **App Details** → **Phone Services**: 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. Removing a service in Elementum does not release the number from your Twilio account. Release numbers in Twilio if needed. Organization Admins can also review numbers and mappings across apps in [Set up Phone Integrations for Agents](/administration/set-up-phone-integrations-for-agents#organization-voice-management). *** ## Test your phone integration 1. Dial your provisioned phone number. 2. Confirm the call connects and the agent responds. 3. Interact with the agent to verify it follows training instructions. 4. Review call logs in your app to confirm data is captured correctly. ### Troubleshooting * Verify the phone provider is active in [Set up Phone Integrations for Agents](/administration/set-up-phone-integrations-for-agents) * Check that the phone number is properly registered on the phone service * For Twilio, ensure your Twilio account has sufficient credits * Confirm the app's **Status** field is not set to **Required** — phone calls create records automatically, and a required Status field blocks that creation * Verify the agent is properly configured and active * Check that the LLM model is available * Review training instructions for phone-specific guidance * Reduce **Additional Supported Languages** if not needed * Review agent training to keep responses concise and tools fast * Check Twilio or SIP provider service status * For SIP, choose a nearer [ingress region](/administration/set-up-phone-integrations-for-agents#multi-region-sip-domains) * Some locales may require firewall configuration on your network or carrier side * Use [E.164](https://www.twilio.com/docs/glossary/what-e164) format for destination numbers (for example, `+15551234567`), especially for international calls * When reporting problems with international calls, include the locale and destination country * Confirm the phone service and agent are configured and the provider supports the destination region *** ## Outbound calls and workflows Use the **Initiate Call** automation action to place outbound calls from a configured agent and phone service. The same outbound setup applies whether you use Twilio or SIP Trunking. The action is fire-and-forget: the workflow continues without waiting for the call to finish. Use the **Agent Conversation Ended** trigger in a separate automation to act on outcomes, and prefer post-call automations for heavy processing so the live call stays low latency. Outbound calling to China is not supported by default. To place China outbound calls, use a China-compliant telephony provider connected through [SIP Trunking](/administration/set-up-phone-integrations-for-agents#add-a-phone-provider); that provider relationship is managed entirely by your organization. ### How it works 1. An automation reaches an **Initiate Call** action. 2. The system starts a phone call to the specified number asynchronously. 3. The configured agent handles the conversation while the workflow continues. 4. A separate automation with **Agent Conversation Ended** can process results. ### Configure the Initiate Call action **Required:** * **Action Name** — Identifies the action in the workflow * **AI Agent** — Agent that conducts the call (must be trained for phone) * **Phone Service** — Phone service/number used to place the call * **Phone Number to Call** — Recipient number in E.164 format when possible (record field, previous task output, or static value such as `+15551234567`) * **Default Language** — Primary language for the call **Optional:** * **Related Record** — Associates the call with a record for context and record keeping * **Additional Context** — Instructions for the agent (for example, ticket number or callback reason). Keep this focused; large context increases latency. Common automation triggers for outbound calls include record created or updated, scheduled events, approval completed, and time-based follow-ups. You cannot reference call outcomes in the same workflow as **Initiate Call**. Create a separate automation with **Agent Conversation Ended**. Example outcome 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) ``` ### Call data and transcripts When a phone call is received or initiated, a record is created in your app with: * Phone number (caller or recipient) * Call start time * Call duration * Call direction (inbound or outbound) * Agent assigned to the call Call recordings are not available. Open the call record and use **Chat/Conversation** to view the **Voice** conversation type, direction, and full transcript. ### Agent Conversation Ended Use the **Agent Conversation Ended** trigger to process outcomes for inbound and outbound calls. The trigger provides the transcript, duration and metadata, call direction, and resolution status. Common follow-ups include posting a summary on the related record, creating tasks, sending notifications, or building call metrics (volume by direction, resolution rates, and similar). For building automations, see [Automations](/workflows/automation-system#building-your-first-automation). ### Outbound training tips Train outbound agents to introduce themselves, state the purpose of the call, confirm they have the right person, then complete the objective. Pass only the context needed for that call, respect time zones and calling hours, and use **Agent Conversation Ended** for no-answers and follow-ups. ```text Example Outbound Agent Instructions theme={null} You are a phone agent making an outbound call. 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. ``` *** ## 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 When using multiple languages, test thoroughly, monitor call quality and response times, and prefer single-language mode when possible. *** ## Security and caller authentication Caller access settings restrict who can interact with your voice agent. Configure these on each phone service in **App Details**. See [Configure caller access](#configure-caller-access). ### 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**. See also [Profile](/administration/profile). Admins can guide users to this setting when enabling PIN-protected phone services. ### Employee ID with OTP Authentication **Employee ID with OTP Authentication** opens a voice agent to any employee calling from any phone, without a pre-registered phone number, using two-factor verification: the caller's employee ID plus a one-time password (OTP) delivered by email. An admin selects **Employee ID w/ OTP** as the caller authentication type on the phone service (see [Configure caller access](#configure-caller-access)). When a caller reaches the agent: 1. The caller provides their employee ID. 2. Elementum emails a one-time password to the address on that employee's profile. 3. The caller speaks or types the OTP to the agent to authenticate. Because callers authenticate by employee ID rather than a recognized phone number, employees can reach the agent from any phone while still passing secure verification. ### 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 on the call record; call recordings are not available (see [Call data and transcripts](#call-data-and-transcripts)) * Ensure your phone interactions comply with local regulations * Consider consent requirements for call data and transcripts * Review data processing agreements with Twilio or your SIP provider * For China outbound limitations, see [Outbound calls and workflows](#outbound-calls-and-workflows) *** ## Best Practices * **Say it is a phone agent**: State in training that the agent is speaking on a phone call * **Be Concise**: Keep instructions and spoken responses short; large context and long tool outputs hit limits faster on voice * **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 * **Phone-specific training**: Keep phone training separate from chat training when the agent is used in both channels * **Use endConversation**: Train agents to close calls with the endConversation tool when resolution is complete * **Prefer GPT-4o Mini** for voice unless you need another available model * **Fast tools only**: Use tools sparingly during the call and favor low-latency actions * **Post-call processing**: Avoid long-running work during the live call; use **Agent Conversation Ended** * **Single Language**: Prefer one language on the phone service unless multilingual support is essential * **Regular Review**: Check call logs and agent performance regularly * **Update Training**: Refine agent training based on call outcomes * **Two cost lines**: Telephony (Twilio or SIP) and model/LLM usage are separate * **Provider Management**: Monitor your Twilio or SIP provider usage and billing * **Backup Numbers**: Consider backup phone numbers for high-availability scenarios