Guide Solutions MKT

Le guide des solutions MKT

Return to guide

API SMS

1 - Introduction

This page describes the different functionalities of the Axialys API for sending SMS and how you should implement them.

This will allow you to:

  • send SMS
  • receive read receipts of your messages

2 - Activating your account

When creating your account, you can provide us with the IP address of the machine that will be querying the server and the address and URI of the server to which receipts should be sent (if you wish to enable this feature). Once your account has been created, you will be provided with a key and the details of the server to be queried.

3 - The various variables used

Fields Description Length Example
key
Key for identifying the client. It must always be sent. It is also possible to define the IP address of the machine authorised to access your account.
16
ma_cle
pass
Password. Can be changed, always provided.
16
passe
ID
Sending ID. This field is optional, you can put what you want; it will allow you to match a read receipt or a received message to a sent message.
16
test
ID2
Optional field. Can be used for your own customer identifiers for example.
16
client 1
ID3
Optional field. Can be used for your own customer identifiers for example.
16
client 2
liste
List ID
10
1
numero
Phone number in e164 format
20
33619000000
nom
Allows personalisation of messages using ##NOM##
32
Dupont
prenom
Allows personalisation of messages using ##PRENOM##
32
Patrick
usr1
Allows personalisation of messages using ##USR1##
32
pat
usr2
Allows you to personalise messages using ##USR2##
32
pat
numeros
List of numbers in e164 format
20
contenu
Content of the message to be sent or received. Messages sent must not be longer than 160 characters.
160
Ceci est un message de test !
type
STANDARD: sending a simple SMS. REPLY: option to receive replies
8
STANDARD
date
Approximate date when the message should be delivered or when a message was received. It has the format YYYYMMDDHHiiSS
14
20160806181000
emetteur
Allows you to configure the sender of the message, you can use a character string or a number in e164 format. Personalisation of the sender is not compatible with the reception of any return messages.
16
Axialys
ttl
Sending deadline after which the message can no longer be transmitted.
14
20160806181000
marketing
Specify the sending type: 1: Marketing sending 0: Notification sending
format
Allows you to select the output format of the API, currently available are: * csv (default old format, the header of the returned CSV is not always available) * csv_header * json
json
encodage
UTF-8: allows to convert some data to UTF-8 instead of ISO-8859- 1
mode_envoi
LATIN1: use of a subset of ISO-8859- 1 EXTENDED: use of extended characters (WARNING, the size of the SMS is greatly reduced, see Table in section VI, and it is necessary to convert the content of the message to UTF-8)
LATIN1
URL
##TRACKINGURL## used by the short URL and will be replaced by a shorter axialys address in the form "axia.ly/XXXXXXX" without the http/https prefix that any mobile is able to interpret today. On the other hand, be sure to specify "http/https" when configuring this variable and avoid using overtones and do not exceed 128 characters
128
https://guide.axialys.com/welcome

4 - Managing list subscribers

It is possible to define lists of subscribers, so that a message can later be sent to a predefined set of people.

To manage them, you have 5 features at your disposal:

  • get_subscribers: To get all the subscribers of a list.
  • add_subscriber: To add a subscriber to a list.
  • del_subscriber: To remove a subscriber from a list.
  • reset_subscribers: To remove all subscribers from a list.
  • update_subscriber: To update the data of a subscriber (based on the number).
  • add_list: To add a list.
  • update_list: To update the attributes of a list.

4.1. « GET_SUBSCRIBERS » method

The variables used by this method are:

  • Mandatory: key, pass, list
  • Optional: –

The requested URL has the following format: http://api-sms.sites.axialys.net/get/get_abonnes.php?cle=macle&pass=pass&liste=10&numero=336100000000

This request returns a page containing all the numbers belonging to this list as well as the associated data (name, first name, usr1, usr2). Only the fields containing a value are returned, here is an example with 2 results:

OK 33619471505;dd

If there is no data, an error message is returned. The list of error codes returned is in the Appendix.

4.2. « ADD_SUBSCRIBERS » method

The variables used by this method are:

  • Mandatory: key, pass, list, number
  • Optional: username, last name, first name, usr1, usr2, encoding

The requested URL has the following format: http://api-sms.sites.axialys.net/get/add_abonne.php?cle=macle&pass=pass&liste=10&nom=david&prenom=david

If the insertion is successful, the request returns ‘OK’.

4.3. “DEL_SUBSCRIBER” method

The variables used by this method are:

  • Mandatory: key, pass, list, number
  • Optional: –

The requested URL has the following format: http://api-sms.sites.axialys.net/get/del_abonne.php?cle=macle&pass=pass&liste=10&numero=336100000000

If the deletion is successful, the request returns ‘OK’.

4.4. “RESET_SUBSCRIBERS” method

The variables used by this method are:

  • Mandatory: key, list
  • Optional: encoding

This method is used in the same way as “get_subscribers”, it returns the message ‘OK’ if the removal of all subscribers is successful.

4.5. “UPDATE_SUBSCRIBER” method

The variables used by this method are:

  • Mandatory: key, list, number
  • Optional: username, surname, first name, usr1, usr2, encoding

This method is used in the same way as ‘add_subscriber’, it returns the message ‘OK’ if the update is successful.

4.6. “ADD_LIST” method

The variables used by this method are:

  • Mandatory: key, pass, number
  • Optional: –

The requested URL has the following format: http://api-sms.sites.axialys.net/get/add_liste.php?cle=macle&pass=pass&nom=maPetiteListe

The request returns ‘OK’ if everything is successful.

4.7. “UPDATE_LIST” method

The variables used by this method are:

  • Mandatory: key, pass, list, number
  • Optional: –

The requested URL has the following format: http://api-sms.sites.axialys.net/get/update_liste.php?cle=macle&pass=pass&liste=1&nom=maPetiteListe

This method returns the message ‘OK’ followed by the ID assigned to the list.

4.8. “CANCEL” method

The variables used by this method are:

  • Mandatory: key, pass
  • Optional: number, list, type, date, ttl, ID2, sender

The requested URL has the following format: http://api-sms.sites.axialys.net/get/cancel.php?cle=macle&pass=pass&numeros[]=33670200200&format=json

This method allows you to cancel a delivery, it returns ‘OK’ if the deletion has been completed, as well as the number of lines deleted.

5 - Sending SMS

A message can be sent to one or more numbers, it is also possible to send it to a predefined mailing list with the methods seen previously. The variables used by this method are:

  • Mandatory: key, ID
  • Optional: number, list, type, date, ttl, ID2, ID3, sender, send_mode, URL

This is the format of a message sent to a mailing list: http://api-sms.sites.axialys.net/get/send.php?cle=dd&ID2=axe&ID3=test&pass=pass&liste=10&id=ax&contenu=coucou+dd&emetteur=AXIALYS

This is the format of a message sent to several numbers: http://api-sms.sites.axialys.net/get/send.php?cle=dd&ID2=axe&pass=pass&numeros[]=336100000000&numeros[]=336100000001&id=ax&contenu=coucou+dd

As with the previous methods, the request returns ‘OK’, once the data has been embedded. If the SMS to be sent is of type SEND, the text of the SMS must be in UTF-8 format.

6 - Receiving MO SMS

If a user replies to a message, it is possible to retrieve it. The URL to which the reply will be sent is the same as for notifications.

The variables received are the following:

Variable Description
Type
MO
ID
Message identifier provided at the time of sending
numero
Number in e164 format
date
Date of read receipt or follow-up of the message
Etat
Returned message

7 - SMS count

In order to comply with current legislation, a note is added to marketing messages so that the user can opt out of receiving SMS messages. All they have to do is reply “STOP” to the message received. The length of the note must be deducted from the message sent.

  • Marketing with personalisation: STOP XXXXX (10 characters)
  • Marketing without personalisation: STOP XXXXX (10 characters)

This is only valid for France for the moment.

Type/Cost 1 SMS 2 SMS 3 SMS 4 SMS 5 SMS
Notification
160
280
420
560
700
Marketing without personalisation:
150
270
410
550
690
Marketing with personalisation:
150
270
410
550
690
Extended characters
70
134
201
268
335

8 - Receiving read receipts

If you have a server capable of receiving HTTP requests, and after sending the information about the server name and URI you want to use, you have the possibility to receive all the information about the status of the message sent. For the same message sent to a given phone, you can receive several pieces of status information. For example, at the time of sending, the mobile may be outside the network’s coverage area, the message will then be received when the phone is in a coverage area. We are then notified each time the status changes, until the message is transmitted. Below are the values returned:

Variable Description
Type
ACK
ID
Message identifier provided at the time of sending
numero
Number in e164 format
date
Date of read receipt or follow-up of the message
Etat
The list of possible statuses can be found in the annexes

9 - Sending SMS by email

Our platform also makes it possible to send SMS by email. In order to send SMS, all the settings concerning the message(s) are sent in the body of the email in the following format:

The email will then be sent to [email protected] In case of a problem, such as a missing variable or an authentication problem etc., an error message will be sent back to you with a description of the problem.

9.1. Authentication

Authentication is performed against the sender address provided to us when your API is activated. You can also provide us with a list of IP addresses authorised to send SMS using your account.

9.2. Mandatory variables

In order to send your message, we first need to know who it is intended for. To do this, we need to fill in the ‘number’ or ‘list’ variables, which are respectively a telephone number or the name of a list to which we wish to send the message. In the case of using the variable ‘number’, we can indicate several telephone numbers by separating them with a comma.

We must then fill in our message with the ‘content’ variable, taking care that it does not contain any unauthorised characters.

When sending to a list, we can also personalise the message for each contact on the list using the:

##NOM##, ##PRENOM##, ##USR1##, ##USR2##

list:axialys

content:Hello ##PRENOM## ##NOM##, you have won ##USR1##

9.3. Optional variables

We can then programme the delivery on a given date or to set an end date with the ‘date’ and ‘ttl’ variables respectively.

Please note that these variables must always specify the ‘content’ variable.

And finally, you have 3 variables that allow you to identify your deliveries or possibly facilitate the invoicing of your customers: ID, ID2 and ID3.

 

liste:axialys

date:20111010101010

ttl:20111020101010

10 - Sending SMS via FTP

SMS can be sent by means of an FTP file. The repository consists of the following directories:

  • pending: folder in which the file to be processed is to be stored
  • processing: data being processed
  • archive: backup of the processed data.

The file to be processed must be in ISO-8859-1 format, except if extended characters are used; in this case the file will be in UTF-8 and must have the following format: “*_ETENDU.csv”.

The available columns are:

  • ID: message identifier
  • e164: phone number to send the SMS to
  • content: message to send
  • date: date of message delivery
  • sender: name to be displayed in the message sender
  • ttl: not used
  • ref: message reference
  • marketing: allows activation of marketing mode when the field is set to “1”.
  • unused
  • URL: the URL which will be replaced by a short URL, only valid for one month, the link will be in the form of “axia.ly/XXXXXXX” without the http/https prefix that any mobile is able to interpret today. When using the short URL, do not forget to use “##TRACKINGURL##” in the message, which will be replaced by the short URL.

 

.

11 - Annexes

11.1. Errors returned during HTTP requests

Here is the list of error codes returned:

Code Description
1
Method not found
2
Identification problem
3
Returned list is empty
4
Adding a subscriber failed
5
Deleting a subscriber failed
6
The number field is incorrectly filled in
7
No list or destination number has been defined
8
No message has been defined
9
Deadline is earlier than the sending date
10
Sending failed
13
Internal error

Error messages have the following format: NO;<error code>;<error message>

11.2. The different possible message statuses

The following is a list of the different statuses that a message sent can have:

Code Description
1
Message sent
2
Platform problem
5
Message expired
6
Invalid syntax
7
Out of coverage area
8
Unknown error
9
Service temporarily unavailable
10
Unknown subscriber
11
Number dialled
12
In progress
13
Message received
14
Destination not included in the package
15
Destination blacklisted
16
Phone not compatible
17
Insufficient balance
18
Message undeliverable
20
Waiting to be sent
21
Awaiting mass delivery (internal)
23
Invalid number
24
Subscriber unreachable

11.3. Character set allowed in SMS

The character set supported by Axialys in the message content is a subset of ISO-8859- 1, as defined in the table below.

To force the use of non-Latin characters, the “send_mode” variable must be set to “EXTENDED”.

12 - Modifications/Evolutions

Date Version Modifications/Evolutions
08/2017
1.8
Management of short URLs
01/2015
1.7
Management of extended characters
06/2014
1.6
STOP and return management
02/2013
1.5
Updating
04/2011
1.3
Sender personalisation
10/2010
1.2
Possibility of sending an SMS by email
01/2008
1.1
Version initiale
  • Table of contents