27 September, Wednesday
SMS Gateway: API for SMS,Voice,TTS
SMS Gateway
Reach any phone worldwide using our simple online SMS gateway platform.
Matrix SMS Gateway for group messaging provides your business a hosted messaging platform to add SMS capability to any system, application or website.We deliver the direct capability to send SMS, Voice and Text-to-Speech messages from any application.
How our SMS Gateway can help you:
- Our gateway delivers SMS, Voice and Text-to-Speech to more than 200 countries worldwide.
- Integration with various front-end and legacy systems is achieved
via a set of simple and easy to use APIs (Application Programming Interface) interfaces.
Our APIs offer you a choice of connection options (HTTP, HTTPS, SMTP) that are flexible and easy to implement and that will fit to pretty much any kind of usage. - Very easy to access and user-friendly web based GUI provides users with functionality to do reporting, make online payments, add sub-users and more.
- On top of the SMS delivery, Matrix gateway also provides Voice and
Text-to-Speech messaging functionality.
Your application will be able to communicate with the outside world using all media known to humanity, and through one, consistent API. - Source code scripts that show how to use gateway's API are available from our website, and they
cover several most popular programming languages.
API specification documentation is also available. - Take a look at the complete list of SMS Matrix API functions.
- Text messages in unicode (utf-8) are supported, as long as wireless carrier
and phone receiver support given language.
When unicode is used, most of Asian languages are supported, including Chinese. - Technical Support for the SMS Gateway is available at this email address: support@smsmatrix.com
So far, access to Matrix SMS Gateway has been successfully implemented and tested with the following programming languages:
Node.js, JavaScript, PHP, Perl, Java, C#, Python, C, C++, VB, .Net, etc..
If in doubt, please refer to Perl examples, as they are the most complete and were the most thoroughly tested.
The following Gateway API functions are provided:
- Send SMS message
- Send TTS (Text-to-Speech) message
- Send Voice message (with voice file data)
- Send Voice message (with voice file url)
- Query message's status
- Lookup cellular carrier for given cell phone number
- Query account's balance
- Query message rate (fee)
- SMTP gateway for SMS/VOICE/TTS delivery
SMTP/Email Gateway functionality:
- Send SMS message
- Send TTS (Text-to-Speech) message
- Send Voice message (with voice file url)
PDF Version - Matrix SMS Gateway Developer's GuideSeptember 2014 update:
We have a new JSON based API under development.
Existing API described below will be still supported, however all new developers are encouraged to use new JSON based one.
SMS Gateway API - JSON
Technical Information:
- Each message sent through our system will have unique ID assigned.
- This ID is returned to the caller when new message is submitted, and later, a query can be submitted with this ID to check on the status of this message.
- Unicode message format for non-English languages is supported for SMS delivery.
- Text-to-Speech - list of supported languages available at the end of this page.
- Both: HTTP and HTTPS protocols are supported for all communication with SMS Matrix servers.
Capturing Recipient's Response
It is possible to send voice or text-to-speech message, that would ask the recipient to make a choice by pressing a number on the dial.For instance, a dentist would like to send a message - appointment reminder:
"Hello, this is dentist Adam Smith. Press 1 to confirm your appointment tomorrow at 9am,
or press 2 to cancel the appointment.
Press 9 to repeat this message."
Or a car serviceman wants to ask if his customers are happy:
"Hello, this is your Citroen Service in Cleveland.
You visited us last week. We would like to know if were happy with the service we provided.
Press 1 if you were happy, or press 2 if you were not.
Press 9 to repeat this message."
The recipient would listen to the message, and then press 1, or 2, or 9.
The number pressed, will later show up in the message status, so it will be easy for the sender to see recipient's response.
If 'response' field is set to 1, the system will deliver voice or TTS message, and it will wait and capture recipient's response.
If 'response' field is not set, no response will be expected nor captured.
'9' is always reserved for the 'repeat this message', so do not use it for other purposes.
When sender checks the status of the message in the 'History', the status of the message will include the information what key (digit) was pressed by the recipient.
Example of the message status:
"Voice call answered, duration 18 seconds. R = 1"
It means that recipient pressed '1' in a response to the message (e.g. appointment was confirmed).
Examples of the usage of SMS Gateway API, in several programming languages:
SMS Gateway - Send SMS - HTTP Post : Perl Example
##################################################
## Example of using SMS Matrix HTTP API in Perl
use LWP::UserAgent;
use HTTP::Request::Common;
my $TXT = 'This is a test, pls ignore';
my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
POST 'http://www.smsmatrix.com/matrix',
Content_Type => 'application/x-www-form-urlencoded',
Content => [ 'username' => 'user888@yahoo.ca',
'password' => 'pass7782',
'callerid' => '12501231233', # optional (for 2-way sms)
'phone' => '12506063167',
'tts' => 1, # optional for TTS fallback
'txt' => $TXT ]
);
if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response: " . $res->content . "\n\n";
SMS Gateway - Send SMS to a group: Perl Example
use LWP::UserAgent;
use HTTP::Request::Common;
my $TXT = 'This is a test, pls ignore';
my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
POST 'http://www.smsmatrix.com/matrix',
Content_Type => 'application/x-www-form-urlencoded',
Content => [ 'username' => 'user888@yahoo.ca',
'password' => 'pass7782',
'callerid' => '12501231233', # optional (for 2-way sms)
'group' => 'Test_Group',
'txt' => $TXT ]
);
if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response: " . $res->content . "\n\n";
SMS Gateway - Check Message Status (HTTP) : Perl Example
use LWP::UserAgent;
use HTTP::Request::Common;
my $URL = 'http://www.smsmatrix.com/matrix_status';
my $USERNAME = 'user@hotmail.com';
my $PASSWORD = 'pass72727';
my $MSGID = 'a876f1267536589be789effa879';
my $q = "username=$USERNAME&password=$PASSWORD&id=$MSGID";
my $ua = new LWP::UserAgent;
my $req = new HTTP::Request 'POST', $URL;
$req->content_type ('application/x-www-form-urlencoded');
$req->content ($q);
my $res = $ua->request ($req);
if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response: " . $res->content . "\n\n";
SMS Gateway - Send Text-To-Speech message: Perl Example
use LWP::UserAgent;
use HTTP::Request::Common;
my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
POST 'http://www.smsmatrix.com/matrix_tts',
Content_Type => 'application/x-www-form-urlencoded',
Content => [ 'username' => 'user@hotmail.com',
'password' => 'password',
'phone' => '12506063167',
'repeat' => 1, ## Optional (default is 0)
'gender' => 'male', ## Optional, 'female' is default
'language' => 'us', ## Optional ('us' is default, see list of languages at the end of this page)
'response' => 0, ## Optional, set to 1 if recipient's response needed
'txt' => 'Adam, web server is down' ]
);
if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response: " . $res->content . "\n\n";
SMS Gateway - Send Text-To-Speech message in non-ASCI language: Perl Example
use LWP::UserAgent;
use HTTP::Request::Common;
my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
POST 'http://www.smsmatrix.com/matrix_tts',
Content_Type => 'application/x-www-form-urlencoded',
Content => [ 'username' => 'user@hotmail.com',
'password' => 'password',
'phone' => '12506063167',
'repeat' => 1, ## Optional (default is 0)
'gender' => 'male', ## Optional, 'female' is default
'language' => 'ch', ## Mandarin
'response' => 0, ## Optional, set to 1 if recipient's response needed
'txt' => '濞变箰鏃跺皻銆佷骇涓氳祫璁€佸疄' ]
);
if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response: " . $res->content . "\n\n";
SMS Gateway - Query Message Rate : Perl Example
use LWP::UserAgent;
use HTTP::Request::Common;
my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
POST 'http://www.smsmatrix.com/sms_rate',
Content_Type => 'application/x-www-form-urlencoded',
Content => [ 'phone' => '12506058145' ]
);
if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response: " . $res->content . "\n\n";
SMS Gateway - Send SMS - HTTP Post : PHP Example
<?php
$URL = 'http://www.smsmatrix.com/matrix';
$PHONE = '12506063167'; // comma separated list of phone numbers
// $PHONE = '12506063167,12508763211';
$USERNAME = urlencode ('user@hotmail.com');
$PASSWORD = urlencode ('pass72727');
$TXT = urlencode ('This is a test, pls ignore');
$Q = "$URL?username=$USERNAME&password=$PASSWORD&phone=$PHONE&txt=$TXT";
$res = implode ('', file ($Q));
echo "Matrix API Response :\n$res\n";
?>
SMS Gateway - Send SMS - HTTP Post : Java Example
try
{
String MATRIXURL = "http://www.smsmatrix.com/matrix";
String PHONE = "12506063167";
String USERNAME = "user@hotmail.com";
String PASSWORD = "pass72727";
String TXT = "This is a test, pls ignore";
String q = "username=" + URLEncoder.encode (USERNAME, "UTF-8");
q += "&" + "password=" + URLEncoder.encode (PASSWORD, "UTF-8");
q += "&" + "phone=" + PHONE;
q += "&" + "txt=" + URLEncoder.encode (TXT, "UTF-8");
URL url = new URL (MATRIXURL);
URLConnection conn = url.openConnection();
conn.setDoOutput (true);
OutputStreamWriter wr = new OutputStreamWriter (conn.getOutputStream());
wr.write (q);
wr.flush();
BufferedReader rd = new BufferedReader (new InputStreamReader (conn.getInputStream()));
String line;
System.out.println ("Matrix API Response :");
while ((line = rd.readLine()) != null) { System.out.println (line); }
wr.close();
rd.close();
} catch (Exception e) { }
SMS Gateway - Send SMS - HTTP Post : C# Example
string MATRIXURL = "http://www.smsmatrix.com/matrix";
string PHONE = "12506063167";
string USERNAME = Server.UrlEncode ("user@hotmail.com");
string PASSWORD = Server.UrlEncode ("pass72727");
string TXT = Server.UrlEncode ("This is a test, pls ignore");
string q = "username=" + USERNAME +
"&password=" + PASSWORD +
"&phone=" + PHONE +
"&txt=" + TXT;
HttpWebRequest req = (HttpWebRequest)WebRequest.Create (MATRIXURL);
req.Method = "POST";
req.ContentType = "application/x-www-form-urlencoded";
req.ContentLength = q.Length;
StreamWriter streamOut = new StreamWriter(req.GetRequestStream(), System.Text.Encoding.ASCII);
streamOut.Write (q);
streamOut.Close();
StreamReader streamIn = new StreamReader(req.GetResponse().GetResponseStream());
string res = streamIn.ReadToEnd();
Console.WriteLine ("Matrix API Response:\n" + res);
streamIn.Close();
SMS Gateway - Carrier Lookup : Perl Example
List of cellular carriers supported by Lookup function
use LWP::UserAgent;
use HTTP::Request::Common;
my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
POST 'http://www.smsmatrix.com/carrier',
Content_Type => 'application/x-www-form-urlencoded',
Content => [ 'username' => 'user@yahoo.ca',
'password' => 'password9999',
'phone' => '12506063167']
);
if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response: " . $res->content . "\n\n";
SMS Gateway - Get Account's Balance : Perl Example
use LWP::UserAgent;
use HTTP::Request::Common;
my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
POST 'http://www.smsmatrix.com/balance',
Content_Type => 'application/x-www-form-urlencoded',
Content => [ 'username' => 'user@yahoo.ca',
'password' => 'password' ]
);
if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response: " . $res->content . "\n\n";
SMTP gateway for SMS/TTS/VOICE delivery
For users (developers) that don't have a need or possibility to integrate their software with our SMS Gateway directly, SMS Matrix provides easy to use option: SMS, Voice and TTS message delivery via SMTP.
If text (not HTML) email is sent to gateway@smsmatrix.com email address, it will be further processed by our SMS Gateway, and premium SMS, Voice or TTS (Text-to-Speech) message will be delivered as a result.
Note: content-type MUST be set like this: "Content-Type: text/plain"
SMS Message via SMTP:
username:user78@hotmail.com password:mypass883 phone:12501238585 callerid:13451238585 sms:Hello Adam, this is a test, please ignore.
TTS Message via SMTP:
username:user78@hotmail.com password:mypass883 phone:16301238534 callerid:13451238585 language:us gender:male tts:Hello John, This is Adam, please call me back.
TTS Message via SMTP:
username:user78@hotmail.com password:mypass883 phone:16301238534 callerid:13451238585 gender:female language:uk response:1 tts:Hello, this is your dentist Joan Smith. You have appointment scheduled for Tuesday at 9am. Press 1 confirm it, or press 2 cancel it. Press 9 to replay this message.
VOICE Message via SMTP:
username:user78@hotmail.com password:mypass883 phone:16301238534 voiceurl:http://www.myweb.ca/sounds/welcome.wav
Keywords (username,password,phone,sms,tts) in these emails ARE CASE SENSITIVE, and must be typed in lowercase - just like in the examples above.
Optionally, 'response' field can be added to voice and TTS messages. 'callerid' field is optional.
The message (sms/tts fields) must be written in one line of text, no newline characters are allowed.
Voice Gateway - Send Voice Message : Perl Example
use LWP::UserAgent;
use HTTP::Request::Common;
# The voice file provided must be in mp3 or wave format.
# It will be converted to: 16Bit 8kHz mono wave format.
my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
POST 'http://www.smsmatrix.com/matrix_voice',
Content_Type => 'form-data',
Content => [ username => 'user@hotmail.com',
password => 'pass8988',
phone => '12502771720', ## comma delimited list
voicefile => ['/tmp/november_sale.wav'],
response => 1, ## optional
callerid => '16307791722' ## optional
]
);
if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response1: " . $res->content . "\n\n";
Voice Gateway - Send Voice Message by URL: Perl Example
use LWP::UserAgent;
use HTTP::Request::Common;
my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
POST 'http://www.smsmatrix.com/matrix_voicew',
Content => [ username => 'user@hotmail.com',
password => 'pass8988',
phone => '12502771720', ## comma delimited list
voiceurl => 'http://www.myweb.de/s/welcome.mp3',
response => 0, ## optional
callerid => '16307791722' ## optional
]
);
if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response1: " . $res->content . "\n\n";
Voice/TTS Gateway - Send Combined: Voice plus TTS Message: Perl Example
use LWP::UserAgent;
use HTTP::Request::Common;
use JSON();
my $msg =
{
username => 'user55@hotmail.com',
password => 'mypass',
phone => '12502012503', # comma delimited list
language => 'us', # optional, see list of supported languages
gender => 'male', # optional
callerid => '12501112233', # optional
response => 0, # optional
msg => [ 'http://www.myserver.com/voices/welcome_prompt.wav',
'This text will be converted to voice by TTS engine.',
'http://www.myserver.com/voices/segment2.mp3' ]
};
my $ua = new LWP::UserAgent;
my $res = $ua->request
(
POST 'http://www.smsmatrix.com/matrix_vtts',
Content_Type => 'application/json',
Content => JSON::to_json ($msg)
);
if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response:\n" . $res->content . "\n\n";
Fax Gateway - Send Fax: Perl Example
use LWP::UserAgent;
use HTTP::Request::Common;
my $ua = new LWP::UserAgent;
my $res = $ua->request
(
POST 'http://www.smsmatrix.com/matrix_fax',
Content_Type => 'form-data',
Content => [ username => 'andywu@apples.mx',
password => 'ibl0w',
phone => '16053537141',
file => ['/tmp/my_fax.pdf']
]
);
if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response:\n" . $res->content . "\n\n";
Incoming SMS (Virtual Mobile Phone Number)
For all incoming SMS messages (when using virtual mobile phone number feature), and for all Voice or TTS messages responses,
our system can submit HTTP POST to an URL associated with the number.
The following data will be submitted:
phonefrom : phone number of the sender phoneto : virtual phone number id : unique alphanumerical ID orgserver : our hostname (usually www.smsmatrix.com) timestamp : UNIX timestamp (GMT) txt : body of the SMS (or TTS/Voice response) smsin : 1 (always set to 1 for incoming SMS messages) voiceresp : 1 (always set to 1 for TTS/Voice responses)Either 'smsin' or 'voiceresp' variables are present and set to 1, not both.
Here is an example of a Perl script that can handle incoming SMS messages:
use CGI;
print "Content-Type: text/plain\n\n";
my $query = new CGI;
my $phonefrom = $query->param ('phonefrom');
my $phoneto = $query->param ('phoneto');
my $sms = $query->param ('txt');
print "Received new SMS from $phone, text: $sms\n";
Similar scripts can be implemented in virtually any programming language.
Retrieve CSV report (message History)
Making a GET or POST HTTP request to this URL:
http://www.smsmatrix.com/csv_reportand providing the following parameters:
email required password required top optional (number of records you want to get, e.g. 100) in_only optional (1 or 0, 1 if you want to get incoming messages only)Example:
http://www.smsmatrix.com/csv_report?email=adam@yahoo.com&password=1234&top=10
SMS Gateway - Error Codes
The following numerical values are returned as statuscode field:
200 - OK 404 - ACCOUNT OR USER DOES NOT EXIST 500 - ERROR 502 - PIN IN DO NOT CALL DATABASE 503 - INSUFFICIENT BALANCE 504 - DATABASE ERROR 505 - USER NOT FOUND OR WRONG PASSWORD 506 - ACCOUNT NOT ACTIVE 507 - DATABASE ERROR 508 - DATABASE ERROR 510 - INVALID USERNAME 511 - INVALID TXT 512 - INVALID PASSWORD 513 - INVALID PIN 514 - NO VOICE FILE PROVIDED 520 - ERROR PARSING XML All values from 0 - 399 (inclusive) mean success, all other values mean failure.
SMS Gateway - Languages supported by TTS
us - US English en - US English uk - UK English jp - Japanese ch - Mandarin it - Italian es - Spanish fr - French de - German pl - Polish fi - Finnish arabic - Arabic ro - Romanian no - Norwegian tr - Turkish sw - Swedish gr - Greek pt - Portuguese ptb - Portuguese Brazilian All languages support male/female voice (gender variable in HTTP post)