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: Register – API TextingHouse.

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 TextingHouse API, 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 valueAdditional parametersDescription
sendsmsyesCommand used for sending SMS.
See Send SMS
getstatusyesGet the status of a message via its ID.
See Get SMS status
getcreditnoGet 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:

 

ParameterMandatoryDescription
toyesRecipient’s phone number prefixed by the international country code
Ex: 33 for France
txtyes

Message text.
The text should be “URL Encoded”.
Note that some special characters may be replaced depending on the SMS destination network.
JavaScript pattern representing the allowed characters:

/[ 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZÄäàÅåÆæßÇèéÉìÖöòØøÑñÜüù#¤%&()*+,\-./:;<>=§$!?£¿·@¡\'"\n\\[\]{}~^|]/

See GSM 03.38

climsgidnoMessage client ID
Defined by customer to get follow-up.
Up to 32 characters.
fromnoAllows 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.

iscomyesIndicates 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

 

Commercial messages must be sent on working days and during the day. The authorized slots (according to the local time of the recipient) are therefore as follows:

  • Monday to Friday between 8 a.m. and 8 p.m.,
  • Saturday between 10 a.m. and 3 p.m.

Text messages of a commercial nature sent outside the authorized time slots will be retained and sent at the next working hour without the customer being able to issue a complaint or cancellation of sending.

Each commercial message must also:

  • specify the identity of the advertiser,
  • provide a simple way to oppose the receipt of new solicitations.

 

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 codeDescription
100Missing parameter
101Authentication failure: invalid username, password or IP address
104Insufficient credit
350Stop 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:

ParameterDescription
api_idTextingHouse ID returned by the API when sending
climsgidCustomer 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 codeDescription
100Missing parameter
101Authentication failure: invalid username, password or IP address
201api_id unknown
202climsgid 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)
  • climsgid: Optional customer ID provided 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 codeStatus typeDescription
0temporaryProcessing in progress
1temporaryIn progress: SMS sent, awaiting final status.
3finalSMS received
4finalExpired or out of reach
5finalNot subscribed
6finalSMS not received”
7finalProhibited sending
20finalInsufficient credit

5.2 Error codes

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