How to Migrate to the New Version of the Call Control API
Articles - 2 min read

How to Migrate to the New Version of the Call Control API

The new Call Control API has been designed to make migration simple. This guide will take you through the key changes you should know about when migrating your Call Control application from API v1 to API v2.
Call Control in API v2 offers the same great call experience but with some changes, aimed at making it even easier to have granular-level control over your calls. For new Telnyx users, SDKs available in multiple languages and the introduction of TeXML Translator enable you to get started in minutes. For users with an existing API v1 application, we’ll cover the main changes you should make to migrate to our latest API version.
There are three main areas that require minor changes:
1. API authentication
2. Webhook structure and signature validation
3. API endpoints

API Authentication

API v2 uses a different authentication strategy that will require you to generate a new API key for your Call Control application. You can do that easily via the Telnyx Mission Control Portal.
Webhook Structure and Signature Validation
The webhook structure and signature validation mechanism has been updated in API V2.
In the API V2 webhook body, there is a top-level data object that contains all subsequent information about the webhook. The top level created_at field in API v1 has been renamed occurred_at - this is the time that the event occurred.
The naming convention of the event_type field has also changed for API v2. While the field names remain in snake_case, for event_type the call event being described will be in dot.case for all call events. Events can contain multiple dots to indicate a relationship.
For example, in API v1 when initiating text-to-speech, if the command is successful, your application will receive a webhook containing "event_type":"speak_started". In API v2, your application would receive "event_type":"call.speak.started" for this call event.
API v2 webhook structures are not enabled by default. To begin receiving webhooks in the new format, you'll need to update your Call Control Application settings for any application you'd like to migrate to API v2.
Each Call Control webhook event that we send you will include a Telnyx signature. The signature allows you to validate that webhooks were not sent by a third-party.
While API v1 uses an HMAC with the SHA256 hash function to sign webhooks, API v2 uses the EdDSA digital signature scheme with a public key. You can read more on this in our developer docs.

API Endpoints

API v2 requests have different endpoints to API v1 commands. The base URL for API v2 is https://api.telnyx.com/v2/. The endpoints carry out the same functions, just at a different URL:

To find out more, take a look at the Call Control API Reference and quickstart guide. Technical questions? Join our developer slack channel to have them answered 24/7.
Share on Social

Worth checking out

By using the site, you agree to our use of cookies. Accept and close Find out more here.