The Retell hosted app allows you to connect a call to retell from any SIP provider, it also supports Retell transferring the call via SIP refer or a new outbound leg.

It can be used for both inbound and outbound calls, with outbounds calls you would initiate the call by making a REST API request to the Create Call endpoint

Requirements

Before setting up the hosted application you will need:

A Jambonz Account,
A Retell account,
A SIP carrier configured in your jambonz account for connecting to the PSTN.
A Phone number configured in your jambonz account for the above carrier.

Get started

SIP client

You will need to create a new Client in your jambonz account in order for retell to make outbound calls, on the Clients tab of the jambonz UI click the + icon and then create a new username and password, make a note of the username and password you created and then click save

When you are returned to the client list screen you should also see a SIP Realm at the top of the page, make a note of this too

Application

Enter the name of your application, this can be anything, we suggest starting out with retell Enter the Calling Webhook below, the same value should be automatically copied to the Call Status Webhook.

Calling Webhook

wss://retell.jambonz.app

When you enter the webhook some new fields will then appear beneath that as shown below, these are the Application Environment variables for this hosted application. We’ll go through how you should configure these next.

Client Application

Now that you have created your application you need to configure you account so that calls made using the SIP client are routed to this application.

On the account page scroll dow to Application for SIP device calls and select the name of the application you just created.

Configuration

RETELL_TRUNK_NAME

You can leave this as the default of retell-hosted on jambonz.cloud as there is a shared carrier already created with the correct settings.

RETELL_SIP_CLIENT_USERNAME

Set this to the name of the SIP client you created earler on for retell to connect to.

PSTN_TRUNK_NAME

The name of your SIP carrier in Jambonz that you want retell to use for outbound calls.

DEFAULT_COUNTRY

If you experience issues with your carrier sending the destination number in local format set this to the ISO-3166 country code of your number and the application will rewrite the number into the proper International e.164 format expected by Retell. The code is 2 characters for example us or gb Full List

OVERIDE_FROM_USER

When making calls from Retell to then PSTN your carrier may want you to use a custom value in the From header, if so set this here. Sipgate is one such carrier.

PASS_REFER

Controls if a refer is sent to the originating carrier or treated as a new outbound leg, see the Call Transfer section.

Other Configuration

The other parameters can be left as default.

Now link your phone number to this application on the phone numbers page.

Retell Configuration

Now you can login to your Retell account and add a new phone number, select Connect to your number via SIP Trunking and then enter;

Your PSTN number from your carrier (note this needs to be in e.164 format eg +12125551212) The sip realm you noted earlier as the Termination URI In the SIP Trunk User Name enter the user of the client you created In the SIP Trunk Password enter the password of the client you created.

Now you can associate that number with your retell agent and process calls.

Retell Call Transfer

The Retell agent has the ability to transfer either an inbound or outbound call to another number, There are a few configuration options within retel that will impact how this transfer is passed to Jambonz.

You can choose a Cold or Warm Transfer, and within a Cold Transfer you can choose to send the Agents Number or the Original Callers Number.

A Cold Transfer with the Retell Agent`s Number or a Warm Transfer will initiate a new outbound call leg from retell through Jambonz, this will be seen to Jambonz as a brand new call and will use a 2nd instance of your availble channels. Retell and Jambonz remain in the call path for the duration of the call, if you have selected a Warm Transfer there are some additional options where retell will play messages to either of the parties on the call.

If you select a Cold Transfer with the Transferee’s Number then retell will send a SIP REFER message back to Jambonz, at this stage you have 2 options depending on the configuration of the PASS REFER flag in your application configuration at jambonz. If set to True then jambonz will send the SIP REFER on to your originating carrier, if they support SIP REFER then they will transfer the call from jambonz to the new destination, once this is completed both Retell and Jambonz are completely out of the call path.

If PASS REFER is set to false then jambonz will turn the SIP refer into a new outbound call leg from Jambonz via your carrier, this will then remove retell from the call path but keep the call in Jambonz, it will only use one of your availble channels.

Override Carrier & Number

Sometimes you may want to transfer the call to an internal number like on your PBX, Retell only allows you to enter full valid phone numbers here and not to use a private mnumber like 1000, The application provides the ability to override these by sending custom SIP headers from Retell in the call transfer.

If you set a header of X-Override-Carrier then value should contain the name of the trunk you want to use for for the call, this will override the PSTN_TRUNK_NAME in your application configuration If you set a header of X-Override-Number then the value will contain a number to be sent to the carrier instead of the destination number set in the Retell transfer node

These headers can be used independently to override either the carrier or the number.

Help & support

If you experience any issues with using the Hosted application via Jambonz.cloud then please email support@jambonz.org and include a call_sid for an example call that shows the issue along with the date & time of the call.

Please also mention that you are using the Retell Hosted application.

You can view the code for this application on our GitHub