Sending a Message on the Telnyx Platform' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
In this tutorial, you’ll learn how to send SMS and MMS messages using the Telnyx
v2 API and the curl command.
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' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
Follow the steps below to send SMS and MMS messages.
- 1Using the SMS or MMS examples below, write a
curl
command that will submit an outbound message request. Include your API Key in theAuthorization
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 awebhook_url
orwebhook_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
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
andfrom
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
andwebhook_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"
]
}'
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.
- 2Replace the
from
number with your Telnyx number. Be sure to remove any delimiters like dashes or spaces. - 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. - 4Run the updated command.
In a few moments you’ll receive a message at your number on your device. Congrats, you’ve just sent your first SMS or MMS.
Next, learn how to receive messages with Telnyx.