This is the current API V1 documentation. Explore our API V2 if you’d like to test new features.

Setup Guide

In this guide, you’ll learn how to get started with Telnyx Messaging within the Telnyx Mission Control Portal. Just follow these simple steps:

  1. Sign up for a Telnyx account.
  2. Buy an SMS-capable phone number.
  3. Create a messaging profile to configure how you send and receive messages on your phone number.
  4. Assign your phone number to your messaging profile.

Step 1: Sign Up for a Telnyx Mission Control Portal Account

Head to telnyx.com/sign-up to sign up for your free Telnyx account. It’ll give you access to our Mission Control Portal where you can buy numbers, set up and manage messaging profiles, and more.

A free credit will be automatically applied to your account upon signup. To enter a promo code, click on My Account in the top-right portal dropdown.

Step 2: Buy an SMS-capable Phone Number

To use the Messaging API, you’ll need an SMS-capable phone number purchased from, or ported into, the Telnyx platform. If purchasing a new number, select the SMS number feature when searching. In general, numbers that are ported in will be messaging-capable.

Within the Numbers section of the Telnyx Portal, you can search for, buy and provision new numbers – or port existing numbers.

  1. Click on Numbers in the navigation menu on the left-hand side of the portal.
  2. Click on the Search & Buy Numbers tab and enter your city, country or rate center.
  3. Select the number features you want. You can choose “Any” or check the individual boxes to select specific features: Voice, Fax, SMS, MMS.
  4. Click Search.
  5. Find the number(s) you want to purchase from the list of results and then click +Add to Cart.
  6. Click on your Cart in the top-right corner of the portal. The number(s) you selected should now be visible in your Cart.
  7. To purchase, click Place Order*. Your number(s) should now be visible in both the “My Numbers” and “Orders” tabs.

Note: You’ll need to ensure that you have enough available credit to make the purchase. To add credit to your account, click the + button to the left of your balance in the top-right corner of the portal.

You can also add/buy numbers programmatically via our RESTful API. Check out our documentation for number searching and ordering.

Step 3: Create a Messaging Profile

Messaging Profiles are the simplest way for you to configure your inbound and outbound messaging settings. An SMS-capable phone number is SMS-enabled by assigning it to a Messaging Profile.

Configure your profile to send and receive SMS messages.

  1. Click on Messaging in the navigation menu on the left-hand side of the portal.
  2. Click Add new profile.
  3. Enter a name for your Messaging Profile. Configure any other desired settings, such as webhook URLs.

    Note: Ensure the profile is using API V1

  4. Click Save to create the profile.

That’s it. Your Messaging Profile has now been created.

You can also do this programmatically via our RESTful API. Check out our documentation for creating a Messaging Profile and assigning it to a number.

Alphanumeric Sender ID: As an alternative to sending SMS from a phone number, you can use an alphanumeric sender ID. Messages sent in this manner are outbound only; it is not possible to receive replies. To use an alphanumeric sender, simply put it in the from field when you submit a send request.

Step 4: Assign Your Phone Number to Your Messaging Profile

Once you’ve created a messaging profile, you’ll need to add your number to that profile:

  1. Click on My Numbers in the navigation menu on the left-hand side of the portal.
  2. Click the My Numbers tab and find the number you want to add to your messaging profile.
  3. For your number, click on the “Select profile to send messages” box in the “Messaging Profile” column.
  4. In the window that opens, select your messaging profile from the dropdown menu under “SMS Messaging”.
  5. Click Save Changes.
  6. The changes may change your monthly recurring charge (MRC) for the number. Click Accept if you approve the change.

Your messaging profile should now show an updated count under “Numbers Connected” on your Messaging Profiles page. If the count has not changed, refresh your page to update.

You can also do this programmatically via our RESTful API. Check out our documentation for assigning a number to a Messaging Profile.

That’s it, you’re all set to start messaging. Next, learn how to send and receive messages with Telnyx.