Developers
Sign in
Create an AccountSign inQuestions on setup? Talk to our experts

  • Choose:

Sending a Message on the Telnyx Platform

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 for $10 of free credit!

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.

  1. 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.

Notes:

  • Don’t forget to update YOUR_API_KEY in the below commands.
  • Make sure that the source (from) is eligible to send messages towards the destination (to) phone number. Read more about this here.
  • If you are sending a message internationally from an A2P enabled longcode, we will automatically fail over to alphanumeric routes using a generic Sender ID.
  • If sending an alphanumeric message, make sure to specify the messaging_profile_id parameter in the body of the request.

Send SMS

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

{
  "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": []
  }
}

Notes:

  • Make sure you’re using the full +E.164 formatted number for your to and from numbers. In the US and Canada, this typically means adding +1 to the beginning of your 10-digit phone number.
  • The webhook URLs for this message are taken from the messaging profile. If you want to override them, use the webhook_url and webhook_failover_url request fields.

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:

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)
  }
);

  1. Replace the from number with the number you purchased above.

  2. 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.

  3. Customize the text message and save changes to send.js.

  4. Finally, back in your terminal run:

node send.js

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

Next, learn how to receive messages.

Was this page helpful?