How to Migrate to the New Version of the Telnyx SMS API
Articles - 2 min read

How to Migrate to the New Version of the Telnyx SMS API

The new Telnyx Messaging API has been designed to make migration smooth. This guide highlights the main changes to be aware of when migrating your messaging application from API v1 to API v2.
Messaging in the new version of the API offers the same great functionality, with some changes aimed at making it even easier to have granular-level control over your messaging metrics and deliverability.
For new Telnyx users, SDKs are available in multiple languages and the introduction of Twexit enables 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 v2 Authentication
2. Webhook Structure and Signature Validation
3. Endpoints for Sending Messages

API v2 Authentication

API v2 utilizes a different authentication strategy that will require you to generate a new API key for your Messaging 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 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 event will be in dot.case. Events can contain multiple dots to indicate a relationship.
For example, in API v1 when sending an SMS, if the send is successful, your application will receive a webhook containing "event_type":"delivered". In API v2, your application would receive "event_type": "message.finalized" for this webhook event.
API v2 webhook structures are not enabled by default. To begin receiving webhooks in the new format, you will need to update your Messaging Profile settings for any application you wish to migrate to API v2.
Each messaging 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 here.

Endpoints for Messages

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 exactly the same functions, just at a different URL:
- To send a message in API v1: https://sms.telnyx.com/messages
- To send a message in API v2: https://api.telnyx.com/v2/messages

To find out more, take a look at the Messaging API Reference and quickstart guide. 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.