SMS API V2

Thank you for choosing Direct Messenger API. This documentation will help you set up the API connection and explains different options available to you.

How to get started

1. Contact us to get an account

To send messages using our API you first need a messaging account. You can create a Smart account on our website here: smart.messenger.ee. To get a Premium account you need to contact us on support@messenger.ee.

2. Set up your connection using the API key we provided

The next step is to setup your connection to our server. We use an API KEY to authenticate all our incoming request. If you do not have an API key or you have lost it feel free to contact us. For Smart account the API KEY will be generated on your account right after the credit has been added.

Setup

The setup is fairly simple if you are familiar with POST requests. The most basic request to send a text message through our API requires the following parameter:

api_token - Your API key
smstext - Message that you want to send
receiver - The receiving number
sender - Name displayed for the recipient

We will explain some of those parameters in more detail further down and go over some common mistakes/misunderstandings.

PS! Every request should use UTF-8 encoding

Here's what a basic request like that might look like:

POST https://API_URL/?api_token=YOUR_API_KEY&smstext=Foo&receiver=372555555555&sender=Bar

Example

A basic request using PHP curl

// Get cURL resource
$curl = curl_init();
// Set some options - we are passing in a useragent too here
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => [
        'Accept:application/json',
    ],
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'API_URL',
    CURLOPT_POST => 1,
    CURLOPT_POSTFIELDS => [
        'api_token' => 'YOUR_API_KEY',
        'smstext' => 'Message you want to send',
        'receiver' => '37255555555',
        'sender' => 'Bar'
    ]
]);
// Send the request & save response to $resp
$resp = curl_exec($curl);
// Close request to clear up some resources
curl_close($curl);

Available parameters

Attribute	Description
`api_token`	Your API key, provided by us, used to authenticate each request.
`smstext`	Message you want to send. For the best results avoid using any special unicode characters. Refer to this article. If no special characters are used the Message limit will be 160 characters for one message. If the character limit is exceeded the message will be sent as two SMS-s and now each message is maximum of 157 characters. Up to 3 messages can be sent at once. If you do need to use special character the limit for one SMS is 70 characters and 67 characters if you exceed one message.
`receiver`	Recipient of the message. Needs to be a phone number and include country code. Example: `37255555555`
`sender`	Name or number displayed for the recipient. Can be either fully numeric, or alphanumeric. Numeric: If sender starts with `+` and contains only numbers (`0123456789`), then it is treated as a numeric sender name. Numeric sender names can be up to 15 characters in length and your recipient can reply to that number, which allows for two way communication. Numeric sender names MUST begin with international prefix `+` and a country code (for example `+372` for Estonia). Examples of numeric sender names are: `+37251000000`, `+358500000000`. Please note that having spaces in your sender name, will change it to alphanumeric sender (for example, `+372 51000000` will be treated as alphanumeric sender). Alphanumeric: If sender contains any character other than `+0123456789`, then it will be treated as alphanumeric sender name. Alphanumeric sender names can contain all characters, but they can only be up to 11 characters in length. Recipients can not reply to alphanumeric sender names. Examples of alphanumeric sender names are name of a person or brand `John Smith`, `Apple`.
`conversion` optional	Optional parameter to specify conversion level for the `smstext`. 0 - no conversion is made, message is sent as is. 1 - Default conversion level. Some characters are converted but special characters still get through. 2 - Harsh conversion. All special characters are converted and what can't be converted are thrown out.
`deliverytime` optional	Used to specify the time Message should be sent. Needs to be in format `YYYY-MM-DD HH:II:SS` Example: `'deliverytime':'2019-12-30 15:30:00'`
`dlruri` optional	URL you want to receive delivery reports to. Delivery reports are responses from operators whether they were able to deliver a message or not. Since this may not be instant we will provide you an unique ID for every message so you can later match each message with a DLR. ID-s are in the UUID format. dlruri parameters: `id=%smsid%`, `dlr=%dlr%`, `receiver=%receiver%` (optional), `time=%time%` (optional) Example: `https://www.your-dlr-url.com?dlr=%dlr%&id=%smsid%` Our backend will replace these parameters with corresponding values, which you can test in the example below. Please note that we will make a GET requests to the URL that you specified.
`dlrid` optional	This parameter can only be used alongside `dlruri` parameter. The parameter is used to specify a custom ID for DLR-s that you can later match with your messages. If this parameter is not specified we will provide an ID in the UUID format for you.

DLR Interactive Example

Your DLRURI + parameters

A GET request will be made to

Responses

Success

After a request, a response is generated. If everything went smoothly you will be notified with a response. There are two possible success responses, one for when you did not include dlruri and one for when you did. The only difference is if you used dlruri parameter will will send you back an ID alongside the usual success response.

Example

Success response without dlruri

{
    "status": "Success",
    "description": "Your message was succesfully added to the queue"
}

Success response with dlruri

{
    "status": "Success",
    "description": "Your message was succesfully added to the queue",
    "dlr_id": "6d775630-54b0-4da2-b0b2-8f22f2d91e56"
}

Success response with a warning message

{
    "status": "Success",
    "description": "Your message was succesfully added to the queue",
    "warning": "Balance low, please contact us!"
}

Failure

If your request fails we will send you back a response with a description that might indicate to where the process failed and what needs to be done in order to solve the issue.

Example

Some examples of unsuccessful responses

The included dlruri was not in a correct URL format

{
    "message": "The given data was invalid.",
    "errors": {
        "dlruri": ["The dlruri format is invalid."]
    }
}

The receiver number was invalid

{
    "message": "Problem with validating numbers",
    "error": "Invalid number"
}

Examples

Examples of a request using all the available parameters.

Basic request

// Get cURL resource
$curl = curl_init();
// Set some options - we are passing in a useragent too here
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => [
        'Accept:application/json',
    ],
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'API_URL',
    CURLOPT_POST => 1,
    CURLOPT_POSTFIELDS => [
        'api_token' => 'YOUR_API_KEY',
        'smstext' => 'Message you want to send',
        'receiver' => '3725555555',
        'sender' => 'Bar',
        'conversion' => 2,
        'deliverytime' => '2019-12-30 15:30:00',
        'dlruri' => 'https://www.your-dlr-url.com',
        'dlrid' => 158,
    ]
]);
// Send the request & save response to $resp
$resp = curl_exec($curl);
// Close request to clear up some resources
curl_close($curl);

Request using x-www-form-urlencoded

$curl = curl_init();

    curl_setopt_array($curl, [
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/x-www-form-urlencoded',
            'Accept: application/json'
        ],
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_URL => 'API_URL',
        CURLOPT_POST => 1,
        CURLOPT_POSTFIELDS =>
            'api_token=YOUR_API_KEY&smstext=YOUR_MESSAGE&receiver=37255555555&sender=Bar&conversion=2&deliverytime=2019-12-30%2015:30:00&dlruri=https://www.your-dlr-url.com&dlrid=158',
    ]);

$resp = curl_exec($curl);

curl_close ($curl);

Request using query string

$curl = curl_init();

    curl_setopt_array($curl, [
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_HTTPHEADER => [
            'Accept: application/json',
        ],
        // Similar to x-www-form-urlencoded but we pass the parameters inside the URL itself
        CURLOPT_URL => 'https://API_URL/api?api_token=YOUR_API_KEY&smstext=YOUR_MESSAGE&receiver=37255555555&sender=Bar&conversion=2&deliverytime=2019-12-30%2015:30:00&dlruri=https://www.your-dlr-url.com&dlrid=158',
    ]);

$resp = curl_exec($curl);

curl_close ($curl);

Response

{
    "message": "Success",
    "description": "Your message was succesfully added to the queue",
    "dlr_id": "158"
}

Blacklist

Blacklist is used to store numbers you wish to exclude when sending messages.

NB! Adding a number to the blacklist does NOT mean that sending a message to the recipient gets automatically blocked. You will have to manually edit your send lists instead. This feature should be used just as a way to keep track of numbers, you wish to exclude in the future.

Get your blacklist

To retrieve your blacklist make a GET request to /api/blacklist. Remember to include your API token as a Bearer token in your headers.

PHP cURL example

// Get cURL resource
$curl = curl_init();
// Set some options - we are passing in a useragent too here
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => [
        'Accept:application/json',
        'Authorization: Bearer YOUR_API_KEY',
    ],
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'API_URL/api/blacklist',
    CURLOPT_CUSTOMREQUEST => 'GET',

]);
// Send the request & save response to $resp
$resp = curl_exec($curl);
// Close request to clear up some resources
curl_close($curl);

Response

{
    "response": "Success",
    "message": "Blacklist",
    "data": [
        {
            "id": 2222,
            "receiver": "37256666666",
            "created_at": "2021-31-12 10:47:14",
            "source": "api"
        },
        {
            "id": 3333,
            "receiver": "37255555555",
            "created_at": "2021-31-12 10:55:28",
            "source": "api"
        }
    ]
}

Add to the blacklist

To add a number to your blacklist make a POST request to api/blacklist/create. The request needs to include api_token and receiver parameters.

PHP cURL example

// Get cURL resource
$curl = curl_init();
// Set some options - we are passing in a useragent too here
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => [
        'Accept:application/json',
    ],
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'API_URL/api/blacklist/create',
    CURLOPT_POST => 1,
    CURLOPT_POSTFIELDS => [
        api_token => 'YOUR_API_KEY',
        receiver => '3725555555',
    ]
]);
// Send the request & save response to $resp
$resp = curl_exec($curl);
// Close request to clear up some resources
curl_close($curl);

Response

{
    "response": "Success",
    "message": "Number (37255555555) added to your blacklist"
}

Remove from blacklist

To remove a number from blacklist you need to make a POST request to /api/blacklist/delete/{id} where {id} is the ID of the number you are removing (you can get the ID-s by retrieving your blacklist as instructed above).

PHP cURL example

// Get cURL resource
$curl = curl_init();
// Set some options - we are passing in a useragent too here
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => [
        'Accept:application/json',
    ],
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'API_URL/api/blacklist/delete/2222',
    CURLOPT_POST => 1,
    CURLOPT_POSTFIELDS => [
        api_token => 'YOUR_API_KEY',
    ]
]);
// Send the request & save response to $resp
$resp = curl_exec($curl);
// Close request to clear up some resources
curl_close($curl);

Response

{
    "response": "Success",
    "message": "Number with id 2222 removed from blacklist"
}

Direct Messenger Two Factor Authentication API

Thank you for choosing Direct Messenger for your two factor authentication (2FA). This documentation will help you set up the API connection and explains different options available to you. If you are not sure whether our solution is the right one for you, check out our website messenger.ee for more information and don't hesitate to contact us on support@messenger.ee or +372 5556 2773.

What the API offers

This API offers the ability to generate and send out 2FA codes and authenticate them.

How to get started

1. Contact us

First you need to contact us on support@messenger.ee or +372 5556 2773 and set up an account.

2. Set up your connection using the API key we provided

Once you have an account you need to setup your connection to our server. We use an API key to authenticate all incoming requests, if you don't have an API key or you have lost it feel free to contact us.

Functions

Send 2FA code

Setup

The setup is fairly simple if you are familiar with POST requests.

The most basic request to send 2FA code through our API requires the following parameters:

api_token - Your API key
receiver - Where to send the 2FA code (phone number)

We will explain those parameters in more detail further down and go over some common mistakes/misunderstandings. Also there are optional parameters and options we will also cover below.

Here's what a basic request like that might look like:

POST https://API_URL/?api_token=YOUR_API_KEY&receiver=372555555555

This request will validate all the fields and on success will store them in our system and send out the message with the 2FA code or in case the validation failed give you back what caused the validation to fail.

Example

A basic request using PHP cURL

// Get cURL resource
$curl = curl_init();
// Set some options - we are passing in a useragent too here
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => [
        'Accept:application/json',
    ],
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'API_URL',
    CURLOPT_POST => 1,
    CURLOPT_POSTFIELDS => [
        'api_token' => 'YOUR_API_KEY',
        'receiver' => '372555555555',
    ]
]);
// Send the request & save response to $resp
$resp = curl_exec($curl);
// Close request to clear up some resources
curl_close($curl);

Javascript ajax example

var form = new FormData();
form.append("api_token", "YOUR_API_KEY");
form.append("receiver", "372555555555");

var settings = {
    url: "API_URL",
    method: "POST",
    timeout: 0,
    headers: {
        Accept: "application/json",
        "Content-Type": "application/x-www-form-urlencoded"
    },
    processData: false,
    mimeType: "multipart/form-data",
    contentType: false,
    data: form
};

$.ajax(settings).done(function(response) {
    console.log(response);
});

Available parameters

Attribute	Description	Default	Type of validation performed if enabled
`api_token`	Your API key, provided by us, used to authenticate each request.	Always required
`receiver`	The phone number you want to send the 2FA code to.	Always required	Numeric
`pin_length`	Length of the 2FA code.	Optional. Default length: 6	Integer. Between 4 and 20

Responses

Success

After a request, a response is generated. If everything went smoothly you will be notified with a success response.

The success response contains the sms status, the pin that was sent to the client and a pin_id that is used to verify 2FA codes.

PS! Keep the pin_id private. This is used to verify pin -s and should never be given out to your clients!

Example

{
    "message": "Success",
    "response": {
        "pin": "MP3KMJ",
        "pin_id": "BEN4KJIK62GNZDVFJCMG",
        "sms": "sent"
    }
}

Failure

If your request fails we will send you back a response with validation errors that you can use to figure out what went wrong.

Example

Some examples of unsuccessful responses

The receiver field was missing

{
    "message": "The given data was invalid.",
    "errors": {
        "receiver": ["The receiver field is required."]
    }
}

The receiver was an invalid phone number

{
    "message": "The given data was invalid.",
    "errors": {
        "receiver": ["Invalid number"]
    }
}

The pin_length was too long

{
    "message": "The given data was invalid.",
    "errors": {
        "pin_length": ["The pin length must be between 4 and 20."]
    }
}

Authenticate Users

The other feature the API offers is to authenticate users.

Setup

This request makes use of the POST method.

The most basic request to send data through our API requires the following parameters:

api_token - Your API key
pin - The 2FA code you are verifying
pin_id - The pin_id we sent you back with the initial 2FA request

Here's what a request might look like:

POST https://API_URL/?api_token=YOUR_API_KEY&pin=PIN_TO_AUTH&pin_id=PIN_ID

Example

Example requesting authentication.

Request

PHP cURL example

// Get cURL resource
$curl = curl_init();
// Set some options - we are passing in a useragent too here
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => [
        'Accept:application/json',
    ],
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'API_URL',
    CURLOPT_POST => 1,
    CURLOPT_POSTFIELDS => [
        'api_token' => 'YOUR_API_KEY',
        'pin' => 'PIN_TO_AUTH',
        'pin_id' => 'PIN_ID',
    ]
]);
// Send the request & save response to $resp
$resp = curl_exec($curl);
// Close request to clear up some resources
curl_close($curl);

Javascript ajax example

var form = new FormData();
form.append("api_token", "YOUR_API_KEY");
form.append("pin", "PIN_TO_AUTH");
form.append("pin_id", "PIN_ID");

var settings = {
    url: "API_URL",
    method: "POST",
    timeout: 0,
    headers: {
        Accept: "application/json",
        "Content-Type": "application/x-www-form-urlencoded"
    },
    processData: false,
    mimeType: "multipart/form-data",
    contentType: false,
    data: form
};

$.ajax(settings).done(function(response) {
    console.log(response);
});

Available parameters

Attribute	Description	Default	Type of validation performed
`api_token`	Your API key, provided by us, used to authenticate each request.	Always required
`pin`	2FA code that you are verifying.	Always required	String. Between 4 and 20
`pin_id`	Corresponding PIN ID we sent back with the initial request.	Always required	String. Size 20

Response

Success

The success response contains the auth_status status, the pin that was verified and pin_id that was used to verify the 2FA code.

PS! Keep the pin_id private.

Example

{
    "message": "Success",
    "response": {
        "auth_status": "User has been authenticated",
        "pin": "DXYMZO",
        "pin_id": "XOK4426WH1HLOG1BOUJK"
    }
}

Failure

If your request fails we will send you back a response with validation errors that you can use to determine what went wrong.

Example

Some examples of unsuccessful responses

The pin has already been authenticated

{
    "message": "The given data was invalid.",
    "errors": {
        "auth_status": ["The PIN has already been authenticated"]
    }
}

The pin provided is invalid

{
    "message": "The given data was invalid.",
    "errors": {
        "pin": ["PIN not found"]
    }
}

The pin and pin_id don't match

{
    "message": "The given data was invalid.",
    "errors": {
        "pin_id": ["PIN and PIN ID not matching"]
    }
}

The pin has expired (expires after 5 minutes)

{
    "message": "The given data was invalid.",
    "errors": {
        "expire_time": ["The PIN given has expired"]
    }
}

Personal API

Personal API helps you personalize your messages.

How to get started

Setup

The setup is fairly simple if you are familiar with POST requests. The most basic request to personalize your message using our API requires the following parameters:

api_token - Your API key
smstext - Message with variables that you want personalize
your variable - Whatever you set as your variable(s)

We will explain some of those parameters in more detail further down and go over some common mistakes/misunderstandings.

PS! Every request should use UTF-8 encoding

Here's what a basic request like that might look like:

POST https://API_URL/?api_token=YOUR_API_KEY&smstext=Foo%var%Bar&var=variable

Example

// Get cURL resource
$curl = curl_init();
// Set some options
curl_setopt_array($curl, [
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Content-Type: application/x-www-form-urlencoded'
    ],
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'API_URL',
    CURLOPT_POST => 1,
    CURLOPT_POSTFIELDS => [
        'api_token' => 'YOUR_API_KEY',
        'smstext' => 'Foo %var% Bar',
        'var' => 'variable'
    ]
]);
// Send the request & save response to $resp
$resp = curl_exec($curl);
// Close request to clear up some resources
curl_close($curl);

Available parameters

Attribute	Description
`api_token`	Your API key, provided by us, used to authenticate each request.
`smstext`	Text you want to personalize. Variables that you want to change are marked with two percent (%) symbols (%var%)
`var` custom	This is the variable you entered in your text. The attribute is customizable, meaning you can have any key as your variable (for example if your variable is `%my_custom_variable%` then you would set this attribute as `my_custom_variable` etc.) You can have as many variables as you want.
`id` optional	You can specify a custom id and this will be returned back to you with response. If this parameter is not specified we will provide an ID in the UUID format for you.
`receiver` optional	You can add a receiver (phone number) with your request. It can be useful to identify which custom message goes with what phone number. If this attribute is not set it will be returned as `null` in the response.

Responses

Success

After a request, a response is generated. If everything went smoothly you will be notified with a response.

Example

Success response

Parameters used:

parameter	value
`api_token`	YOUR_API_KEY
`smstext`	Foo %my_var% Bar %second_var%
`my_var`	variable
`second_var`	another variable
`receiver`	37255555555555

Response:

{
    "message": "Success",
    "id": "8f793eda-78c7-47f9-ad00-1b4fdc8e9ae6",
    "original_text": "Foo %my_var% Bar %second_var%",
    "formatted_text": "Foo variable Bar another variable",
    "receiver": "37255555555555"
}

Failure

If your request fails we will send you back a response with a description that might indicate to where the process failed and what needs to be done in order to solve the issue.

Example

No smstext was provided

{
    "message": "The given data was invalid.",
    "errors": {
        "smstext": ["The smstext field is required."]
    }
}