Sending a Message on the Telnyx Platform

cURL

In this tutorial, you’ll learn how to send SMS and MMS messages using the Telnyx v2 API and the curl command. First thing's first -- make sure you have signed up for your free Telnyx Account.

Portal Setup

Follow the setup guide to configure your Portal for sending and receiving messages.

Development Environment Setup

Check out the Development Environment Setup guide to acquire your API Key.

You can paste the below snippets into your Terminal on Mac and Linux computers. Windows users should install bash on Windows.

Send an SMS or MMS with Telnyx

Follow the steps below to send SMS and MMS messages.

Using the SMS or MMS examples below, write a curl command that will submit an outbound message request. Include your API Key in the Authorization request header, and add the source ( from ) and destination ( to ) phone number, and the message’s content ( text ) into the payload. Optionally, your payload may include a webhook_url or webhook_failover_url (or both).

Send SMS

Copy

Copied

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{
    "from": "+13115552368",
    "to": "+13115552367",
    "text": "Hello, world!"
  }' \
  https://api.telnyx.com/v2/messages

Example Response

Copy

Copied

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
    "type": "SMS",
    "organization_id": "a9b37e61-32bc-4a03-bf90-080c3b55db6f",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "from": {
      "phone_number": "+19842550944",
      "carrier": "Telnyx",
      "line_type": "Wireless"
    },
    "to": [
      {
        "phone_number": "+13115552367",
        "status": "queued",
        "carrier": "SOME CARRIER",
        "line_type": "Wireless"
      }
    ],
    "text": "Hello, world!",
    "media": [],
    "webhook_url": "https://www.example.com/hooks",
    "webhook_failover_url": "https://www.example.com/callbacks",
    "encoding": "GSM-7",
    "parts": 1,
    "tags": [],
    "cost": null,
    "received_at": "2019-01-23T18:10:02.574Z",
    "sent_at": null,
    "completed_at": null,
    "valid_until": "2019-01-23T19:10:02.574Z",
    "errors": []
  }
}

Send MMS

For MMS messages, the structure of the send request differs, in order to accommodate different types of media.

Send a message with an image URL:

Copy

Copied

curl -X POST "https://api.telnyx.com/v2/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": "+13125550001",
    "to": "+13129450002",
    "subject": "Picture",
    "text": "Hello, world!",
    "media_urls" : [
      "https://picsum.photos/500.jpg"
    ]
}'

Copy

Copied

the message being sent as an MMS without any media content – the message
will still contain a subject and/or text content.

Replace the from number with your Telnyx number. Be sure to remove any delimiters like dashes or spaces.
Replace the to number with the number you want to send a message to. Make sure you’re using the full +E.164 formatted number. In the US and Canada, this typically means adding +1 to the beginning of your 10-digit phone number.
Run the updated command.

That's it! Congrats on sending your first message with your Telnyx Account.

Next, learn how to receive messages.

Python

In this tutorial, you’ll learn how to send SMS and MMS messages using the Telnyx v2 API and the Telnxy Python Library . First thing's first -- make sure you have signed up for your Telnyx Account .

Portal Setup

Follow the setup guide to configure your Portal for sending and receiving messages.

Development Environment Setup

Check out the Development Environment Setup guide to set up the Telnyx Python SDK and your development environment for this guide.

You can paste the below snippets into your Terminal on Mac and Linux computers. Windows users should install bash on Windows.

Send an SMS or MMS

Follow the steps below to send SMS and MMS messages.

Create a new file called send.py and paste in either the SMS or MMS example code given below. Additional arguments, such as webhook_url and webhook_failover_url , can be supplied in the call to telnyx.Message.create .

Send SMS

Copy

Copied

import telnyx

telnyx.api_key = "YOUR_API_KEY"

your_telnyx_number = "+13115552368"
destination_number = "+13115552367"

telnyx.Message.create(
    from_=your_telnyx_number,
    to=destination_number,
    text="Hello, world!",
)

Example Response

Copy

Copied

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
    "type": "SMS",
    "organization_id": "a9b37e61-32bc-4a03-bf90-080c3b55db6f",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "from": {
      "phone_number": "+19842550944",
      "carrier": "Telnyx",
      "line_type": "Wireless"
    },
    "to": [
      {
        "phone_number": "+13115552367",
        "status": "queued",
        "carrier": "SOME CARRIER",
        "line_type": "Wireless"
      }
    ],
    "text": "Hello, world!",
    "media": [],
    "webhook_url": "https://www.example.com/hooks",
    "webhook_failover_url": "https://www.example.com/callbacks",
    "encoding": "GSM-7",
    "parts": 1,
    "tags": [],
    "cost": null,
    "received_at": "2019-01-23T18:10:02.574Z",
    "sent_at": null,
    "completed_at": null,
    "valid_until": "2019-01-23T19:10:02.574Z",
    "errors": []
  }
}

Send MMS

For MMS messages, the structure of the send request differs, in order to accommodate different types of media.

Note that we're still using the telnyx.Message class, but specifying an additional parameter. The Telnyx API knows to send an MMS message when media_urls is specified.

Send a message with an image URL:

Copy

Copied

import telnyx

telnyx.api_key = "YOUR_API_KEY"

your_telnyx_number = "+13115552368"
destination_number = "+13115552367"

telnyx.Message.create(
    from_=your_telnyx_number,
    to=destination_number,
    subject="Picture",
    text="Hello, world!",
    media_urls=["https://picsum.photos/500.jpg"],
)

Copy

Copied

the message being sent as an MMS without any media content – the message
will still contain a subject and/or text content.

Replace the from_ number with your Telnyx number. (Note that the parameter ends with an underscore, in order to avoid collision with the python from keyword.) Be sure to remove any delimiters like dashes or spaces.
Replace the to number with the number you want to send a message to. Make sure you’re using the full +E.164 formatted number. In the US and Canada, this typically means adding +1 to the beginning of your 10-digit phone number.
Customize the text message and save the changes to send.py .
Run the script.

Copy

Copied

python send.py

That's it! Congrats on sending your first message with your Telnyx Account.

Next, learn how to receive messages.

PHP

In this tutorial, you’ll learn how to send SMS and MMS messages using the Telnyx v2 API and the Telnxy PHP Library . First thing's first -- make sure you have signed up for your Telnxy Account .

Portal Setup

Follow the setup guide to configure your Portal for sending and receiving messages.

Development Environment Setup

Check out the Development Environment Setup guide to set up the Telnyx PHP SDK and your development environment for this guide.

Send an SMS or MMS

Follow the steps below to send SMS and MMS messages.

Create a new file called send.php and paste in either the SMS or MMS example code given below. This file should be in the same directory as your composer.json file that we created during setup . Additional arguments, such as webhook_url and webhook_failover_url , can be supplied in the call to \Telnyx\Message::Create .

Send SMS

Copy

Copied

<?php
require_once __DIR__.'/vendor/autoload.php';

\Telnyx\Telnyx::setApiKey('YOUR_API_KEY');

$your_telnyx_number = '+13115552368';
$destination_number = '+13115552367';

$new_message = \Telnyx\Message::Create(['from' => $your_telnyx_number, 'to' => $destination_number, 'text' => 'Hello, world!']);

Example Response

Copy

Copied

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
    "type": "SMS",
    "organization_id": "a9b37e61-32bc-4a03-bf90-080c3b55db6f",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "from": {
      "phone_number": "+19842550944",
      "carrier": "Telnyx",
      "line_type": "Wireless"
    },
    "to": [
      {
        "phone_number": "+13115552367",
        "status": "queued",
        "carrier": "SOME CARRIER",
        "line_type": "Wireless"
      }
    ],
    "text": "Hello, world!",
    "media": [],
    "webhook_url": "https://www.example.com/hooks",
    "webhook_failover_url": "https://www.example.com/callbacks",
    "encoding": "GSM-7",
    "parts": 1,
    "tags": [],
    "cost": null,
    "received_at": "2019-01-23T18:10:02.574Z",
    "sent_at": null,
    "completed_at": null,
    "valid_until": "2019-01-23T19:10:02.574Z",
    "errors": []
  }
}

Send MMS

For MMS messages, the structure of the send request differs, in order to accommodate different types of media.

Note that we're still using the \Telnyx\Message class, but specifying an additional parameter. The Telnyx API knows to send an MMS message when media_urls is specified.

Send a message with an image URL:

Copy

Copied

<?php
require_once __DIR__.'/vendor/autoload.php';

\Telnyx\Telnyx::setApiKey('YOUR_API_KEY');

$your_telnyx_number = '+13115552368';
$destination_number = '+13115552367';

$new_message = \Telnyx\Message::Create(['from' => $your_telnyx_number, 'to' => $destination_number, 'text' => 'Hello, world!', 'subject' => 'Picture', 'media_urls' => ['https://picsum.photos/500.jpg']]);

Copy

Copied

the message being sent as an MMS without any media content – the message
will still contain a subject and/or text content.

Replace the from number with your Telnyx number. Be sure to remove any delimiters like dashes or spaces.
Replace the to number with the number you want to send a message to. Make sure you’re using the full +E.164 formatted number. In the US and Canada, this typically means adding +1 to the beginning of your 10-digit phone number.
Customize the text message and save the changes to send.php .
Run the script.

Copy

Copied

php send.php

That's it! Congrats on sending your first message with your Telnyx Account.

Next, learn how to receive messages.

Node

In this tutorial, you’ll learn how to send SMS and MMS messages using the Telnyx v2 API. First thing's first -- make sure you have signed up for your Telnyx Account .

Requirements

Follow the setup guide to configure your Portal for sending and receiving messages.

Development Prerequisites

Check out the development prerequisites to setup your Node development environment for this guide.

Send an SMS or MMS

Follow the steps below to send SMS and MMS messages.

Create a new file called send.js and paste in either the SMS or MMS example code given below. Additional arguments, such as webhook_url and webhook_failover_url , can be supplied in the call to telnyx.messages.create .

Send SMS

Copy

Copied

var telnyx = require('telnyx')('YOUR_API_KEY');

telnyx.messages.create(
  {
    'from': '+18665552368', // Your Telnyx number
    'to': '+18445552367',
    'text': 'Hello, World!'
  },
  function(err, response) {
    // asynchronously called
    console.log(response);
  }
);

Example Response

Copy

Copied

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
    "type": "SMS",
    "organization_id": "a9b37e61-32bc-4a03-bf90-080c3b55db6f",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "from": {
      "phone_number": "+19842550944",
      "carrier": "Telnyx",
      "line_type": "Wireless"
    },
    "to": [
      {
        "phone_number": "+13115552367",
        "status": "queued",
        "carrier": "SOME CARRIER",
        "line_type": "Wireless"
      }
    ],
    "text": "Hello, world!",
    "media": [],
    "webhook_url": "https://www.example.com/hooks",
    "webhook_failover_url": "https://www.example.com/callbacks",
    "encoding": "GSM-7",
    "parts": 1,
    "tags": [],
    "cost": null,
    "received_at": "2019-01-23T18:10:02.574Z",
    "sent_at": null,
    "completed_at": null,
    "valid_until": "2019-01-23T19:10:02.574Z",
    "errors": []
  }
}

Send MMS

For MMS messages, the structure of the send request differs, in order to accommodate different types of media.

Note that we're still using the telnyx.messages.create method, but specifying an additional parameter. The Telnyx API knows to send an MMS message when media_urls is specified.

Send a message with an image URL:

Copy

Copied

var telnyx = require('telnyx')(YOUR_API_KEY);

telnyx.messages.create(
 {
    'from': '+18665552368', // Your Telnyx number
    'to': '+18445552367',
    'media_urls': [
      'https://picsum.photos/500.jpg'
    ]
  },
  function(err, response) {
    // asynchronously called
    console.log(response)
  }
);

Replace the from number with the number you purchased above.
Replace the to number with your own phone number. Ensure that you are using the full +E.164 formatted number. In the US and Canada, for example, this typically means adding +1 to the beginning of your phone number.
Customize the text message and save changes to send.js .
Finally, back in your terminal run:

Copy

Copied

node send.js

That's it! Congrats on sending your first message with your Telnyx Account.

Next, learn how to receive messages.

Java

In this tutorial, you’ll learn how to send SMS and MMS messages using the Telnyx v2 API and the Telnxy Java Library . First thing's first -- make sure you have signed up for your Telnyx Account .

Portal Setup

Follow the setup guide to configure your Portal for sending and receiving messages.

Development Environment Setup

Check out the Development Environment Setup guide to set up the Telnyx Java SDK and your development environment for this guide.

You can paste the below snippets into your Terminal on Mac and Linux computers. Windows users should install bash on Windows.

Send an SMS or MMS

Follow the steps below to send SMS and MMS messages.

Create a new file called TelnyxMessaging.java and paste in either the SMS or MMS example code given below. Additional arguments, such as webhook_url and webhook_failover_url , can be supplied in the call to CreateMessageRequest.setWebhookUrl and CreateMessageRequest.webhookFailoverUrl respectively.

Send SMS

Copy

Copied

import java.util.Arrays;
import com.telnyx.sdk.ApiClient;
import com.telnyx.sdk.ApiException;
import com.telnyx.sdk.Configuration;
import com.telnyx.sdk.auth.*;
import com.telnyx.sdk.model.*;
import com.telnyx.sdk.api.MessagesApi;

public class Example {

    private static final String YOUR_TELNYX_NUMBER = "+19842550944";
    private static final String YOUR_MOBILE_NUMBER = "+19198675309";
    private static final String YOUR_TELNYX_API_KEY = "YOUR_API_KEY";

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.telnyx.com/v2");

        // Configure HTTP bearer authorization: bearerAuth
        HttpBearerAuth bearerAuth = (HttpBearerAuth) defaultClient.getAuthentication("bearerAuth");
        bearerAuth.setBearerToken(YOUR_TELNYX_API_KEY);

        MessagesApi apiInstance = new MessagesApi(defaultClient);
         // CreateMessageRequest | Message payload
        CreateMessageRequest createMessageRequest = new CreateMessageRequest()
                .from(YOUR_TELNYX_NUMBER)
                .to(YOUR_MOBILE_NUMBER)
                .text("Hello From Telnyx");
        try {
            MessageResponse result = apiInstance.createMessage(createMessageRequest);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling MessagesApi#createMessage");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Example Response

Copy

Copied

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
    "type": "SMS",
    "organization_id": "a9b37e61-32bc-4a03-bf90-080c3b55db6f",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "from": {
      "phone_number": "+19842550944",
      "carrier": "Telnyx",
      "line_type": "Wireless"
    },
    "to": [
      {
        "phone_number": "+13115552367",
        "status": "queued",
        "carrier": "SOME CARRIER",
        "line_type": "Wireless"
      }
    ],
    "text": "Hello, world!",
    "media": [],
    "webhook_url": "https://www.example.com/hooks",
    "webhook_failover_url": "https://www.example.com/callbacks",
    "encoding": "GSM-7",
    "parts": 1,
    "tags": [],
    "cost": null,
    "received_at": "2019-01-23T18:10:02.574Z",
    "sent_at": null,
    "completed_at": null,
    "valid_until": "2019-01-23T19:10:02.574Z",
    "errors": []
  }
}

Send MMS

For MMS messages, the structure of the send request differs, in order to accommodate different types of media.

Note that we're still using the telnyx.Message class, but specifying an additional parameter. The Telnyx API knows to send an MMS message when media_urls is specified.

Send a message with an image URL, just create a CreateMessageRequest with mediaUrls:

Copy

Copied

// Create the new SMS message payload
CreateMessageRequest createMessageRequest = new CreateMessageRequest()
        .from(YOUR_TELNYX_NUMBER)
        .to(YOUR_MOBILE_NUMBER)
        .text("Hello From Telnyx")
        .mediaUrls(Arrays.asList(
                "https://upload.wikimedia.org/wikipedia/en/5/5f/Original_Doge_meme.jpg"
        ));

Copy

Copied

the message being sent as an MMS without any media content – the message
will still contain a subject and/or text content.

Replace the from number with your Telnyx number. Be sure to remove any delimiters like dashes or spaces.
Replace the to number with the number you want to send a message to. Make sure you’re using the full +E.164 formatted number. In the US and Canada, this typically means adding +1 to the beginning of your 10-digit phone number.
Customize the text message and save the changes to TelnyxMessaging.java .
Compile and run.

Next, learn how to receive messages with Telnyx.

.NET

In this tutorial, you’ll learn how to send SMS and MMS messages using the Telnyx v2 API and the Telnxy.net Library . First thing's first -- make sure you have signed up for your Telnyx Account .

Portal Setup

Follow the setup guide to configure your Portal for sending and receiving messages.

Development Environment Setup

Check out the Development Environment Setup guide to set up the Telnyx.net SDK and your development environment for this guide.

You can paste the below snippets into your Terminal on Mac and Linux computers. Windows users should install bash on Windows.

Send an SMS

Follow the steps below to send SMS messages with dotnet core v3.1+

Using the dotnet CLI create a new console application and change directories to the newly created folder. Then add the Telnyx.net package.

Copy

Copied

$ dotnet new console --output send-sms
$ cd send-sms
$ dotnet add package Telnyx.net

Open the Program.cs file created for you in the directory. It should look something like the code below:

Original Program.cs

Copy

Copied

using System;

namespace send_sms
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello World!");
        }
    }
}

Tell the application to use Telnyx.net by adding: using Telnyx; before the namespace
In order to use the Asynchronous methods, we need to modify our Main method to return a Task and make it async.
4.1. static void Main(string[] args) should be static async Task Main(string[] args).

4.2. Add using System.Threading.Tasks; before the namespace.
Modify the Main method to look something like the following code:

Updated Program.cs

Copy

Copied

using System;
using Telnyx;
using System.Threading.Tasks;

namespace send_sms
{
  class Program
  {
    private static string TELNYX_API_KEY = System.Environment.GetEnvironmentVariable("TELNYX_API_KEY");
    private static string telnyxNumber = "+19194150467";
    private static string destinationNumber = "+19198675309";

    static async Task Main(string[] args)
    {
      Console.WriteLine("Hello World!");
      TelnyxConfiguration.SetApiKey(TELNYX_API_KEY);
      MessagingSenderIdService service = new MessagingSenderIdService();
      NewMessagingSenderId options = new NewMessagingSenderId
      {
        From = telnyxNumber,
        To = destinationNumber,
        Text = "Hello, World!"
      };
      try
      {
        MessagingSenderId messageResponse = await service.CreateAsync(options);
        Console.WriteLine(messageResponse.Id);

      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
      }
    }
  }
}

Run the program

Finally, restore and run the application

Copy

Copied

$ dotnet restore
$ TELNYX_API_KEY="YOUR_API_KEY" dotnet run
$ TELNYX_API_KEY="YOUR_API_KEY" dotnet run
Hello World!
4031742c-d288-49f0-b4b9-809931dbd27c

That's it! Congrats on sending your first message with your Telnyx Account.

Next, learn how to receive messages.

Ruby

In this tutorial, you’ll learn how to send SMS and MMS messages using the Telnyx v2 API and the Telnyx Ruby Library . First thing's first -- make sure you have signed up for your free Telnyx Account.

Portal Setup

Follow the setup guide to configure your Portal for sending and receiving messages.

Development Environment Setup

Check out the Development Environment Setup guide to set up the Telnyx Ruby Gem and your development environment for this guide.

You can paste the below snippets into your Terminal on Mac and Linux computers. Windows users should install bash on Windows.

Send an SMS or MMS

There are three steps required to send our initial message. Import the library, configure the API Key, and send the request.

Create a new file called send.rb and paste in either the SMS or MMS example code given below. Additional arguments, such as webhook_url and webhook_failover_url , can be supplied in the call to Telnyx::Message.create .

Send SMS

Copy

Copied

require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

from_number = "YOUR_TELNYX_NUMBER"
to_number = "DESTINATION_NUMBER"

response = Telnyx::Message.create(
    from: from_number,
    to: to_number,
    text: "Hello, world!"
)

Example Response

Copy

Copied

{
  "data": {
    "record_type": "message",
    "direction": "outbound",
    "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
    "type": "SMS",
    "organization_id": "a9b37e61-32bc-4a03-bf90-080c3b55db6f",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "from": {
      "phone_number": "+19842550944",
      "carrier": "Telnyx",
      "line_type": "Wireless"
    },
    "to": [
      {
        "phone_number": "+13115552367",
        "status": "queued",
        "carrier": "SOME CARRIER",
        "line_type": "Wireless"
      }
    ],
    "text": "Hello, world!",
    "media": [],
    "webhook_url": "https://www.example.com/hooks",
    "webhook_failover_url": "https://www.example.com/callbacks",
    "encoding": "GSM-7",
    "parts": 1,
    "tags": [],
    "cost": null,
    "received_at": "2019-01-23T18:10:02.574Z",
    "sent_at": null,
    "completed_at": null,
    "valid_until": "2019-01-23T19:10:02.574Z",
    "errors": []
  }
}

Send MMS

For MMS messages, the structure of the send request differs, in order to accommodate different types of media.

Note that we're still using the Telnyx::Message object, but specifying an additional parameter. The Telnyx API knows to send an MMS message when media_urls is specified.

Send a message with an image URL:

Copy

Copied

require "telnyx"

Telnyx.api_key = "YOUR_API_KEY"

from_number = "YOUR_TELNYX_NUMBER"
to_number = "DESTINATION_NUMBER"

response = Telnyx::Message.create(
    from: from_number,
    to: to_number,
    subject: "Picture",
    text: "Hello, world!",
    media_urls: ["https://picsum.photos/500.jpg"]
)

Copy

Copied

the message being sent as an MMS without any media content – the message
will still contain a subject and/or text content.

Replace from_number with your Telnyx number. Be sure to remove any delimiters like dashes or spaces.
Replace to_number with the number you want to send a message to. Make sure you’re using the full +E.164 formatted number. In the US and Canada, this typically means adding +1 to the beginning of your 10-digit phone number.
Customize the text message and save the changes to send.rb .
Run the script.

Copy

Copied

ruby send.rb

That's it! Congrats on sending your first message with your Telnyx Account.

Next, learn how to receive messages.