Skip to main content

HTTP-Schnittstelle für SMS

Ihre einfache Verbindung zur Welt

Unsere APIs und Dokumentationen helfen Ihnen, die SMS effizient
in Ihr bestehendes System zu integrieren, ohne über
detailliertes technisches Verständnis verfügen zu müssen.

Versenden Sie noch heute SMS mit GTX

GTX Messaging HTTP Gateway

 

The Mobile Messaging SMS Gateway provides an easy-to-use and easy-to-implement HTTP-GET interface for receiving and submitting messages from and to the gateway. This manual will describe the interface and provide some examples on how to use the interface. If you have further questions regarding this interface, please contact your account manager or file a trouble ticket to support@gtx-messaging.com

Sending SMS

Targets


You can reach the SMS Gateway under the following URL using HTTP:

http://http.gtx-messaging.net/smsc.php

If you prefer to use a HTTPS connection instead, please use this endpoint:

https://http.gtx-messaging.net/smsc.php

Request


The following HTTP-­GET or HTTP-Post parameters should be set when sending a message:

Field Mandatory Type Description Example
user yes String Your username "comp_gold_001"
pass yes String Your password "topsecret"
from¹ optional Alphanumeric String
Numeric
MSISDN		 The TPOA / originator of the message "Company"
"49171000000"
"55888"
to yes MSISDN The recipient of the message in international format without "+" "491701234567"
"44751234567"
t optional TEXT|BINARY|UNICODE Type of the message (defaults to "TEXT") "TEXT"
text² optional String Text of the message "Hello World"
coding3 optional Fixed String Use UCS-­2 coding "ucs2"
udh4 optional HEX Custom UDH "0605040B8423F0"
data4 optional HEX Custom Data "1B0601AE02056..."
dcs4 optional Integer Custom DCS "8"

1) The TPOA in the from-­field may be overridden, based on your profile/contract. In case you do not have a custom TPOA, this parameter can be left out. Please note that special characters are not allowed.

2) When using multi-­byte text (UTF-­8), make sure to set the t-­parameter to  "UNICODE", only mandatory when the t­-parameter is either "TEXT" or "UNICODE". Please see the Encoding reference below.

3) Only applicable when the t-­parameter is set to "UNICODE". Please note that UCS-­2 coding requires more bytes per character. A single-­part message can contain up to 70 characters, multi-­part messages can contain up to 67 characters.

4) Only applicable when the t-­parameter is set to "BINARY".

Encoding


The gateway internally uses UTF-8 encoding. If you submit messages as plain text (parameter t=TEXT, default) then the gateway will assume that the text is encoded using Windows-1252 (a.k.a. CP-1252). If you want to submit UTF-8 text please set the parameter t=UNICODE. Please note that special Unicode characters can only be transmitted using UCS-2 coding.

Wikipedia provides a good reference; please see en.wikipedia.org/wiki/Windows-1252 or en.wikipedia.org/wiki/UTF-8 for more information.

Request Examples

 

Simple text message


The easiest way of using the interface:

http://http.gtx-messaging.net/smsc.php?user=comp_gold_001&pass=topsecret&from=ACME&to=491701234567&text=Hello+World

Binary message containing a WAP-Push

Send a WAP-Push message to the recipient (may not work on all products, please ask your account manager for details about special binary content):

http://http.gtx-messaging.net/smsc.php?user=comp_gold_001&pass=topsecret&to=491701234567&t=BINARY&udh=0605040B8423F0&data=1B0601AE02056A0045C60C037777772E796F632E636F6D0001034D6F62696C6520456E61626C696E67000101

Multi-byte message with UCS-2 coded data (using BINARY format and DCS)

If your client already encodes multi-byte messages using UCS-2 itself, you may simply supply that coded data and set the necessary DCS by yourself:

http://http.gtx-messaging.net/smsc.php?user=comp_gold_001&pass=topsecret&to=491701234567&t=BINARY&data=041F044004804204504B&dcs=8

Multi-byte UTF-8 message (with UCS-2 coding)

In this example the text is submitted using UTF-8 encoding. By setting the parameter coding=ucs2 the gateway is requested to encode this message in UCS-2:

http://http.gtx-messaging.net/smsc.php?user=comp_gold_001&pass=topsecret&from=ACME&to=491701234567&t=UNICODE&text=%D0%9F%D1%80%D0%B8%D0%B2%D0%B5%D1%82&coding=ucs2

Response


The Gateway will return a response containing a result of the performed operation. If the operation was successful, the result will contain a message ID that will be referred to when sending a DLR to the customer (see examples).

The following error codes will be returned:

Code Description
200 OK Message sent (includes message ID)
400 Bad Request Malformed or bad request submitted
401 Unauthorized Wrong username / password
408 Blacklist The recipient is blacklisted (upon request)
503 Service Unavailable Service is currently unavailable, please try again

Response Examples

 

Successful Submission

The submitted message was sent successfully and assigned the internal message ID 26818021.

HTTP/1.1 200 OK\r\n
(HTTP Headers shortened)
Content-Length: 17\r\n
\r\n
200 OK (26818021)

Service Unavailable

This service is temporarily unavailable, please try again later.

HTTP/1.1 200 OK\r\n
(HTTP Headers shortened) \r\n
Content-Length: 23\r\n
\r\n
503 Service Unavailable

Receiving DLRs


The gateway will return an asynchronous delivery report (DLR) to your site via HTTP GET. In order to receive DLRs your profile must support DLRs and you must provide GTX with a callback URL that will satisfy the following interface requirements. The DLR callback refers to the message ID that was previously returned in response to the submission and will contain the destination MSISDN of the submitted message.

Request Parameters


The following parameters will be provided to the callback URL:

Field Mandatory Type Description Example
id yes Unsigned
Long		 The message ID this DLR refers to "21498252"
status yes Integer The last status of the message "1"
snr yes MSISDN The number of the recipient "+491721234567"

Status definitions


The status codes provided to the callback URL should be interpreted in this manner:

Status Description
1 Delivered to phone
2 Not delivered to phone
4 Queued on SMSC
8 Delivered to SMSC
16 Not delivered to SMSC

Example DLR Callback


Given that you have provided your account manager with the callback URL:

http://system.company.com/dlr.cgi

A sample DLR callback could look like this:

http://system.company.com/dlr.cgi?id=21498252&status=1&snr=%2B491721234567

This callback reports that the message identified by 21498252 was successfully delivered to the recipients phone. The recipient number is +491721234567.

 

Note: Client always has to respond with HTTP_OK and body: „Result: OK“

 

 

Receiving Session Replies


When using a 2way product (e.g. Silver 2way) the recipient of the message can reply to it. This reply will be redirected to a given interface to your site. In order to receive these session replies you must provide GTX with a callback URL that will satisfy the following interface requirements. The session reply will refer to the original message ID that was previously returned in response to the submission.

Please ask your account manager about 2way products for more details.

Request parameters


The following parameters will be provided to the callback URL:

Field Mandatory Type Description Example
id yes Unsigned
Long		 The message ID this reply refers to "21498252"
from yes MSISDN The number of the originator (former recioient) "00491717654321"
to yes MSISDN Allways the virtual number "00491710000000"
text yes String The message of the reply (UTF-8) "Ping back"
user yes String Your username "comp_gold_001"

Given that you have provided your account manager with the callback URL:

http://system.company.com/reply.cgi

A sample session reply callback could look like this:

http://system.company.com/reply.cgi?id=12345678&from=00491721234567&to=00491710000000text=Ping%20back

This callback reports that there is a message from the user 00491721234567 in reply to the message identified by 12345678. The message text is "Ping back" 

Receiving SMS


To receive SMS on a short code or a long number you must provide GTX with a callback URL that will satisfy the following interface requirements.

Request parameters


The following parameters will be provided to the callback URL

Field Mandatory Type Description Example
timestamp yes UNIX Timestamp The timestamp of the message (GMT) "1306413940"
from yes MSISDN The number of the originator "00491717654321"
to yes MSISDN The recipient of the message "55123" or
"00491715554443"
text yes String The message sent by the originator
(UTF-­8)		 "Hello World"
user yes String Your username "comp_gold_001"

Example MO SMS


Given that you have provided your account manager with the callback URL:

"http://system.company.com/inbox.cgi"

A sample session reply callback could look like this:

http://system.company.com/inbox.cgi?from=00491721234567&to=55123&text=Hello%2World&timestamp=1206415240

This callback reports that there is a message from the user 00491721234567 that was sent to the short code 55123 on Tue, 25 Mar 2008 at 03:20:40. The text of the message is "Hello World""

Sample Code


This sample pseudo-­code is written in PHP and will help to demonstrate how the interface is used. It does not include any error handling and is not meant as a recommendation but just for illustrative purposes.

Send a text SMS

<?php

$gw = "http://http.gtx-messaging.net/smsc.php";

$auth = array(
   'user' => 'comp_gold_001'
   , 'pass' => 'topsecret'
);

$message = array(
   'from' => 'ACME'
   , 'to' => '491701234567'
   , 'text' => 'Hello World!'
);

$url = $gw. "?user=".$auth['user']."&pass=".$auth['pass'];
$url .= "&from=".urlencode($message['from'])."&to=".$message['to']; 
$url .= "&text=".urlencode($message['text'])

; $cp = curl_init($url);
curl_setopt($cp, CURLOPT_HEADER, false);
curl_setopt($cp, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($cp);

if ($result === false) { // error handling } else { // parse response message }

curl_close($cp);

?>

Send a Unicode SMS

<? php
//Assuming this file is UTF-8

$gw = "http://http.gtx-messaging.net/smsc.php";

$auth = array(
   'user' => 'comp_gold_001'
   ,   'pass' => 'topsecret'
);

$message = array(
   'from' => 'ACME'
   ,   'to' => '491701234567'
   ,   'text' => 'text'
   ,   'coding' => 'ucs2'
);

$url = $gw. "?user=".$auth['user']."&pass=".$auth['pass'];
$url .= "&from=".urlencode($message['from'])."&to=".$message['to']; 
$url .= "&text=".urlencode($message['text']);
$url .= "&t=UNICODE&coding=".$message['coding']; 

$cp = curl_init($url);
curl_setopt($cp, CURLOPT_HEADER, false);
curl_setopt($cp, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($cp);

if ($result === false)  {
   //  error handling
} else {
   // parse response message
}

curl_close($cp);

?>

Process a DLR callback

We are using a pseudo-class for database abstraction.

<? php

if (isset($_REQUEST['id'], $_REQUEST['status'], $_REQUEST['snr']))  {

   $db->connect('to', 'my', 'database');

   $sql = "UPDATE my_message_table ";
   $sql .= "SET last_status = ?";
   $sql .= "WHERE remote_id = ?";
   $sql .= "AND destination = ?";
   $sql .= "LIMIT 1 ";

   $statement = $dfb->prepare($sql);
   $statement -> bindParam($_REQUEST['status']);
   $statement -> bindParam($_REQUEST['id']);
   $statement -> bindParam($_REQUEST['snr']);

   $statement -> execute() ;

   $db -> disconnect () ;

}

?>

Process a session reply callback

We are using a pseudo-class for database abstraction.

<? php

if (isset($_REQUEST['id'], $_REQUEST['from'], $_REQUEST['text'], ))  {

   $db->connect('to, 'my', 'database');

   $sql = "INSERT INTO my_reply_table ";
   $sql .= "(message_id, orogonator, text)  ";
   $sql .= "VALUES (?, ?, ?, ?)  ";

   $statement = $dfb->prepare($sql);
   $statement -> bindParam($_REQUEST['id']);
   $statement -> bindParam($_REQUEST['from']);
   $statement -> bindParam($_REQUEST['text']);

   $statement -> execute() ;

   $db -> disconnect () ;

}

?>

Process a MO SMS callback

we are using a pseudo-class for database abstraction.

<? php

if (isset($_REQUEST['from'], $_REQUEST['to'], $_REQUEST['timestamp'], $_REQUEST['text']))  {

   $db->connect('to', 'my', 'database');

   $sql = "INSERT INTO my_mo_table ";
   $sql .= "(originator, destination, ts, text)  ";
   $sql .= "VALUES (?, ?, ?, ?)  ";

   $statement = $dfb->prepare($sql);
   $statement -> bindParam($_REQUEST['from']);
   $statement -> bindParam($_REQUEST['to']);
   $statement -> bindParam(date('Y-m-d H:i:s', $_REQUEST['timestamp']));
   $statement -> bindParam($_REQUEST['text']);

   $statement -> execute() ;

   $db -> disconnect () ;

}

?>

Benutzerhinweise herunterladen

PDF-Datei Herunterladen