PROGRAMMABLE SMS

Intelligent Communications API

Build intelligent SMS 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 both long code and short code SMS messages, read logs, and manage phone numbers.

Stuff you can build

  • Appointment Reminders
  • Automated Alerts
  • Contact Center Messaging
  • Long Code SMS Masking
  • Two-Factor Authentication

How It Works

Voxology’s Programmable SMS consists of two related services, a REST API and Callbacks:

REST API

Overview

The Voxology REST API enables you to send SMS messages and read logs. It also allows you to 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’s Callbacks allow you to receive inbound SMS messages. When a message is sent to an SMS enabled Voxology phone number, Voxology will send a callback containing the text message to the URL that you designate. Unlike Programmable Voice, Voxology does not expect to receive a response to Programmable Messaging callbacks of “type”: “sms”.

Example Request // SMS Received
{
  "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
}

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 an API key // Finally, go to your Applications and click ‘SELECT’ to view your application’s details and get your unique API key
  • Base URL // All REST requests referenced in this documentation have the following base URL: https://api.voxolo.gy/v1

Tutorial

1. Provision a Phone Number

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.

2. Configure Your Call Flow Callback

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

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 RequestBin page and see the text message.

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

Send Messages

Overview

This tutorial is a step-by-step guide for generating an SMS to a call phone number 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 point your number to a URL on your own server and start building intelligent SMS messaging into your application.