Voxeo Documentation - SMS HTTP POST Interface API

The Voxeo SMS HTTP POST Interface is an API that allows you to send and receive text messages using HTTP POST or HTTP GET request methods. You use the HTTP POST request method to send data to the Voxeo server as part of the URL request itself. This is in contrast to the GET request method where only a URL and headers are sent to the server. The SMS HTTP POST Interface API is specifically designed to parse the data for a text message from the URL.

Note: Your Evolution Developer Portal account must have outbound SMS privileges enabled before you can send outbound SMS messages. For more information, contact Voxeo Support.

Authentication

To access the SMS HTTP POST Interface API at Voxeo, you must use your Evolution Developer Portal account log in credentials. If you need to create a free Voxeo Evolution Developer Portal account, see How to: Register or contact Voxeo Support.

Authentication is managed by using basic HTTP authentication. Each request must include an Authorization HTTP header with your Evolution Developer Portal account username and password. For example, if you use PHP code with the cURL library, you could add your authorization using the following code:

// Enter your application SMS Botkey and SMS-enabled telephone number from the Evolution Contact Methods tab

$botkey='[999999]';

$from="14075551212";

$userKey = $_REQUEST['userkey'];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'http://api.messaging.staging.voxeo.net/1.0/messaging');

curl_setopt($ch, CURLOPT_HEADER, 0);

$data="botkey=".$botkey."&apimethod=send&msg=".$msg."&userkey=".$userKey."&network=SMS&from=".$from;

curl_setopt($ch, CURLOPT_USERPWD, '[Evolution User Name]:[Evolution Password]');

curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

curl_setopt($ch, CURLOPT_TIMEOUT, 100);

If you specify a URL as an HTTP GET request with text messaging data sent directly from a web browser to the SMS HTTP POST Interface API, an authentication dialog box is displayed and you must enter your authorization credentials.

Outbound Text Messages

To send an outbound text message using the SMS HTTP POST Interface API, you will need to submit parameters using an HTTP POST to:

http://api.messaging.staging.voxeo.net/1.0/messaging

With Voxeo-provided SMS-enabled telephone numbers, the carrier limitation for sending text messages is set at a maximum of 60 text messages per minute. This limitation is for both Staging testing and Production text messaging. If you need to send more than 60 text messages per minute, you will have to purchase a short code. For more information about ordering a short code, see How to: Get a Short Code or contact Voxeo Support.

An outbound text message HTTP POST is a combination of the http://api.messaging.staging.voxeo.net/1.0/messaging URL and the parameters described in the following table.

Outbound Parameters

Parameters

Description

botkey

Your Evolution Developer Portal application SMS Botkey displayed on the Contact Methods tab. This parameter is required.

apimethod

Set to send. This parameter is required.

userkey

A GUID text message identifier generated by the SMS HTTP POST API response comprised of a hash of the application botkey, network (SMS), user, and to (inbound telephone number, same as from for outbound) parameters. The userkey will not exceed 50 characters. This parameter is optional if both the user and network parameters are individually passed an HTTP POST request.

msg

The message to send. You must URL encode special characters, for example, a space is %2B. Text messages greater than 160 characters after decoding are sent as multiple messages. This parameter is required.

user

The receiving telephone number to send the text message to. This parameter is required unless the userkey parameter is passed.

channel

Not used for text messaging.

network

Set to SMS. This parameter is required unless the userkey parameter is passed.

from

The sending telephone number or short code used to send a text message. This parameter is optional.

The following URL's are examples of an outbound text message HTTP GET request.

http://api.messaging.staging.voxeo.net/1.0/messaging?botkey=12345&apimethod=send&msg=My%20test%20message.&user=14075555555&network=SMS&from=14076666666

and

http://api.messaging.staging.voxeo.net/1.0/messaging?botkey=12345&apimethod=send&msg=My%20test%20message.&userkey=b649228afa9597a156527032d8be45eb

The following code example is a cURL HTTP POST request for the preceding example.

curl -u MyUserName:MyPassword "http://api.messaging.staging.voxeo.net/1.0/messaging" -X POST -d "botkey=12345&apimethod=send&msg=My%20test%20message.&user=14075555555&network=SMS&from=14076666666"

and

curl -u MyUserName:MyPassword "http://api.messaging.staging.voxeo.net/1.0/messaging" -X POST -d "botkey=12345&apimethod=send&msg=My%20test%20message.&userkey=b649228afa9597a156527032d8be45eb"

Response from an Outbound Text Message

An XML response is generated by the SMS HTTP POST Interface API for each outbound text message. The response will either be a successful or error message. The following examples show the SMS HTTP POST Interface API responses for a successful and unsuccessful text message.

Successful request:

<rsp stat="ok">

<success msg="accepted" transactionid="2e47fe224d25559a696a7bdddec1828b" messageid="cf0d21f067e5b386a2e042134687eb5c"/>

</rsp>

Unsuccessful request:

<rsp stat="fail">

<err msg="error message txt"/>

</rsp>

Inbound Text Messages

The following section describes how an incoming text message should be sent to your application URL and the API response. The URL is the application Messaging URL on the Application Settings for your application in the Evolution Developer Portal. Incoming text messages are sent to the application URL as an HTTP POST with the POST parameters form encoded.

The inbound text message HTTP POST is a combination of the application URL and the parameters described in the following table.

Inbound Parameters

Parameters

Description

botkey

Your Evolution Developer Portal application SMS Botkey displayed on the Contact Methods tab. This parameter is required.

userkey

A GUID text message identifier generated by the SMS HTTP POST API response comprised of a hash of the application botkey, network (SMS), user, and to (inbound telephone number, same as from for outbound) parameters. The userkey will not exceed 50 characters. This parameter is optional if both the user and network parameters are individually passed an HTTP POST request.

network

For inbound text messages, set to SMS.

user

The telephone number that sent the text message.

to

The telephone number or short code that the text message was sent to.

channel

Not used for text messaging.

step

A numeric value that represents the inbound text message step for the user. The first inbound text message is Step 1. If the next inbound message from the same user occurs within five minutes, the step value is incremented by one. The maximum number of steps per user session is 50 and is then reset to Step 1.

value

The values, value1 to valueX, sent from the user for each step.

msg

The message was sent.

The following code is an example of an inbound text message.

to=14075551234&value3=Thanks&msg=Yes&value1=Hello&botkey=999888&network=SMS&value2=Perfect&value0=Finished &userkey=8711267db36972eef3f37f1bb043c142&user=14075559090&channel=public&step=4

In the preceding example, there are a total of four steps with four values, value0 - value3.

Inbound Response Handling

You can respond to an inbound text message by returning text in the body of the response. In addition, you can add helper tags in the response. Helper tags interact with the SMS HTTP POST Interface API to handle user step and value parameter settings when required. By default, a caller session ends after five minutes of inactivity. The same caller will have to wait for five minutes to begin a new session using reset step and value settings. By using helper tags, you could, for example, reset the parameter values automatically when a caller successfully completes the text messaging transaction. For example, when a caller sends a valid zip code to retrieve a weather forecast, you could reset the step and value parameters to allow the same caller to retrieve a weather forecast for different zip code.

Helper tags are useful for error handling. If a caller response does not match or is invalid, you can use the error or goto step helper tags to return the caller to the same step again. The following table describes the SMS HTTP POST Interface API helper tags.

Tag

Description

error

Reduces the step value by one. For example, if a user on Step 1 sends a name and you were expecting a number, you can respond with You must enter a number!<error>. The values saved in Step 1 - 3 are still saved, and the step value is reset to Step 3. When the user responds, the step value will again be set to Step 4.

goto = step

Resets step value to the specified step. For example, <goto=3> would reset the step parameter to 3.

reset

Resets step value to 1 and clears all step values for the session.

The following PHP code example shows how you can use helper tags.

if ($_REQUEST['msg']) != "No"

{

$msg = "Thanks for your reply!;

send_response($msg) .  ".<reset>"; 

}

else

{

$msg = "Sorry to bother you.";

send_response($msg) .  ".<error>";    // Or use ".<goto=1>"; to keep the step values and return to Step 1

}

Next Steps

You can use the SMS HTTP POST Interface API and your own text messaging application to create interactive inbound text messaging sessions. Your application requires an SMS Botkey and a SMS-enabled telephone number, provided to you free of charge when you create an Evolution Developer Portal application mapping. After you create an application mapping, you can specify the URL of your application to handle inbound text messages. For more information see How to: Create an Application Mapping for Text Messaging.

You can also use your application mapping to send a basic outbound text message. For outbound text messaging, you can form a URL in any web browser and send a message without a text messaging application. For more information, see How to: Send an Outbound Text Message.

See Also

Text Messaging Overview

How to: Create an Application Mapping for Text Messaging

How to: Send an Outbound Text Message

How to: Reply to an Inbound Text Message

About Production Text Messaging

How to: Get a Short Code

Voxeo Support

 
Voxeo Corporation is a technology company that specializes in providing development platforms for unified customer experience as self-service and unified communications using real-time communications applications. Voxeo's products are also available as a SaaS platform as cloud-based services using on-premise software in a private cloud, or hybrid clouds that combine both on-demand public-cloud and on-premise components. For more information, see Voxeo.com and Triplecloud.com.

 
The Voxeo SMS HTTP POST Interface is an API on Voxeo Prophecy Hosting that allows you to send and receive text messages using an HTTP POST method. You can use the HTTP POST request method to send data to the Voxeo API server as part of the URL request itself. This is in contrast to the GET request method where only a URL and headers are sent to the server. The SMS HTTP POST Interface API is specifically designed to parse the data for a text message from the URL. For more information, see the SMS HTTP POST Interface API Guide.
 

The programming interface used by an application to access services and communicate with other systems. The acronym for application programming interface is API.

 
Text messaging, or SMS, is the text communication service component of telephone, web or mobile communication systems, that uses standardized communications protocols to exchange of text messages between fixed or mobile telephone devices.
 
Hyper Text Transfer Protocol is a computer-to-computer communications standard and is the basis for all communication on the World Wide Web. The acronym for Hyper Text Transfer Protocol is HTTP. HTTP is used whenever a URL such as http://www.voxeo.com is processed.
 
A request method supported by the HTTP protocol used on the World Wide Web. A POST request method is used when the client needs to send data to the server as part of the request, such as when uploading a file or submitting a completed form. A POST request submits data contained in the message body to the specified resource. In contrast, a GET request method is a URL and headers sent to the server without a message body. A GET requests a representation of a specified resource and is used only to retrieve data.
 
A request method supported by the HTTP protocol used on the World Wide Web. A GET request method is a URL and headers sent to the server without a message body. A GET requests a representation of a specified resource and is used only to retrieve data.

In contrast, a POST request method is used when the client needs to send data to the server as part of the request, such as when uploading a file or submitting a completed form. A POST request submits data contained in the message body to the specified resource.

 

(Uniform Resource Locator)

 
A request method supported by the HTTP protocol used on the World Wide Web. A GET request method is a URL and headers sent to the server without a message body. A GET requests a representation of a specified resource and is used only to retrieve data.

In contrast, a POST request method is used when the client needs to send data to the server as part of the request, such as when uploading a file or submitting a completed form. A POST request submits data contained in the message body to the specified resource.

 

The free Voxeo customer and developer web portal located at https://evolution.voxeo.com that provides tutorials, application development tools, developer forums, and access to our free 24-hour, around-the-clock, Customer Obsession Support Team.

 

PHP is a server-side scripting and programming language. PHP is used for web page development for dynamic web pages that can be easily embedded into HTML.

 

(Client URL Request Library)

 

Short message service, or text messaging, is the text communication service component of telephone, web or mobile communication systems, that uses standardized communications protocols to exchange of text messages between fixed or mobile telephone devices. The acronym for short message service is SMS.

 
The Voxeo Staging environment on Prophecy Hosting provides IVR platforms that you can use to test and review your applications at no cost during development. The Staging environment is shared to all developers and provides limited server resources that can have performance issues. When your application is ready for live use, you must contact Voxeo Support to move your application to the Production environment.
 
The Voxeo Production environment provides IVR platforms for live use. When your application is ready for live use, you must contact Voxeo Support to move your application from Staging to the Production environment. To contact Voxeo Support to move an application to Production, visit Voxeo Support Guide Overview.
 
A short code is a 5 or 6 digit text messaging telephone number, for example, 54321, used as an inter-carrier connection for your text messaging application. Carriers limit the maximum number of text messages that can be sent from an SMS-enabled telephone number, usually 25 to 60 messages per minute, unless a short code is used.
 

A globally unique identifier is a 32-character hexadecimal string used as a reference number to identify a specific object. The acronym for globally unique identifier is GUID, pronounced GOO-id.

 

A globally unique identifier is a 32-character hexadecimal string used as a reference number to identify a specific object. The acronym for globally unique identifier is GUID, pronounced GOO-id.

Voxeo Documentation

     Voxeo Documentation Overview
  Evolution Developer Portal
     Introduction to the Evolution Developer Portal
  Evolution Developer Portal Guide
  Prophecy Platforms & Languages
  Prophecy Migration
  Voxeo Designer Guide
  SMS HTTP POST Interface API Guide
     Text Messaging Overview
     How to: Create an Application Mapping for Text Messaging
     How to: Send an Outbound Text Message
     How to: Reply to an Inbound Text Message
     About Production Text Messaging
     How to: Get a Short Code
     SMS HTTP POST Interface API
  PCI Compliance
  Location-Based Services
  Voxeo CXP
  Prophecy
  Development Languages
  Voxeo Support
     Support Quick Reference
  Registering for an Account
  Self-Help Tools
  Collecting Information
  Evolution Ticketing System
     Submitting a Support Request
     Escalating a Support Request
  Software Lifecycle and Support Policies
  Getting Further Assistance
  Voxeo Glossary
  Help on Help