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

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

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 sending an alphanumeric message, make sure to specify the messaging_profile_id parameter in the body of the request.

Send SMS

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

Copy Code

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

Copy Code

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.

Send a message with an image URL:

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 Code

Notes:

• The from number here must be MMS enabled.
• Passing an empty array to the media_urls parameter will result in the message being sent as an MMS without any media content – the message will still contain a subject and/or text content.
• Media URLs must be publicly accessible.

1. 2Replace the from number with your Telnyx number. Be sure to remove any delimiters like dashes or spaces.
2. 3Replace 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.
3. 4Run the updated command.

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

Next, learn how to receive messages.