Phone AI Integration

💡 Connecting Your Chatbot with Phone AI

What is the Phone AI Agent?

YourGPT's Phone AI Agent lets you answer phone calls using an AI-powered voice assistant. It can speak naturally, handle common queries, and even transfer the call to a human.

The agent is powered by a language model and connects through Twilio to receive and manage calls.

Step 1: Connect Your Twilio Account

To start receiving calls, connect your Twilio account.

Configure Twilio Settings

Go to the Settings tab in the Phone AI Agent section.

Fill in these details:

Account SID (from your Twilio dashboard)
Auth Token
Phone Number (including country code)
Phone SID

Click Enable once all fields are filled.

Note

Once connected, you'll see the phone number in green at the top of the Functions tab.

Need Help Finding These?

You can find these values in your Twilio Console under the Phone Numbers and Account Info sections.

Follow this guide to get Twilio Credentials

Step 2: Configure Your Voice Agent

Head over to the Configuration tab to set up how your agent behaves.

Welcome Message

This is the first thing the agent will say when answering a call.

Example:

Hi, this is YourGPT's virtual assistant. How can I help you today?

This is a crucial component that defines the tone, personality, and behavior of the Phone AI agent. It sets the foundation for how the AI agent will interact with callers. The base prompt should include:

The agent's role and purpose
Key information about your business or services
Guidelines for handling different types of inquiries
Instructions on when to transfer calls to a human operator

By creating a detailed and specific base prompt, you can ensure that your AI agent provides consistent, accurate, and helpful responses to callers.

Phone AI Agent

Personalize with variables

The welcome message and base prompt can include variables such as {{SESSION_DATA.first_name}} or {{CALL.from}}. They're filled in when the call starts. See Use variables in prompts and functions.

AI Model

Select from the available models.

Phone AI Agent

Advanced Settings

Speech Settings – Choose Speech Model, Voice, Speech Instructions.

TTS Model Settings

Transcription Settings – Choose Transcription Model and transcription Instructions.

Transcription Model Settings

Step 3: Add Call Functions

Go to the Functions tab to define what the voice agent can do.

Phone AI Agent

Use variables in prompts and functions

Variables let you pass call details, such as the session ID or the caller's phone number, to your prompts and your own APIs. Write them in double curly braces, like {{SESSION.session_uid}}.

Available variables

Variable	Value
`{{SESSION.session_uid}}`	Unique ID of the session for this call, e.g. `1731234567891234`
`{{CALL.from}}`	Number that placed the call. On inbound calls this is the caller; on outbound calls it's your agent's number.
`{{CALL.to}}`	Number that received the call. On inbound calls this is your agent's number; on outbound calls it's the person you called.
`{{CALL.call_id}}`	Call ID from the phone provider
`{{CALL.call_type}}`	`inbound` or `outbound`
`{{CONFIG.<key>}}`	One of your chatbot's config variables, e.g. `{{CONFIG.API_KEY}}`
`{{SESSION_DATA.<key>}}`	A value passed in `extra_data.session_data` when starting an outbound call

Where you can use them

Configuration tab: Welcome Message and Base Prompt
API functions: URL, Headers and Request Parameters
Other function settings: for example, the Transfer Number of a call transfer function

Example: send the session ID and caller's number to your API

In an API function, add these under Request Parameters:

{
  "session_id": "{{SESSION.session_uid}}",
  "caller_phone": "{{CALL.from}}"
}

When the AI calls the function, your API receives these values together with the parameters the AI filled in. GET requests send them as query parameters. POST, PUT, PATCH and DELETE requests send them in the JSON body.

Variables are filled in when the call starts

Values the AI fills in during the call are sent exactly as the AI produces them, without replacing variables. Put system values like the session ID or the caller's number in the URL, Headers or Request Parameters, not in a parameter the AI fills in.

If a Request Parameter has the same name as a parameter the AI fills in, your Request Parameter value is sent.

Good to know

The variable picker doesn't list CALL and SESSION_DATA variables yet. Type them in directly.
In test calls from the dashboard, CALL variables are empty because there's no phone call.
CONTACT and VISITOR variables are empty on phone calls.
A variable without a value becomes an empty string.

Programmatic Outbound Calling

Beyond receiving inbound calls, you can programmatically trigger outbound calls using YourGPT's API. This enables powerful use cases like:

Click-to-call buttons on your website
Automated appointment reminders
Lead qualification calls
Customer outreach campaigns
Proactive customer support

How It Works

Use the Make Outbound Call API to initiate AI-powered phone calls programmatically. Your configured Phone AI Agent will call the specified phone number and engage in a natural conversation based on your agent's configuration.

Quick Example

const response = await fetch("https://api.yourgpt.ai/chatbot/v1/makeOutboundCall", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "api-key": "your_api_key_here"
  },
  body: JSON.stringify({
    agent_id: "your_agent_id",
    call_to: "+1234567890",
    extra_data: {
      contact_data: {
        name: "John Doe",
        phone: "+1234567890"
      },
      session_data: {
        first_name: "John",
        order_id: "ORD-1042"
      }
    }
  })
});

Everything in extra_data.session_data is available to the agent as {{SESSION_DATA.<key>}}. For example, use {{SESSION_DATA.order_id}} in the welcome message or in a function's Request Parameters. See Use variables in prompts and functions.

Learn More

Click-to-Call Integration Guide - Complete guide with examples
Make Outbound Call API Reference - Full API documentation

Try it out

Beta Notice

The phone AI agent is currently in beta. Join the Beta Website to try it out yourself and join our Discord Community for feedback and support.

Phone AI Integration

On this page