API SMS PRO Documentation

If you have a specific need, contact us!

1. Introduction

The HTTP API is the easiest way to use TextingHouse’s SMS communication portal.

This interface can be used in the form of HTTP POST as well as GET URL.
We recommend using POST if the data volume is large, as the GET is limited in size.

TextingHouse’s responses to these queries are plain text (content-type: text/plain; charset=utf-8).
For example the ID of the SMS created, the SMS status code, the credit value, an error code… They are inserted directly into the HTTP body of the response, without any particular tag.
Communication with our API is done over HTTPS on port 443.

Note: It is important that the entire document is read before contacting support.

All of the examples shown in this document use HTTP GET.

2. Prerequisites

In order to use the SMS sending API you first need an active customer account with positive credit on the TextingHouse systems.
The identifiers will be replaced by ‘XXXX‘ in the code examples that follow.

To register, it’s here: https://api.textinghouse.com.

3. Examples

Below are basic implementation examples for sending an SMS via the TextingHouse API.

The parameters are case sensitive.

GET basic command example
GET:
https://api.textinghouse.com/http/v1/do?user=XXXX&pass=XXXX&cmd=sendsms&to=999&txt=XXXXX&iscom=N
Return example:ID:5d726149a129c829e8c23f7b
Javascript example - jQuery
jQuery.post() :
$.post('https://api.textinghouse.com/http/v1/do',
    {
        user: 'XXXX',
        pass: 'XXXX',
        cmd: 'sendsms',
        to: '999',
        txt: 'My test SMS'
        iscom: 'N'
    }, function(data) {
        alert(data);
    });
Javascript example - axios
axios:
const axios = require('axios');    

axios({
  method: 'post',
  url: 'https://api.textinghouse.com/http/v1/do',
  data: {
    user: 'XXXX',
    pass: 'XXXX',
    cmd: 'sendsms',
    to: '999',
    txt: 'My test SMS',
    iscom: 'N'
  },
  responseType: 'text'
})
.then((res) => {
  console.log(res.data)
})
.catch((error) => {
  console.error(error)
});
PHP example - cURL
cURL:
$data = array(
    'user' => 'XXXX',
    'pass' => 'XXXX',
    'cmd' => 'sendsms',
    'to' => '999',
    'txt' => 'My test SMS',
    'iscom' => 'N'
);
$url = 'https://api.textinghouse.com/http/v1/do';
$ch = curl_init($url);
$postString = http_build_query($data, '', '&');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postString);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

4. How the API works

4.1 Authentication

Once your account is created on https://api.textinghouse.com/, your login details are available on the “Options” page:

  • user : the username provided to you for the http TextingHouse API
  • pass : the password associated with the username

An IP lock can also be added via the “Options” > “IP lock” page in order to allow sending only from a specific IP address: this is recommended.

4.2 Commands

The commands are specified via the « cmd » parameter. The possible values are:

 

cmd value Additional parameters Description
sendsms yes Command used for sending SMS.
See Send SMS
getstatus yes Get the status of a message via its ID.
See Get SMS status
getcredit no Get customer account actual credit.
See Consult your credit balance

4.3 Send SMS

Sending a message is done using the command « sendsms » :

&cmd=sendsms

 

The parameters of the « sendsms » command are as follows:

 

Parameter Mandatory Description
to yes Recipient’s phone number prefixed by the international country code
Ex: 33 for France
txt yes Message text.
The text should be “URL Encoded”.
Note that some special characters may be replaced depending on the SMS destination network.
climsgid no Message client ID
Defined by customer to get follow-up.
Up to 32 characters.
from no Allows you to customize the sender ID of the SMS.

Sender ID personalization is restricted to a set of names authorized for your account. Requests are made via the “Options” page of the API interface.

Limited to 11 unaccented characters (a-zA-Z0-9).

The personalization of the sender ID is not possible for certain destinations (technical restriction of certain operators). TextingHouse reserves the right to replace the sender chosen by the customer at the time of sending.

iscom yes Indicates whether it is a commercial message or not.

Possible value:

  • ‘Y’ for: Yes, this is a commercial message
  • ‘N’ for: No, this is not a commercial message

 

Example of sending an SMS containing the message « SMS accentué de test via TextingHouse » to the French number  with the client ID « FRS78913246 »:

https://api.textinghouse.com/http/v1/do?user=XXXX&pass=XXXXXX&cmd=sendsms&to=33628000000&txt=SMS%20accentu%C3%A9%20de%20test%20via%20TextingHouse&climsgid=FRS78913246&from=test&iscom=N

 

Return:

ID:<api_id> (TextingHouse ID)
Example:
ID:5d726149a129c829e8c23f7b

Following a sending, the API provides the message ID, which confirms that the message has been properly handled. This ID will be necessary for you to correlate the feedback of statuses and the messages sent.
 

Or, in case of error:

ERR: <error_code> | error description
Example:
ERR: 101 | Authentication failed

In the event of an error, the following codes must be taken into consideration:

Error code Description
100 Missing parameter
101 Authentication failure: invalid username, password or IP address
104 Insufficient credit
350 Stop flooding.
Only one message (same content, same telephone number) per recipient is authorized per 10 seconds. Beyond this limit, the API returns this error.

4.4 Get SMS status

We recommend the use of automatic status reporting via the callback URL: see Status callback.

However, it is possible to request the status of a message by specifying its TextingHouse ID or its customer ID with the command « getstatus » :

&cmd=getstatus

The parameters are as follows:

Parameter Description
api_id TextingHouse ID returned by the API when sending
climsgid Customer ID provided when sending

If both parameters are entered, only the api_id will be taken into account.

Example:

https://api.textinghouse.com/http/v1/do?user=XXXX&pass=XXXXXX&cmd=getstatus&api_id=1c97394eea5806c0741be3601d8fca0b

Or

https://api.textinghouse.com/http/v1/do?user=XXXX&pass=XXXXXX&cmd=getstatus&climsgid=FRS78913246

Return:

<status_code>
Example:
3

Status codes: see Status dode

Error code:

Error code Description
100 Missing parameter
101 Authentication failure: invalid username, password or IP address
201 api_id unknown
202 climsgid unknown

4.5 Status callback

The TextingHouse API will send the statuses with HTTP POST on a URL provided by the client (callback URL). This URL configuration is done on the API interface page “Options” > “DLR and MO callbacks”.

For example if the entered callback URL is https://www.mysite.com/myscript.do, the request made by TextingHouse will be:

POST https://www.mysite.com/myscript.do
apimsgid: "5d726149a129c829e8c23f7b"
climsgid: "FR-6468446"
status: "3"

With the following parameters:

  • apimsgid: TextingHouse ID returned by the API when sending (string)
  • climsgid: Optional customer ID provided when sending (string)
  • status: SMS status (string) – code list: see Status codes

The client-side script should respond “ok” in the body of the HTML response, without further markup in order to acknowledge the status received.

4.6 SMS replies callback (SMS MO)

The TextingHouse API will send the SMS replies* with HTTP POST on a URL provided by the client (SMSMO callback URL). This URL configuration is done on the API interface page “Options” > “DLR and MO callbacks”.

* Depending on the operators and the sending countries. Warning, when a sender ID name is used (parameter ‘from’ in ‘sendsms’ command), the recipients cannot reply to SMS.

For example if the entered callback URL is https://www.mysite.com/myscript.do, The request made by TextingHouse will be:

POST https://www.mysite.com/myscript.do
apimsgid: "5d726149a129c829e8c23f7b"
from: "33600000000"
txt: "Text message"
date: "2020-06-01 14:49:05"

With the following parameters:

  • apimsgid: TextingHouse ID returned by the API when sending (string)
  • from: phone number of the message sender (string)
  • txt: the message (string)
  • date: message UTC date, format YYYY-MM-DD HH:mm:ss (string)

4.7 Consult your credit balance

Get your credit balance with command getcredit :

&cmd=getcredit
Example :
https://api.textinghouse.com/http/v1/do?user=XXXX&pass=XXXXXX&cmd=getcredit

Return:

<credit>
Example :
1423

4.8 Test SMS to 999

Sending an SMS to the number 999 is a simple way to test the API for both development and service monitoring.

Sending an SMS to this number is subject to authentication as for sending a standard SMS to a “classic” recipient. Note that SMS sent to 999 are not charged.

The API will support these tests in the same way as standard SMS (see Send SMS, Get SMS status et Status callback), this implies in particular:

  • The return of a message id.
  • Support for your internal id (optional).
  • The transmission of an acknowledgment of receipt in “delivered” status. Note that this virtual acknowledgment of receipt is generated at the end of the test (the SMS is not delivered to an operator) but nevertheless reflects the proper functioning of our sending chain and in particular the communication between the API front-ends and our platforms of consignments.
  • The response to the status query on this message ID.

The content of the test SMS is free and not taken into account.

5. Appendices

5.1 Status codes

Status code Status type Description
0 temporary Processing in progress
1 temporary In progress: SMS sent, awaiting final status.
2 final Sent to the operator (sending without status request only)
3 final SMS received
4 final Expired or out of reach
5 final Not subscribed
6 final SMS not received”
7 final Prohibited sending
20 final Insufficient credit

5.2 Error codes

Error code Description
100 Missing parameters
101 Authentication failure: invalid username, password or IP address
104 Insufficient credit
201 Unknown api_id
202 Unknown climsgid
300 Error processing request
350 Flood detected.
Only one message (same content, same telephone number) per recipient is authorized per 10 seconds. Beyond this limit, the API returns this error.