PROGRAMMABLE SMS

Serverless Communications API

Integrate intelligent SMS, MMS, group, and batch messaging into your application.

Blindfolded Typing Competition | 1940s

Introduction

Designed for developers

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 (10DLC), short code, and toll-free SMS, MMS, group, and batch messages, setup auto-response, read logs, and manage phone numbers.

Stuff you can build

  • Appointment Reminders
  • Automated Alerts
  • Batch Notifications
  • Auto-Response
  • Contact Center Messaging
  • Long Code SMS Masking
  • Two-Factor Authentication
  • Group Messaging
  • Picture, Audio, and Video Messages

How It Works

Voxology’s Programmable SMS consists of two related services, a REST API and Callback-Response Loop:

REST API

Overview

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.

Example Request // Send SMS Message
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!"
      }
    }'

Callbacks

Overview

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.

Example Callback Request // Receive Inbound SMS
{
  "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.

Example Callback Response // Send Outbound SMS Response
{
  "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."
      }
    }
  ]
}

Supported Actions For Messaging

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.

Basic Actions

  • DIAL // Initiate an outbound call
  • PAUSE // Wait to process more actions
  • SESSIONDATA // Insert session_data into the message
  • SMS // Send a text message
  • WEBHOOK // Trigger a webhook to a designated URL

Control Flow Actions

  • FOREACH // Loop through an array or object
  • IF // Basic if-then-else conditional
  • GOTO // Jump to designated LABEL
  • LABEL // Target of GOTO

Variable Support

  • Native Constants // Many constants (like direction, number location, etc.) are assigned as variables and available to build your flow around
  • User Defined Variables // define your own variables and write them to each message via session_data

Getting Started

Get started with the basics of Voxology's Programmable SMS API.

Receive Messages

Overview

This tutorial is a step-by-step guide to setting up an SMS enabled number which receives a text message.

Prerequisites

  • Create an Account // Sign up for a Voxology Portal Account
  • Make a Payment // After you sign up, Make a Payment to start sending and receiving SMS messages
  • Get Your API key // Finally, go to your Applications and click Select to view your application’s details and get your unique API key
  • ‘Provision Phone Number’ Tutorial // Make sure you have completed the Provision Phone Number tutorial.

Tutorial

1. Provision a Phone Number

To receive an inbound text message, you need to search for an available phone number, provision it, and assign it to CallFlows, using either the Portal or our API. If you have not already provisioned a phone number, please see our Provision Phone Number tutorial.

2. Define Your Phone Number’s HTTP Callback Configuration

To quickly test inbound SMS, temporarily set your phone number’s callback configuration URL to the Webhook.site service following the steps below in the Portal. NOTE: You can also set your callback configuration using the API.

A. Go to Webhook.site.

B. 'Copy' the "Your unique URL" value.

C. Go to Manage Inbound Phone Numbers page in the Portal and select the number you provisioned.

D. Click on the Callback Configuration tab.

E. Click the Inherit Default Callback Configuration from Application toggle and then click the Designated a Callback URL to where Voxology will send Callback Requests toggle to display the Callback Configuration form.

F. 'Paste' “Your unique URL” value (from Webhook.site) into the Callback URL field.

G. Set the Callback Method field to GET.

H. Click Save.

3. Text Your Number

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 Webhook.site page and see HTTP callback request containing the text message.

Congratulations! You are now ready to send a text message from the number that you just programmed.

NOTE: You can now update the Callback URL to point to your own server where you could choose to display the message in a UI you’re building, or automatically respond.


Send Messages

Overview

This tutorial is a step-by-step guide for sending an SMS using the REST API.

Prerequisites

  • 'Receive Messages' Tutorial // Make sure that you have completed the Receive Messages tutorial.

Tutorial

1. Prepare your Request

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!"
    }'

2. Send an SMS

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.


Auto-Response

Overview

This tutorial is a step-by-step guide to creating a multi-action SMS auto response system using Programmable Messaging.

Prerequisites

  • 'Receive Messages' Tutorial // Make sure that you have completed the Receive Messages tutorial.

Tutorial

1. Define Your Phone Number’s HTTP Callback Configuration

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 Callback Configuration of your Voxology Phone Number using either the Portal or our API.

2. Text Your Number

Once you’ve configured your number, send a text message with one of the keywords:

  • START, YES, SUBSCRIBE
  • STOP, NO, UNSUBSCRIBE
  • HELP, INFO

You should receive a text message back with the corresponding response.

Congratulations! Your Voxology phone number can now return 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.