If you were already using Call APIs and webhooks before, this doc will help you migrate to the new Call API V2 smoothly.

What Has Changed

The new Call API V2 has a few changes from the previous version:

  • 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, we will be updating docs soon, please stay tuned.
  • We use WebRTC instead of Websocket underlying for the call, and uses SIP for telephony integration. 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.

Migration Steps

SDK users

  1. Update to newest version SDK for your backend.
    • 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 users

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.

Webhook users

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.