Phonebook API [BETA]

Phonebook API enables you to use our blacklisting feature to make sure you're not sending any unwanted messages.

API Setup

Omnichannel API requests are made to the following server:

https://api.messente.com/

Authentication and making requests

Requests are done with JSON body and HTTP Basic Auth is used for authentication.

Request headers example

Accept: application/json
Content-Type: application/json
Authentication: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Development libraries

You can use our development libraries to help you get started quickly.

We have libraries available for the following programming languages:

Error handling

HTTP response code Error code Description
400 201 Missing required parameter
401 202 Authentication error
404 203 Missing resource error
409 204 Duplicate object detected
4XX (not above) 244 Client error
500 205 General error
{
    "errors": [
        {
            "code": "202",
            "detail": "User e9fbc8a9a9845 does not exist",
            "title": "Unauthorized"
        }
    ]
}

Blacklist

Blacklist is a list of numbers that is tied to one specific Account. All messages sent using any API credentials from this account, are passed through this list. If the number is in the list, the message is not sent. It applies both to API calls and messages sent from the Dashboard.

List all numbers

GET /v1/phonebook/blacklist

Successful Response

HTTP/1.1 200

{
  "phoneNumbers": [
    "+37251000000",
    "+37251000001"
  ]
}
# pip install phonebook-api

from phonebook_api import (BlacklistApi, ApiClient, Configuration)
from phonebook_api.rest import ApiException

# Configure HTTP basic authorization: basicAuth
configuration = Configuration()
configuration.username = 'YOUR_MESSENTE_API_USERNAME'
configuration.password = 'YOUR_MESSENTE_API_PASSWORD'

# create an instance of the API class
api_instance = BlacklistApi(ApiClient(configuration))

try:
    response = api_instance.fetch_blacklist()
    print(response)
except ApiException as e:
    print("Exception when calling fetch_blacklist: %s\n" % e)
    
// npm install phonebook_api --save

const PhonebookApi = require('phonebook_api');

const defaultClient = PhonebookApi.ApiClient.instance;

// Configure HTTP basic authorization: basicAuth
const basicAuth = defaultClient.authentications['basicAuth'];
basicAuth.username = 'YOUR_MESSENTE_API_USERNAME';
basicAuth.password = 'YOUR_MESSENTE_API_PASSWORD';

const api = new PhonebookApi.BlacklistApi();

const callback = function(error, data, response) {
	if (error) {
		console.error(error['response']['body']);
	} else {
		console.log('API called successfully. \n', response.body);
	}
};

api.fetchBlacklist(callback);
// composer require messente/messente-phonebook-php

require_once(__DIR__ . '/vendor/autoload.php');
use Messente\Phonebook\Configuration;
use Messente\Phonebook\Api\BlacklistApi;
use GuzzleHttp\Client;

// Configure HTTP basic authorization: basicAuth
$config = Configuration::getDefaultConfiguration()
    ->setUsername('YOUR_MESSENTE_API_USERNAME')
    ->setPassword('YOUR_MESSENTE_API_PASSWORD');

$apiInstance = new BlacklistApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new Client(),
    $config
);

try {
    $response = $apiInstance->fetchBlacklist();
    echo $response;
} catch (Exception $e) {
    echo 'Exception when calling fetchBlacklist: ', $e->getMessage(), PHP_EOL;
}
    
// compile "com.messente.phonebook:phonebook-java"

public class BlacklistApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure HTTP basic authorization: basicAuth
        HttpBasicAuth basicAuth = (HttpBasicAuth) defaultClient.getAuthentication("basicAuth");
        basicAuth.setUsername("YOUR_MESSENTE_API_USERNAME");
        basicAuth.setPassword("YOUR_MESSENTE_API_PASSWORD");

        BlacklistApi apiInstance = new BlacklistApi();

        try {
            FetchBlacklistSuccess response = apiInstance.fetchBlacklist();
            System.out.println(response);
        } catch (ApiException e) {
            System.err.println("Exception when calling fetchBlacklist");
            e.printStackTrace();
        }
    }
}
    
curl https://api.messente.com/v1/phonebook/blacklist \
    -u MESSENTE_API_USERNAME:MESSENTE_API_PASSWORD \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
    

Add a number

POST /v1/phonebook/blacklist

{
  "phoneNumber": "+37251000000"
}

Successful Response

HTTP/1.1 204
# pip install phonebook-api

from phonebook_api import (BlacklistApi, ApiClient, Configuration)
from phonebook_api.rest import ApiException

# Configure HTTP basic authorization: basicAuth
configuration = Configuration()
configuration.username = 'YOUR_MESSENTE_API_USERNAME'
configuration.password = 'YOUR_MESSENTE_API_PASSWORD'

# create an instance of the API class
api_instance = BlacklistApi(ApiClient(configuration))

try:
    api_instance.add_to_blacklist({'phoneNumber': '+37255555555'})
except ApiException as e:
    print("Exception when calling add_to_blacklist: %s\n" % e)
    
// npm install phonebook_api --save

const PhonebookApi = require('phonebook_api');

const defaultClient = PhonebookApi.ApiClient.instance;

// Configure HTTP basic authorization: basicAuth
const basicAuth = defaultClient.authentications['basicAuth'];
basicAuth.username = 'YOUR_MESSENTE_API_USERNAME';
basicAuth.password = 'YOUR_MESSENTE_API_PASSWORD';

const api = new PhonebookApi.BlacklistApi();

const callback = function(error, data, response) {
	if (error) {
		console.error(error['response']['body']);
	} else {
		console.log('API called successfully. \n', response.body);
	}
};

api.addToBlacklist({phoneNumber: '+37255555555'}, callback);
	
// composer require messente/messente-phonebook-php

require_once(__DIR__ . '/vendor/autoload.php');
use Messente\Phonebook\Configuration;
use Messente\Phonebook\Api\BlacklistApi;
use GuzzleHttp\Client;

// Configure HTTP basic authorization: basicAuth
$config = Configuration::getDefaultConfiguration()
    ->setUsername('YOUR_MESSENTE_API_USERNAME')
    ->setPassword('YOUR_MESSENTE_API_PASSWORD');

$apiInstance = new BlacklistApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new Client(),
    $config
);

try {
    $apiInstance->addToBlacklist(['phoneNumber' => '+37255555555']);
} catch (Exception $e) {
    echo 'Exception when calling addToBlacklist: ', $e->getMessage(), PHP_EOL;
}
    
// compile "com.messente.phonebook:phonebook-java"

public class BlacklistApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure HTTP basic authorization: basicAuth
        HttpBasicAuth basicAuth = (HttpBasicAuth) defaultClient.getAuthentication("basicAuth");
        basicAuth.setUsername("YOUR_MESSENTE_API_USERNAME");
        basicAuth.setPassword("YOUR_MESSENTE_API_PASSWORD");

        BlacklistApi apiInstance = new BlacklistApi();

        try {
            apiInstance.addToBlacklist(new NumberToBlacklist().phoneNumber("+37255555555"));
        } catch (ApiException e) {
            System.err.println("Exception when calling addToBlacklist");
            e.printStackTrace();
        }
    }
}
    
curl https://api.messente.com/v1/phonebook/blacklist \
    -u MESSENTE_API_USERNAME:MESSENTE_API_PASSWORD \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{ "phoneNumber": "+37255555555" }'
    

Delete a phone number

DELETE /v1/phonebook/blacklist/{phone-number}

Successful Response

HTTP/1.1 204
# pip install phonebook-api

from phonebook_api import (BlacklistApi, ApiClient, Configuration)
from phonebook_api.rest import ApiException

# Configure HTTP basic authorization: basicAuth
configuration = Configuration()
configuration.username = 'YOUR_MESSENTE_API_USERNAME'
configuration.password = 'YOUR_MESSENTE_API_PASSWORD'

# create an instance of the API class
api_instance = BlacklistApi(ApiClient(configuration))

try:
    api_instance.remove_from_blacklist('+37255555555')
except ApiException as e:
    print("Exception when calling remove_from_blacklist: %s\n" % e)
    
// npm install phonebook_api --save

const PhonebookApi = require('phonebook_api');

const defaultClient = PhonebookApi.ApiClient.instance;

// Configure HTTP basic authorization: basicAuth
const basicAuth = defaultClient.authentications['basicAuth'];
basicAuth.username = 'YOUR_MESSENTE_API_USERNAME';
basicAuth.password = 'YOUR_MESSENTE_API_PASSWORD';

const api = new PhonebookApi.BlacklistApi();

const callback = function(error, data, response) {
	if (error) {
		console.error(error['response']['body']);
	} else {
		console.log('API called successfully. \n', response.body);
	}
};

api.removeFromBlacklist('+37255555555', callback);
// composer require messente/messente-phonebook-php

require_once(__DIR__ . '/vendor/autoload.php');
use Messente\Phonebook\Configuration;
use Messente\Phonebook\Api\BlacklistApi;
use GuzzleHttp\Client;

// Configure HTTP basic authorization: basicAuth
$config = Configuration::getDefaultConfiguration()
    ->setUsername('YOUR_MESSENTE_API_USERNAME')
    ->setPassword('YOUR_MESSENTE_API_PASSWORD');

$apiInstance = new BlacklistApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new Client(),
    $config
);

try {
    $apiInstance->removeFromBlacklist('+37255555555');
} catch (Exception $e) {
    echo 'Exception when calling removeFromBlacklist: ', $e->getMessage(), PHP_EOL;
}
    
// compile "com.messente.phonebook:phonebook-java"

public class BlacklistApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure HTTP basic authorization: basicAuth
        HttpBasicAuth basicAuth = (HttpBasicAuth) defaultClient.getAuthentication("basicAuth");
        basicAuth.setUsername("YOUR_MESSENTE_API_USERNAME");
        basicAuth.setPassword("YOUR_MESSENTE_API_PASSWORD");

        BlacklistApi apiInstance = new BlacklistApi();

        try {
            apiInstance.removeFromBlacklist("+37255555555");
        } catch (ApiException e) {
            System.err.println("Exception when calling removeFromBlacklist");
            e.printStackTrace();
        }
    }
}
    
curl https://api.messente.com/v1/phonebook/blacklist/PHONE_NUMBER \
    -u MESSENTE_API_USERNAME:MESSENTE_API_PASSWORD \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
    -X "DELETE"