Direct Messenger Campaign API

Thank you for choosing Direct Messenger for your consumer campaign. 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 meryl@messenger.ee or +372 5556 2773.

What the API offers

This API offers the ability to store and validate the campaign data. In addition to storing data you can also query your campaign winners. Outside of the API we offer a full statistics environment complete with raffle functionality.

How to get started

1. Contact us

First you need to contact us on meryl@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

Submit data

Setup

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

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

  • api_token - Your API key
  • game - The campaign ID we provide for you
  • first_name - First name of the person registering
  • last_name - Last name of the person registering
  • code - Code the person is registering (e.g. receipt numer)
  • email - Email of the person registering
  • privacy - Whether the person registering has checked the 'privacy policy' checkbox or not

We will explain some of those parameters in more detail further down and go over some common mistakes/misunderstandings. Also there are many optinal 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&game=YOUR_CAMPAIGN_ID&first_name=John&slast_name=Smith&code=ABC123&email=johnsmith@gmail.com&privacy=on

This request will validate all the fields and on success will store them in our system 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',
        game => 'YOUR_CAMPAIGN_ID',
        first_name => 'John',
        last_name => 'Smith',
        code => 'ABC123',
        email => 'johnsmith@gmail.com',
        privacy => 'on'
    ]
]);
// 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("first_name", "John");
form.append("last_name", "Smith");
form.append("code", "ABC123");
form.append("game", "YOUR_CAMPAIGN_ID");
form.append("email", "johnsmith@gmail.com");
form.append("privacy", "on");
form.append("api_token", "YOUR_API_KEY");

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
game Your campaign ID provided by us, used to associate the data with the correct campaign. Always required
first_name First name of the person registering in your consumer campaign Validated by default Required
last_name Last name of the person registering in your consumer campaign Validated by default Required
code Code the person is registering, usually a receipt number Validated by default Required. Must be unique for the person
phone Phone number of the person registering Not validated by default Required. Phone number format validation
email Email of the person registering Validated by default Required. Email format validation
city Location specified by person registering. Usually used for delivering prizes. Often used for storing parcel terminal locations (Omniva, SmartPOST etc) Not validated by default Required
rules Whether the person registering accepted the campaign rules or not Not validated by default Required
privacy Whether the person registering accepted the campaign privacy policy or not Validated by default Required
age Age of the person registering Not validated by default Required. Must be between 5 and 120
address Address of the person registering Not validated by default Required
zip Zip/postal code of the person registering Not validated by default Required. Must be 5 digits
validator_code The code used to toggle various validation fields. We go more in depth on the validator code down below Optional parameter
lang Specify the languaeg/country the registration is made from. Useful for multi-language campaigns. Available language options: et - Estonian, en - English, lt - Lithuanian, lv - Latvian, fi - Finnish, ru - Russian, ua - Ukrainian. Everything else will default to English Optional parameter

Validator code

Validator code is used enable/disable validation separately on each field. Not all campaigns are similar and sometimes some fields are not required on one campaign but are required on another. Sometimes the client wants to validate all the data on their side and double validation isn't needed. For those reasons we offer a validator code that you can use to choose which fields are validated and which are not. We offer a code generator down below to help you generate the code, just choose the fields you want validated and copy the code and send it with the validator_code parameter.
Note that if your campaign uses only the fields that are validated by default this parameter is optional.

Generator

Responses

Success

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

Example
{
    "Description": "Registration successful",
    "message": "success"
}

Failure

If your request fails we will send you back a response with validation errors that you can use to indicate to your users what they did wrong.

Example

Some examples of unsuccessful responses

The first_name field was missing and email was not formatted correctly


    "errors": {
        "first_name": [
            {
                "err": "NOFIRSTNAME",
                "field": "first_name",
                "message": "First name cannot be empty"
            }
        ],
        "email": [
            {
                "err": "INVALIDEMAIL",
                "field": "email",
                "message": "Invalid email format"
            }
        ]
    }
}

The code was already used

{
    "errors": {
        "code": [
            {
                "err": "DUPLICATECODE",
                "field": "code",
                "message": "Code must be unique"
            }
        ]
    }
}

Error messages

All possible validation error messages

first_name

"first_name" : {
    "required" : {
        "err" : "NOFIRSTNAME",
        "field" : "first_name",
        "message" : "First name cannot be empty"
    },
},

last_name

"last_name" : {
    "required" : {
        "err" : "NOLASTNAME",
        "field" : "last_name",
        "message" : "Last name cannot be empty"
    },
},

code

"code" : {
    "required" : {
        "err" : "NOCODE",
        "field" : "code",
        "message" : "Code cannot be empty"
    },
    "unique" : {
        {
            "err" : "DUPLICATECODE",
            "field" : "code",
            "message" : "Code must be unique"
        },
    },
},

phone

"phone" : {
    "required" : {
        "err" : "NOPHONE",
        "field" : "phone",
        "message" : "Phone number cannot be empty"
    },
    "format" : {
        {
            "err" : "INVALIDPHONE",
            "field" : "phone",
            "message" : "Invalid phone number format"
        },
    },
},

email

"email" : {
    "required" : {
        "err" : "NOEMAIL",
        "field" : "email",
        "message" : "Email cannot be empty"
    },
    "email" : {
        "err" : "INVALIDEMAIL",
        "field" : "email",
        "message" : "Invalid email format"
    },
},

city

"city" : {
    "required" : {
        "err" : "NOCITY",
        "field" : "city",
        "message" : "City cannot be empty"
    },
},

rules

"rules" : {
    "required" : {
        "err" : "NORULES",
        "field" : "rules",
        "message" : "Rules cannot be empty"
    },
},

privacy

"privacy" : {
    "required" : {
        "err" : "NOPRIVACY",
        "field" : "privacy",
        "message" : "Privacy cannot be empty"
    },
},

age

"age" : {
    "required" : {
        "err" : "NOAGE",
        "field" : "age",
        "message" : "Age cannot be empty"
    },
    "numeric" : {
        "err" : "NUMERICAGE",
        "field" : "age",
        "message" : "Age has to be a number"
    },
    "between" : {
        "err" : "INVALIDAGE",
        "field" : "age",
        "message" : "Age has to be between 5 and 120"
    },
},

address

"address" : {
    "required" : {
        "err" : "NOADDRESS",
        "field" : "address",
        "message" : "Address cannot be empty"
    },
},

zip

"zip" : {
    "required" : {
        "err" : "NOZIP",
        "field" : "zip",
        "message" : "Zip cannot be empty"
    },
    "digits" : {
        "err" : "INVALIDZIP",
        "field" : "zip",
        "message" : "Zip has to be 5 digits"
    }
}

Query winners

The other feature the API offers is to query the winners for your campaign.

Setup

This request makes use of the GET method.

For the request you need to set your game id as a GET parameter and also set the Authorization header.

Here's what a request might look like:

Http Headers:
Authorization: Bearer YOUR_API_KEY

Request:
GET https://API_URL/?game=YOUR_GAME_ID

Example

Example requesting winners.

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 => [
        'Authorization:Bearer YOUR_API_KEY',
    ],
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'API_URL?game=YOUR_GAME_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();
var settings = {
  "url": "https://API_URL/?game=YOUR_GAME_ID",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  "processData": false,
  "mimeType": "multipart/form-data",
  "contentType": false,
  "data": form
};

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

Response

{
    "0": {
        "prize": "name_of_the_prize",
        "first_name": "John",
        "last_name": "Smith",
        "date": "2020-01-29 18:57:02"
    },
    "1": {
        "prize": "name_of_the_prize",
        "first_name": "Jane",
        "last_name": "Doe",
        "date": "2020-01-30 12:41:36"
    },
}