A step by step guide to buy a number from Retell

This guide will walk through how to purchase a number from Retell. The numbers are managed by Retell, so you don’t have to worry about the telephony infrastructure.

Currently we only support purchase of US numbers and only support making domestic calls from the platform. If you are looking to use numbers from other countries, or to make international calls, or to use your own telephony provider, check out Custom Telephony guide.

​From Dashboard

You can purchase and bind agents to the number from the dashboard. You can optionally specify the area codes you want to purchase from.

After the number is purchased, you can change its nickname so that it’s easier for you to find and identify.

At this stage, the number should already be ready to accept inbound calls if you have assigned an inbound agent. Give it a try by calling it!

From API

Check out for all the parameters you can use programmatically.

• Phone numbers are yours once purchased, and can be used indefinitely. Find numbers you own .

• You can assign different inbound and outbound agent to the number.

• If you don’t want user to be able to call this number (maybe you are doing outbound and don’t want callbacks), you can leave inbound_agent_id unset.

NodePython

Pricing

Numbers are charged at $2 per month.

Configure your AI agent to detect and handle voicemails automatically

It is common that your phone agent will encounter voicemails. You can configure your agent to either hang up or leave a message when it detects a voicemail.

The system internally run voicemail detection continuously (within the timeout), and if you select to hang up in voicemail, we will do that the moment we detect we are in voicemail. If you select to leave a message, the system will wait for its turn to speak to leave that message. If the voicemail detection timeout is reached, the system will stop the voicemail detection, and will continue with the call as normal.

1

Enable Voicemail Detection

Navigate to your agent settings and enable “Voicemail Detection”

2

Choose Voicemail Behavior

Select one of two options:

• Hang up: The agent will disconnect when it detects a voicemail

• Leave a message: The agent will play a pre-recorded message after it’s agent’s turn to speak

3

Configure Detection Duration

Set the “Voicemail Detection Duration” timeout. This is the time where you will have the voicemail detection to be active for after the call is connected. With more minutes into the call, the chance you hit a voicemail is lower and you might want to turn the voicemail detection off to avoid false positives, and that’s why there’s a timeout setting here. This timeout will not cause your agent’s voicemail message to be cut off.

We recommend starting with 30 seconds, and extend this time if you reach voicemail in a later time in the call or the recorded message in that voicemail is long.

4

Set Voicemail Message (Optional)

If you selected “Leave a message” in Step 2: Enter the message you want the agent to leave. You can either set a prompt so that the message will be generated dynamically, or you can set a fixed static message.

In real-world scenarios, phone calls often face audio quality challenges such as background noise, echo, or other unwanted sounds.

While our orchestration model is designed to handle background noise effectively, you may want to fine-tune the settings for optimal performance in challenging environments.

1

Adjust the responsiveness

1. Navigate to your agent’s settings

2. Set the “Responsiveness” setting to 0.9

3. This adjustment makes the agent more deliberate in its responses, reducing false triggers from background noise.

2

Configure the interruption sensitivity

1. In the same settings panel

2. Set the “Interruption Sensitivity” to 0.8

3. This setting helps the agent distinguish between intentional speech and background interference

For extremely noisy environments like construction sites or busy streets, you may need to experiment with even higher settings.

Conversation flow agent allows you to create multiple nodes to handle different scenarios in the conversation. It provides more fine-grained control over the conversation flow compared to single / multi prompt agent, which unlocks the ability to handle more complex scenarios.

​Components

• Global Settings: Global settings are settings that apply to the entire conversation. For example, you can set the global prompt, default voice, language, and other agent related settings here.

• Node: A node is a basic unit of conversation flow. There’s multiple types of nodes. A node can define how to interact with user, how to make function calls, and many other settings.

• Edge: An edge is a connection between two nodes. It defines the conditions for transitioning from one node to another.

• Functions: Define functions used by this agent, and select them in individual function nodes.

How it Works

Every node defines a small set of logic, and the transition condition is used to determine which node to transition to. Once the condition is met when checked, the agent will transition to the next node. There are also finetune examples on nodes that can help you further improve the performance. It might take longer to set up, as you want to cover all the scenarios, but after that it’s much easier to maintain and the performance is more stable and predictable.

Quickstart

Head to the Dashboard, create a new conversation flow agent and select a pre-built template to get started. You can view all options available to the agent within the Dashboard, with details of the options and any lantency implications listed there. You can also view the estimated latency and cost of the agent. Modify the template to your needs, all changes are auto saved.

Pricing

Since the choice of model can be overriden within individual nodes, the pricing for each call is calculated based on how many seconds spent within each node * the model price per second for that node, and aggregated across all nodes.

Deploy your first phone agent in 5 minutes.

Retell is a platform for building, testing, deploying, and monitoring reliable AI phone agents that can handle natural conversations over the phone.

1

Create Your Account

1. Visit the Retell Dashboard

2. Sign up for a new account

2

Create a New Agent

1. Navigate to the “Agents” tab

2. Click “Create an agent”

3. Choose a template

   • If you are not sure which template to choose, we recommend starting with “Lead qualification” in “Multi Prompt” category.

3

Test Your Agent

1. Click the “Test” button to test your agent

4

Add your payment method

1. Before buying a phone number, you need to add a payment method to your account

2. Go to the “Billing” tab and click “Change payment methods”

5

Deploy to a Phone Number

1. Go to the “Phone Numbers” tab

2. Click “Buy New Number”

3. (Optional) Enter the area code you want to buy the number for

4. Purchase your number

6

Test Your Phone Agent

1. Incoming Calls:

   • Dial your purchased number

2. Outbound Calls:

   • Click “Make an outbound call”

🎉 Congratulations! Your agent is now live and can:

• Receive incoming calls

• Make outbound calls

• Handle natural conversations

• Process requests 24/7

Testing is essential for successfully deploying your agent to production. Follow these recommended steps to ensure a robust deployment:

​Step 1: LLM and Web Call Testing

Validate and refine your agent’s behavior:

• Use the LLM Playground to test conversation flows and responses

• Use

• Ensure accurate function calling and conversation handling

Step 2: Phone Audio Testing

Test your agent in phone environments:

• Place test calls to your agent

• Initiate outbound calls from your agent

• Validate performance with background noise and user interruptions

Step 3: Limited Production Testing

Perform controlled testing in production:

• Deploy with a small sample size (5-10 calls)

• Use to track performance

• Measure critical metrics including completion rates and user satisfaction

Step 4: Gradual Rollout

Scale your deployment strategically:

• Incrementally expand your user base

• Maintain continuous performance monitoring

In this guide, we will show how to integrate Retell agents with your telephony providers and use your numbers. Please note that this is independent of the agent type you are using.

We will provide two ways to integrate with your telephony provider:

1. Elastic SIP trunking: This is the recommended way to integrate with your telephony provider that supports elastic SIP trunking. You will need to set up a SIP trunking and configure your number to point to it, and then import that number to Retell.

2. Dial to SIP Endpoint: If your telephony provider does not support elastic SIP trunking, or you have more complicated telephony setup that cannot use elastic SIP trunking, you can dial the call to a specific SIP endpoint.

• Retell SIP server uri: sip:5t4n6j0wnrl.sip.livekit.cloud

• If inbound does not work (might be due to initial SDP being dropped), specify to use TCP as the transport protocol: sip:5t4n6j0wnrl.sip.livekit.cloud;transport=tcp

We currently do not provide a static IP address for the SIP server, as it’s deployed globally across different cloud.

Method 1: Elastic SIP trunking (Recommended)

Elastic SIP Trunking is a service offered by cloud communications platforms that enables organizations to connect their existing PBX (Private Branch Exchange) or VoIP (Voice over IP) infrastructure to the Public Switched Telephone Network (PSTN) over the internet using the SIP (Session Initiation Protocol).

In this context, the elastic SIP trunking is used to connect Retell’s VoIP with PSTN so that your agents can make and receive calls. When using this method, all the telephony functionalities that are supported by Retell numbers will also be supported here, assuming that your telephony provider supports it.

SIP trunking is a popular service offered by many telephony providers, so most likely your telephony provider would be able to support this.

Here’re detailed guides for some telephony providers:

Getting help

If you are using a telephony provider that requires static IP address, or you are having trouble setting up, you can check out our partner , where you can connect to Jambonz’s system that already connects with Retell (which supports static IP address) and use their SIP trunking service. Dedicated slack support channel is available for Retell users.

Method 2: Dial to SIP Endpoint

If your telephony provider does not support elastic SIP trunking, or you have more complicated telephony setup that cannot use elastic SIP trunking, you can use this method.

When using this method, Retell does not directly make or receive calls, but instead relies on your system to dial the call to the respective SIP endpoint. This would require you to have some codes to handle integration with your telephony provider. All traffic looks like inbound to Retell in this case, so it’s up to you to specify the call direction.

When using this method, you will not be able to utilize Retell’s transfer call feature, as we do not have information about the underlying telephony provider and number.

Here we assume you already have your call handling setup. For Retell to know what agent to use to handle the call, and for you to obtain SIP endpoint to use for this call, you would call the . You will get a call_id back from this API, and you would use it to piece together the SIP endpoint.

SIP endpoint: sip:{call_id}@5t4n6j0wnrl.sip.livekit.cloud

Example Code

Here’s an overly simplified example code to handle the inbound call webhook from Twilio and dialing the call to the SIP endpoint.

Node

Learn how to use Retell’s Node.js and Python SDKs

While you can use our REST API for most operations, we recommend using our SDKs to speed up development and reduce code complexity. Our SDKs provide typed methods and a more structured approach to integrating with Retell.

​Available SDKs & Requirements

• Node.js TypeScript SDK

  • Requires Node.js version 18.10.0 or higher

• Python SDK

  • Requires Python 3.x

1

Get Your API Key

Navigate to the “API Keys” tab in your dashboard to obtain your API key.

2

Install the SDK

Choose your preferred language and install the SDK:

Node ClientPython Client

3

Initialize the Client

Create a new client instance using your API key:

Node ClientPython Client

4

Make API Calls

Here’s an example of making a phone call using the SDK:

Node ClientPython Client

SDK vs REST API Example

To illustrate the benefits of using our SDK, here’s a comparison of creating an agent using both methods:

Using REST API (More Verbose)

Using SDK (More Concise)

Best Practices

1. Error Handling: Always wrap SDK calls in try-catch blocks

2. Type Safety: Take advantage of TypeScript types in the Node.js SDK

3. API Reference: Refer to our for all available parameters

Additional Resources

Find more SDK examples in our test suites to learn more about how to use the SDK:

In the agent detail page, click “Test” to make a web call to test your agent.

Learn how to effectively test and debug your AI agents using the LLM Playground

The LLM Playground provides a convenient environment for testing your AI agents without making actual web or phone calls. This interactive testing interface enables:

• Rapid prototyping and debugging of agent responses

• Testing different conversation scenarios

• Immediate feedback on agent behavior

• Faster development iterations

1

Access the LLM Playground

1. Navigate to your agent’s detail page

2. Click on the “Test LLM” tab

3. You’ll see the chat interface where you can start testing

LLM Playground Interface

2

Test Basic Conversations

1. Type your message in the input field

2. Observe the agent’s response

3

Test Function Calling

1. Use prompts that should trigger specific functions

2. Verify that functions are called with correct parameters

4

Iterate and Refine

1. Monitor agent behavior and responses

2. Update prompts or functions as needed

3. Click the “delete” button to reset conversations

4. Test the updated behavior

Iterate and test

5

Save Test Cases

1. Click the “Save” button to store your test conversation

2. Add a descriptive name for the test case

3. Access saved tests from the agent detail page

Save test case

Saved test cases

6

Test Dynamic Variables

1. Use dynamic variables in your prompts

2. Verify that variables are properly interpolated

3. Test different variable values and scenarios

Best Practices

• Start with simple conversations and gradually test more complex scenarios

• Save important test cases for regression testing

• Test edge cases and error handling

• Document unexpected behaviors for future reference

A step by step guide to make & receive phone calls with Retell managed numbers & imported numbers

From previous guides, you already have numbers purchased or imported. This guide will walk through how to assign agents, and make and receive phone calls.

​Bind Voice Agents

• Only when you bind agents to a number will the number be able to receive and make calls.

• You can assign different inbound and outbound agent to the number.

• You can leave agent unset to disable inbound / outbound (for example, you are doing outbound and don’t want callbacks, you can leave inbound_agent_id unset)

After binding an agent for inbound, you should be able to receive inbound calls already.

Make Outbound Call

If you are using a number purchased from Retell, right now it’s not able to make international calls. This restriction does not apply to imported numbers, as you have to set geo location permissions yourself at your telephony provider.

Check out for all the parameters you can use.

• from_number is the e.164 string format of the number you purchased earlier.

• to_number is the phone number you want to call in e.164 string format.

NodePython

Update the Voice Agent Bound to A Number

Check out for all the parameters you can use to update the inbound and outbound agent who handles the phone. You can also turn off the inbound calls for the number by setting inbound_agent_id to null.

Get Call Detail

• API: You can use to get information like transcript, recording, latency tracking, etc.

• Webhook: You can also setup webhooks to receive real time updates when call is initiated, ends, and analyzed. Read more at .

Understand the constraints and limitations of the agents.

We have enforced some constraints and limitations to ensure the smooth operation of your agents, and prevent any misuse of the service. Note that these constraints can be adjusted based on your operational needs, on a case-by-case basis.

​Concurrency

As part of our service, Pay-As-You-Go users are allocated a quota of 20 concurrent calls. Should your operational needs require additional concurrency, you can go to “Billing” page to upgrade your plan.

Billing Page

You can check your current number of concurrent calls in the dashboard.

• Handling Multiple Calls per Agent: You don’t need to create multiple agents to manage multiple calls concurrently. Each agent within your plan is capable of handling an unlimited number of calls, provided that the total concurrency remains within your designated quota. This means you can efficiently manage your workload without unnecessary agent duplication.

Max Call Duration

The maximum duration of a call is 1 hours by default, and the call will end automatically after 1 hour. Should your operational needs require longer calls, please reach out to our team at to discuss options.

Max Prompt Token Length

The maximum length of prompt when using Retell LLM framework is 8192 by default, and longer prompt will be rejected when creating or updating the LLM. Should your operational needs require longer context, please reach out to our team at to discuss options.

A step by step guide to create a web call with agent using frontend Web SDK

​Set up the SDK

Step 1: Install the Retell Web SDK

npm install retell-client-js-sdk

Step 2: Set up the SDK class

Call create-web-call to get call id

Your client code should call your server endpoint which internally calls to get the access token for the call. The endpoint requires using your Retell API Key, which is the reason why you need to call the endpoint from the server instead of client to protect the key from exposing.

The access token obtained will be used in your frontend client code to start the call.

Note that if you do not start the call within 30s obtaining the access token, we will invalidate it and the call will be marked with error.

Start the Call

Once call starts, you can listen to a couple events that’s emitted for real time updates about the call.

There are other optional options that allow you to set the sample rate of call, audio capture and playback device, whether to receive raw audio bytes from the client.

Stop the Call

You can close a web call with the agent by using

Listen to events

You can listen to events emitted by the SDK to get real time updates about the call, including who is speaking, the real time transcript, start and end of the call.

Audio Basics

If you have not worked with audio bytes before, we stronly suggest you to check out , which can help with choosing the best configuration here.

PCM audio format conversion functions convertUnsigned8ToFloat32 and convertFloat32ToUnsigned8 can be found in .