SMS API

An API is available to send SMS messages from your information system.

Only sends to French mobile numbers are handled by the API. Messages are sent through a direct operator connection (Premium SMS), which makes it possible to manage replies and unsubscribes via a short code.

The URLs declared in the “URL Link” module can be used in your messages sent through the API. Click events are identified in the reports.

Unlike the SMS sending platform, sending hours are not restricted. However, please note that marketing SMS sends are forbidden between 8pm and 8am, as well as on Sundays and public holidays. Only solicited transactional SMS messages are allowed during these time slots.

The endpoint is: https://www.eml-srv.com/_api_rest/api_sms_submit

The Ediware SMS platform overview is available here.

Authentication

The API uses the REST format and is accessed through HTTP Basic authentication.

How authentication works

If your username is “monlogin” and your password is monmotdepasseABC, you must build the following string: monlogin:monmotdepasseABC
Then encode it in base 64: bW9ubG9naW46bW9ubW90ZGVwYXNzZUFCQw==

The following property must be added to your HTTP header:
“Authorization” : “Basic bW9ubG9naW46bW9ubW90ZGVwYXNzZUFCQw==”

PHP example with cURL

cURL makes HTTP Basic authentication easy to handle:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.eml-srv.com/_api_rest/api_sms_submit');
curl_setopt($ch, CURLOPT_USERPWD, "monlogin:monmotdepasseABC");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
$output = curl_exec($ch);

Sending an SMS

Important: all character strings, especially the message itself which may contain special characters, must be encoded in UTF-8.

Parameters must be formatted in JSON.

Parameters

Text: the text of your message

TrackingId: a string of your choice. It is the reference of your task that will be returned later and will let you easily find your send.
This field is optional.

AdhocRecipients: the list of mobile numbers the message should be sent to.
It is an array with the key “Number” and as value the recipient’s mobile number.

Sender: a string of up to 11 characters that may only contain letters and digits (1-Za-z0-9), spaces or dots.
This field is optional. If empty or omitted, the SMS sender will be a French short code.
If this field is customized, the recipient will not be able to reply to the SMS, nor unsubscribe by replying “STOP”.
If this field is customized, the text “STOP XXXXX” will be automatically appended to your message. This string is 16 characters long.

Accepted number formats

Two formats are accepted:

• French: 06XXXXXXXX or 07XXXXXXXX
• International: +336XXXXXXXX or +337XXXXXXXXX

Request examples

Sending with a customized sender to a single recipient

{
     "Text": "This is a test", 
     "TrackingId": "my_tracking_id",
     "AdhocRecipients": [
          {
               "Number": "+337xxxxxx"
          }
     ]
}

Sending without a customized sender to two recipients

{
     "Text": "This is a test", 
     "TrackingId": "my_tracking_id",
     "AdhocRecipients": [
          {
               "Number": "+337xxxxxx"
          },
          {
               "Number": "+336xxxxxx"
          }
     ],
     "Sender": "Ediware"
}

PHP sending example

$url = 'https://www.eml-srv.com/_api_rest/api_sms_submit';

$username = 'your_login';
$password = 'your_password';

$msg = 'This is a UTF-8 encoded message';

// Build the parameters array

$data_to_post = array(
    'Text' => $msg,
    'TrackingId' => 'my_internal_tracking_id',
    'AdhocRecipients' => array(
        array(
            'Number' => '+336XXXXXXXX'
        ), // I can add up to 100 numbers
    ),
'Sender' => 'EDIWARE',
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_USERPWD, "$username:$password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data_to_post));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
$output = curl_exec($ch);
curl_close($ch);

// die($output); // for easy debugging

$output = json_decode($output);

// var_dump($output); // response handling

Handling the response

The response is in JSON format.

On error

The possible errors are:

• Auth protocol error: the login or password is not set, or the protocol is incorrect
• Auth error: the protocol is correct but the credentials are wrong
• Unknown error - no id: internal system error
• SMS Module desactivated for this account: the SMS module is not enabled on your account
• No more SMS credits: you have no remaining sending credits
• Empty message: the message to send is empty
• Message too long, nothing was sent: the message must be less than 700 characters
• Wrong number nothing was sent: a number was in the wrong format. In that case the entire process is aborted.

On success

A process number is returned. You should store this number on your side, as it is the way to easily look up the status of the sends.
The number of credits consumed by the process is also indicated for information.

Example: {“JobNumber”:“unique process number”, “Cost”:“1”}

About message length

A single SMS can only contain 160 characters.

If the sender is customized, 12 characters are used to add an unsubscribe mechanism (STOP XXXXX). The maximum length is therefore 148 characters.

If you send a longer message, one or more additional credits will be consumed.
For SMS messages with a non-customized sender, the credit cost is:
1 credit up to 160 characters
2 credits up to 306 characters
3 credits up to 459 characters
4 credits up to 612 characters
5 credits up to 612 characters
6 credits beyond, however we cannot send SMS messages longer than 700 characters.

A specific case: the € sign counts as two characters because of how SMS encoding works.

Retrieving the status of your sends

Through the web interface

In the SMS Campaigns > API section, you can view the latest sends and their statuses.
You can also download the replies via the SMS Campaigns > Replies page.

Through an HTTP webhook

The URL where events should be posted must be specified in the SMS Campaigns > API > Webhooks section.

Data sent by the SMS API webhook

A test webhook can be sent through the interface to make your development easier.

The dictionary of returned values is below:

id: arbitrary numeric identifier generated by the platform for internal use.

date_envoi: SMS send date

TrackingId: the reference of your task, defined when sending the SMS to the API, returned to easily identify your send

JobNumber_api: unique process identifier generated by the platform. This is the same identifier returned when sending the SMS to the API.

tel: the recipient’s phone number

messagelength: the message length computed by the platform

credits: the number of credits consumed

status: overall status of the send

code_status: detailed status of the send (possible values at the end of the article)

date_status: date of the last status change

error_code: result of the transmission (possible values at the end of the article)

error_detail: result of the transmission “human readable” (possible values at the end of the article)

clicked: 1 if a link was clicked in the message, NULL otherwise

answer: the text of the recipient’s reply to the SMS, if any.

Data dictionary for the SMS API webhooks

The values returned by “statut”, “error_code”, “error_detail” and “code_statut” all return the result of the SMS send, with different levels of detail.

For most projects, processing the “statut” value is enough. Processing “error_code”, “error_detail” and “code_statut” is useful for cleaning a phone number database.

Possible values for “statut”**

Possible values for “error_code” and “error_detail”

Possible values for “code_status”

Processing these codes is optional. They give a very detailed view of why an SMS did not go through.

Code 10201 corresponds to a read receipt for the SMS.