Integrate intelligent SMS, MMS, group, and batch messaging into your application.
Blindfolded Typing Competition | 1940s
Voxology’s Programmable SMS gives developers the keys to one of the industry’s largest and most reliable cloud communications platforms in a powerful API. The service allows you to programmatically send and receive, long code, short code, and toll-free SMS, MMS, group, and batch messages, read logs, and manage phone numbers.
The Voxology REST API enables you to send individual, batch, and group SMS and MMS (picture, audio, video) messages. It also allows you to fetch logs, manage your account, applications, phone numbers, and callback configurations.
You can view a full list of Voxology’s REST API Methods on the API Reference.
curl -X POST \
https://api.voxolo.gy/v1/Messages \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Cache-Control: no-cache' \
-d '{
"api_no": "+19495551212",
"caller_no": "+17145551212",
"text_message": "Hello, World!"
}
}'Voxology delivers inbound SMS and MMS messages via an http callback request. When a message is sent to an SMS enabled Voxology phone number, Voxology will send a callback request containing the text message and any media to the URL that you designate in the callback config. Unlike Programmable Voice, Voxology does not expect to receive a response to Programmable Messaging callbacks of “type”: “sms” and “type”: “mms”, however you can respond to messaging callback requests with a subset of Voxology Call Flow Actions.
{
"service": "programmable_messaging",
"type": "sms",
"app_id": "aaaa-bbbb-cccc-dddd-eeee",
"subaccount_id": 0,
"api_no": "+19495551212",
"caller_no": "+17145551212",
"api_no_region": "FL",
"api_no_country": "US",
"api_no_timezone": "America/New_York",
"api_no_postal_code": "33444",
"api_no_city": "Delray Beach",
"api_no_latitude": "26.46081644913084",
"api_no_longitude": "-80.07187504809512",
"api_no_lata": "460",
"api_no_rate_center": "DELRAY BEACH",
"caller_no_region": "FL",
"caller_no_country": "US",
"caller_no_timezone": "America/New_York",
"caller_no_postal_code": "33444",
"caller_no_city": "Delray Beach",
"caller_no_latitude": "26.46081644913084",
"caller_no_longitude": "-80.07187504809512",
"caller_no_lata": "460",
"caller_no_rate_center": "DELRAY BEACH",
"direction": "inbound",
"message_id": "SMI:2d784af7-1410-41bd-9e89-f978082506c3",
"external_group_id": null,
"external_id": null,
"created_on": "2019-03-04T18:12:18.914Z",
"num_parts": null,
"uri": "/v1/Messages/SMI:2d784af7-1410-41bd-9e89-f978082506c3",
"text_message": "Hello world to you.",
"status": "received",
"error": null,
"error_code": null
}If you choose to respond to SMS/MMS-related callback requests, you can either respond dynamically, or you can setup a "serverless" auto-response by pointing the sms callback requests to a static JSON file.
{
"actions": [
{
"type": "SMS",
"params": {
"no": "+17145551212",
"caller_id_no": "+19495551212",
"message": "Thanks for your message. We'll get back with you as soon as possible."
}
}
]
}Voxology’s Actions are a set of instructions that you use to build your automated responses. You can combine them in all kinds of ways to create an experience for your customers.
session_data into the messageLABELGOTOsession_dataOverview
This tutorial is a step-by-step guide to setting up an SMS enabled number which receives a text message.
To receive an inbound phone call, you need to search for an available phone number, provision it, and assign it to CallFlows, using either the Portal or our REST API (instructions below).
To search for an available phone number, go to List Inbound Available Phone Numbers and prepare your query request. For SMS enabled numbers, make sure to set capabilities=sms (see example below)
curl -X GET \
'https://api.voxolo.gy/v1/PhoneNumbers/Available?capabilities=voice,sms&search_by=prefixes&search_on=INSERT_YOUR_AREA_CODE' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: YOUR_API_KEY'Once you have made your GET request, select a phone number from the list of results and 'copy' it. To provision the number, go to Provision Phone Numbers, ‘paste’ the number into your request body and assign it to CallFlows (see example below).
curl -X POST \
https://api.voxolo.gy/v1/PhoneNumbers/CallFlows \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'x-api-key: YOUR_API_KEY' \
-d '{
"phone_numbers": [
{
"no": "PASTE_YOUR_VOXOLOGY_NUMBER_HERE"
}
]
}'Now that you have provisioned your new SMS enabled phone number, it is time to configure the callback settings.
To quickly test inbound SMS, set your callback configuration URL to the Webhook.site service following these steps:
curl -X PUT \
'https://api.voxolo.gy/v1/CallFlows/Configurations/PhoneNumbers/PASTE_YOUR_VOXOLOGY_NUMBER_HERE_URL_ENCODED' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'x-api-key: YOUR_API_KEY' \
-d '{
"callback": {
"method": "GET",
"url": "YOUR_UNIQUE_URL",
"content_type": "application/json"
}
}'Now you can text “Hello, World!” to the new phone number that you configured. If all went well, you should be able to refresh your RequestBin page and see the text message.
Congratulations! You are now ready to send a text message from the number that you just programmed.
This tutorial is a step-by-step guide for generating an SMS to a call phone number using the REST API.
To send a text message from the number that you programmed above, you will use the Send SMS method and copy/paste the following body:
curl --X POST \
https://api.voxolo.gy/v1/Messages \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Cache-Control: no-cache' \
-d '{
"api_no": "PASTE_YOUR_VOXOLOGY_NUMBER_HERE",
"caller_no": "TO_NUMBER",
"text_message": "Hello, World!"
}'Once you have prepared your request body, send it. If successful, you should receive the “Hello, World!” text message.
Congratulations! You can now send SMS messages from your Voxology phone numbers. Next, you can learn how to set up an auto-response for your Voxology Phone Numbers.
This tutorial is a step-by-step guide to creating a multi-action SMS auto response system using Programmable Messaging.
To enable auto response messaging from your number, you need to tell Voxology where to fetch your instructions. When a text comes in, we will make a request to your server or CDN and expect you to tell us what to do next using our list of Call Flow Actions.
For your convenience, we posted a sample JSON call flow script using our Actions and Variables at the following URL: https://s3-us-west-2.amazonaws.com/com.voxology.actions/docs/Example-SMSAutoResponse.json (contents below).
{
"actions": [
{
"$subscribeList": "['START', 'YES', 'SUBSCRIBE'].join()",
"$unsubscribeList": "['STOP', 'NO', 'UNSUBSCRIBE'].join()",
"$helpList": "['HELP', 'INFO'].join()"
},
{
"$formattedMessage": "$textMessage.toUpperCase()"
},
{
"type": "IF",
"condition": "$subscribeList.indexOf($formattedMessage) !== -1",
"then": [
{
"type": "SESSIONDATA",
"session_data": {
"response": "You have opted in."
}
},
{
"type": "GOTO",
"params": {
"label": "sendMessage"
}
}
]
},
{
"type": "IF",
"condition": "$unsubscribeList.indexOf($formattedMessage) !== -1",
"then": [
{
"type": "SESSIONDATA",
"session_data": {
"response": "You have opted out."
}
},
{
"type": "GOTO",
"params": {
"label": "sendMessage"
}
}
]
},
{
"type": "IF",
"condition": "$helpList.indexOf($formattedMessage) !== -1",
"then": [
{
"type": "SESSIONDATA",
"session_data": {
"response": "This is a helpful message."
}
},
{
"type": "GOTO",
"params": {
"label": "sendMessage"
}
}
]
},
{
"type": "SESSIONDATA",
"session_data": {
"response": "You've sent an invalid response."
}
},
{
"type": "LABEL",
"name": "sendMessage"
},
{
"type": "SMS",
"params": {
"message": "${sessionData.response}"
}
}
]
}To configure the SMS callback, ‘copy’ the call flow script URL above and 'paste' it into the SMS/MMS Callback Configuration of your Voxology Phone Number using either the Portal or our REST API (instructions below).
If you want to use the API, you can prepare your request (see example request below).
curl -X PUT \
'https://api.voxolo.gy/v1/CallFlows/Configurations/PhoneNumbers/PASTE_YOUR_NUMBER_HERE_URL_ENCODED' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'x-api-key: YOUR_API_KEY' \
-d '{
"callback_sms": {
"method": "GET",
"url": "https://s3-us-west-2.amazonaws.com/com.voxology.actions/docs/Example-SMSAutoResponse.json",
"content_type": "application/json"
}
}'Once you’ve configured your number, send a text message with one of the keywords:
START, YES, SUBSCRIBE STOP, NO, UNSUBSCRIBEHELP, INFOYou should receive a text message back with the corresponding response.
Congratulations! Your Voxology phone number can now send automated response messages. Next, you can point your number to a URL on your own server or CDN and start building intelligent SMS auto-responses into your application.