API SMS PRO Documentation

Test API
If you have a specific need, contact us!

Versions

Num Modifications Date of application
1.0.0 Initial version
1.1.0
  • Commercial messages must include the words ‘STOP sms-s.top’.
  • Error code added : 400 – STOP mention missing
 16/12/2021
1.1.1 11/07/2022

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 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.
See 5.3 Allowed characters in SMS
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

 

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.

Commercial messages on Sundays and public holidays are not permitted.

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,
  • include the mention ‘STOP sms-s.top’

See detail below: Commercial / marketing SMS

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.
400 STOP mention missing
The message is commercial but the mention `STOP sms-s.top` is missing.

 

Commercial / marketing SMS

The parameter « iscom » (mandatory) of the « sendsms » command indicates if your SMS is commercial (or marketing), or if it is a service message.

 

Reminder of the CNIL rules concerning commercial SMS:

SMS advertising is possible in France provided that people have explicitly given their consent to be canvassed when collecting their mobile phone number.

Each commercial message must:

  • specify the identity of the advertiser,
  • provide a simple way to object to receiving new solicitations (STOP SMS).
  • be sent only on working days and during the day.

 

STOP SMS

All commercial SMS (iscom = Y) must include the mention ‘STOP sms-s.top’ at the end of the text of your message.

TextingHouse will then automatically collect STOP SMS from your recipients to allow them to unsubscribe from your communications.

If a commercial SMS does not contain the mention ‘STOP sms-s.top’, it will be refused (error 400).

 

Time restrictions:

The rules for prospecting by SMS define that messages of a commercial nature must be sent on working days and during the day. The slots allowed by TextingHouse are therefore as follows:

  • Saturday between 10 a.m. and 3 p.m.

Commercial messages are not permitted on Sundays or public holidays.

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.

 

SMS cost

Each SMS sent to the API (except test SMS sent to 999), is billed at the rate in effect at the time of sending. If the SMS exceeds 160 characters, each additional SMS will be counted according to the cutting of the SMS (see FAQ What size of message can I send by SMS ?).

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 containing the status in JSON format 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.mondomaine.com/monscript.do HTTP/1.1
Content-Type: application/json

{
  "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 with a 2XX HTML status code. The response body is not processed by TextingHouse.

4.6 SMS replies callback (SMS MO)

The TextingHouse API will send the SMS replies* with HTTP POST containing the SMS reply in JSON format 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.mondomaine.com/monscript.do HTTP/1.1
Content-Type: application/json

{
  "apimsgid": "5d726149a129c829e8c23f7b",
  "climsgid": "FR-6468446",
  "from": "33600000000",
  "txt": "Texte du message",
  "date": "2019-04-01T13:09:16Z"
}

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)

The client-side script should respond with a 2XX HTML status code. The response body is not processed by TextingHouse.

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.
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.
400

STOP mention missing

The message is commercial but the mention `STOP sms-s.top` is missing.

5.3 Allowed characters in SMS

JavaScript pattern representing the allowed characters:

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

See GSM 03.38