Migration guide

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.

​

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.
• 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.
• 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

1. 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) or create_phone_call (Python)
     • web call: register -> createWebCall (Node.js) or create_web_call (Python)
   • Remove dependencies on deleted fields
2. 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.

​

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.