Make Calls
Migration Guide
How to smoothly migrate to Call API V2
As part of the migration from audio Websocket to WebRTC for internal audio communication, and as part of the migration to using SIP for telephony integration, we have updated the Call API to V2. The new API looks pretty similar to the old one, but with a few changes. This doc will help you migrate to the new API smoothly.
We will stop supporting Deprecated V1 Call API
and Audio websocket starting 1/1/2025.
What Has Changed
The new Call API V2 has a few changes from the previous version:
- Retell now uses WebRTC instead of Websocket underlying for the call, this results in a couple fields being removed, and some fields
being added.
- Removed fields:
audio_websocket_protocol
,audio_encoding
,sample_rate
- Added fields:
call_type
to distinguish web call and phone call,access_token
for web call to join WebRTC room.
- Removed fields:
- Retell now uses SIP for telephony integration. This means that the old way to integrate with custom Twilio is deprecated, you do not need to have your own server to listen to Twilio webhook and handle it anymore. You can follow the Custom Telephony Integration Guide for details.
- We are splitting the call object for web call and phone call, and have respective different APIs now.
- Web call will use Create Web Call API
- Phone call will use Create Phone Call API, note that there’s a v2 in the path of the API, which is different from the previous create phone call API.
- Get Call and List Calls API will return the
different call object based on the call type.
- Web Call object will have
access_token
field used to join the call. - Phone Call object will have
from_number
,to_number
,direction
fields.
- Web Call object will have
- List Calls API is now a POST method: this allows easier use of the filtering with its object type.
- Register Call API is deprecated.
- For web calls, you can use Create Web Call API to get the access token.
- For custom telephony integration, you can set it up according to the Custom Telephony Integration Guide with no codes and servers needed. If you wish to integrate by calling to SIP endpoint, you can use new Register Phone Call API.
Migration Steps
Telephony
- For number purchased in Retell, nothing needs to be done as it’s already migrated to new infrastructure.
- For custom telephony integration, follow the Custom Telephony Guide for details.
SDK
- Update to newest version SDK for your backend.
- Remove any audio websocket related codes.
- Some of the method names might have changed:
- outbound phone call:
create
->createPhoneCall
(Node.js) orcreate_phone_call
(Python) - web call:
register
->createWebCall
(Node.js) orcreate_web_call
(Python)
- outbound phone call:
- Remove dependencies on deleted fields
- For Web Call users: update to newest version SDK for your frontend. (See Web Call Guide for details)
- Some of the method names might have changed:
startConversation
->startCall
: the parameters now require the access token.stopConversation
->stopCall
- events emitted have its naming changed from camelCase to snake_case.
- Now have a mute and unmute function.
- Some of the method names might have changed:
Raw API
The new Call API V2 has a /v2 in the path, and the fields changed a bit as mentioned above. See API Reference for details.
Webhooks
The webhook payload has populated a new field call
which contains the new call object. The old field data
is being deprecated.
See more details in Webhook Guide.
Was this page helpful?