Omnichannel Quickstart

Follow the guide to add SMS messages to your application in minutes.

Sending a message using the API is a three-step process.

  1. Sign up to Messente and receive your API keys (no credit card required).
  2. Verify your phone number as sender ID or request a branded Sender name.
  3. Using the API keys, make an API request with the desired message and recipient.

Upon sign up we will add you some free credits so you can test out the service immediately. With it you can send a few test messages.

Once you have received your API keys follow this guide to send a message.

1. Install a library

The fastest way to get started with the API is to use our official libraries.

Select your preferred programming language and follow the instructions.

With PIP

To install the API client library, simply execute:

pip install messente-api

Or with Setuptools

To install the API client library, simply execute:

python setup.py install --user

then import the package:

import messente_api

Take a look at the library's GitHub and PyPI pages.

Install with npm

npm i messente_api

Take a look at the library's GitHub and npm pages.

Install with composer

composer require messente/messente-api-php

Take a look at the library's GitHub and packagist pages.

Maven users

Allow fetching messente-api from jcenter by placing a settings.xml file to ~/.m2 maven folder containing

<?xml version="1.0" encoding="UTF-8" ?>
<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"
          xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <profiles>
    <profile>
      <id>bintray</id>
      <repositories>
        <repository>
          <id>central</id>
          <name>bintray</name>
          <url>https://jcenter.bintray.com</url>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </repository>
      </repositories>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>bintray</activeProfile>
  </activeProfiles>
</settings>

To install the API client library to your local Maven repository, add the dependency to your project's POM

<dependency>
  <groupId>com.messente.api</groupId>
  <artifactId>messente-api</artifactId>
  <version>$INSTALLED_VERSION</version>
</dependency>

and execute

mvn clean install

Gradle users

Add jcenter repository

repositories { jcenter() }

to your project's build file.

Also add the dependency to your project's build file

dependencies { implementation 'com.messente.api:messente-api' }

Others

At first generate the JAR by executing:

mvn package -Dmaven.javadoc.skip=true

Then manually install the following JARs:

  • target/messente-api-$VERSION_NUMBER.jar
  • target/messente-api-$VERSION_NUMBER-sources.jar
  • target/lib/*.jar

Take a look at the library's GitHub and Bintray pages.

Install the library with gem.

gem install messente_api

Take a look at the library's GitHub page and RubyGems pages.

Install using NuGet

Install-Package com.Messente.Api

Take a look at the library's GitHub and NuGet pages.

Let us know if your preferred language is not in the list

These libraries only contain Omnichannel and Phonebook API features. For other Messente features, you need to install different set of libraries. Libraries page contains the list of all our SDKs

2. Send a single SMS

Use the following example to send an SMS using Omnichannel API.

Detailed API Reference on sending an SMS

# pip install messente-api

from pprint import pprint
from messente_api import OmnimessageApi, SMS, Omnimessage, Configuration, ApiClient
from messente_api.rest import ApiException

configuration = Configuration()
configuration.username = "YOUR_MESSENTE_API_USERNAME"
configuration.password = "YOUR_MESSENTE_API_PASSWORD"

api_instance = OmnimessageApi(ApiClient(configuration))

sms = SMS(sender="<sender name (optional)>", text="hello sms")

omnimessage = Omnimessage(messages=tuple([sms]), to="<recipient_phone_number>")

try:
    response = api_instance.send_omnimessage(omnimessage)
    print(
        "Successfully sent Omnimessage with id: %s that consists of the following messages:"
        % response.omnimessage_id
    )
    for message in response.messages:
        pprint(message)
except ApiException as exception:
    print("Exception when sending an omnimessage: %s\n" % exception)
// npm i messente_api

const MessenteApi = require('messente_api');

const defaultClient = MessenteApi.ApiClient.instance;
const basicAuth = defaultClient.authentications['basicAuth'];
basicAuth.username = 'YOUR_MESSENTE_API_USERNAME';
basicAuth.password = 'YOUR_MESSENTE_API_PASSWORD';

const api = new MessenteApi.OmnimessageApi();

const sms = MessenteApi.SMS.constructFromObject({
  sender: '<sender name (optional)>',
  text: 'hello sms',
});

const omnimessage = MessenteApi.Omnimessage.constructFromObject({
  messages: [sms],
  to: '<recipient_phone_number>',
});

api.sendOmnimessage(omnimessage, (error, data) => {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ', data);
  }
});
<?php

// composer require messente/messente-api-php

require_once __DIR__.'/vendor/autoload.php';

use Messente\Api\Api\OmnimessageApi;
use Messente\Api\Model\Omnimessage;
use Messente\Api\Configuration;
use Messente\Api\Model\SMS;

$config = Configuration::getDefaultConfiguration()
    ->setUsername('YOUR_MESSENTE_API_USERNAME')
    ->setPassword('YOUR_MESSENTE_API_PASSWORD');

$apiInstance = new OmnimessageApi(
    new GuzzleHttp\Client(),
    $config
);

$omnimessage = new Omnimessage([
    'to' => '<recipient_phone_number>',
]);

$sms = new SMS(
    [
        'text' => 'hello sms',
        'sender' => '<sender name (optional)>',
    ]
);

$omnimessage->setMessages([$sms]);

try {
    $result = $apiInstance->sendOmnimessage($omnimessage);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling sendOmnimessage: ', $e->getMessage(), PHP_EOL;
}
import com.messente.ApiClient;
import com.messente.ApiException;
import com.messente.api.OmniMessageCreateSuccessResponse;
import com.messente.api.Omnimessage;
import com.messente.api.OmnimessageApi;
import com.messente.api.SMS;
import com.messente.auth.HttpBasicAuth;

import java.util.Arrays;

// repositories { jcenter() }
// dependencies { implementation 'com.messente.api:messente-api' }

public class Main {
    public static void main(String[] args) {
        ApiClient apiClient = new ApiClient();

        HttpBasicAuth basicAuth = (HttpBasicAuth) apiClient.getAuthentication("basicAuth");
        basicAuth.setUsername("YOUR_MESSENTE_API_USERNAME");
        basicAuth.setPassword("YOUR_MESSENTE_API_PASSWORD");

        SMS sms = new SMS();
        sms.text("hello sms");
        sms.sender("<sender name (optional)>");

        OmnimessageApi apiInstance = new OmnimessageApi(apiClient);
        Omnimessage omnimessage = new Omnimessage();
        omnimessage.setMessages(Arrays.asList(sms));
        omnimessage.setTo("<recipient_phone_number>");

        try {
            OmniMessageCreateSuccessResponse result = apiInstance.sendOmnimessage(omnimessage);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println(e.getResponseBody());
        }
    }
}
# gem install messente_api

require 'messente_api'

MessenteApi.configure do |config|
  config.username = 'YOUR_MESSENTE_API_USERNAME'
  config.password = 'YOUR_MESSENTE_API_PASSWORD'
end

api_instance = MessenteApi::OmnimessageApi.new
omnimessage = MessenteApi::Omnimessage.new
omnimessage.to = '<recipient_phone_number>'
omnimessage.messages = [
  MessenteApi::SMS.new(
    sender: '<sender name (optional)>',
    text: 'hello sms'
  )
]

begin
  result = api_instance.send_omnimessage(omnimessage)
  puts result
rescue MessenteApi::ApiError => e
  puts "Exception when calling send_omnimessage: #{e}"
  puts e.response_body
end
// PM > Install-Package com.Messente.Api

using System;
using System.Diagnostics;
using System.Collections.Generic;
using com.Messente.Api.Api;
using com.Messente.Api.Client;
using com.Messente.Api.Model;

namespace Example
{
    public class SendOmniMessageExample
    {
        public static void Main()
        {
            Configuration conf = new Configuration();
            conf.Username = "YOUR_MESSENTE_API_USERNAME";
            conf.Password = "YOUR_MESSENTE_API_PASSWORD";
            var apiInstance = new OmnimessageApi(conf);

            var sms = new SMS(
                sender: "<sender name (optional)>",
                text: "hello sms"
            );
            List<object> messages = new List<object>();
            messages.Add(sms);

            var omnimessage = new Omnimessage(
                to: "<recipient_phone_number>",
                messages: messages
            );

            try
            {
                var result = apiInstance.SendOmnimessage(omnimessage);
                Debug.WriteLine(result.ToJson());
            }
            catch (Exception e)
            {
                Debug.Print("Exception when calling SendOmnimessage: " + e.Message);

            }
        }
    }
}
curl -X POST \
  'https://api.messente.com/v1/omnimessage' \
  -u YOUR_MESSENTE_API_USERNAME:YOUR_MESSENTE_API_PASSWORD \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "<recipient_phone_number>",
    "messages": [
      {
        "channel": "sms",
        "sender": "<sender name (optional)>",
        "text": "hello sms"
      }
    ]
  }'

3. Get delivery reports

Messente tracks your sent message and reports status updates back to you.

To be able to view the status, you must add a callback URL to the message. Messente will use this URL to make HTTP POST requests, if there is a status update.

Here is a code snippet for you to test it out quickly.

Learn more about the delivery status

# 1. Get a temporary WebHook URL from https://webhook.site.
# Leave the website open. This is where you'll see your incoming delivery reports.

# 2. Edit the previous code example by adding the delivery URL to the request.
omnimessage = Omnimessage(
    messages=tuple([sms]), to="<recipient_phone_number>", dlr_url="<webhook_url>"
)

# 3. Send an SMS with the script and monitor the incoming requests on the webhook's website.
// 1. Get a temporary WebHook URL from https://webhook.site.
// Leave the website open. This is where you'll see your incoming delivery reports.

// 2. Edit the previous code example by adding the delivery URL to the request.
const omnimessage = MessenteApi.Omnimessage.constructFromObject({
  messages: [sms],
  to: '<recipient_phone_number>',
  dlr_url: '<webhook_url>',
});

// 3. Send an SMS with the script and monitor the incoming requests on the webhook's website.
<?php
// 1. Get a temporary WebHook URL from https://webhook.site.
// Leave the website open. This is where you'll see your incoming delivery reports.

// 2. Edit the previous code example by adding the delivery URL to the request.
$omnimessage = new Omnimessage([
  'to' => '<recipient_phone_number>',
  'dlrUrl' => '<webhook_url>',
]);

$sms = new SMS(
  [
      'text' => 'hello sms',
      'sender' => '<sender name (optional)>',
  ]
);

$omnimessage->setMessages([$sms]);

// 3. Send an SMS with the script and monitor the incoming requests on the webhook's website.
?>
// 1. Get a temporary WebHook URL from https://webhook.site.
// Leave the website open. This is where you'll see your incoming delivery reports.

// 2. Edit the previous code example by adding the delivery URL to the request.
omnimessage.setDlrUrl("<webhook_url>");

// 3. Send an SMS with the script and monitor the incoming requests on the webhook's website.
# 1. Get a temporary WebHook URL from https://webhook.site.
# Leave the website open. This is where you'll see your incoming delivery reports.

# 2. Edit the previous code example by adding the delivery URL to the request.
omnimessage.dlr_url = '<webhook_url>'

# 3. Send an SMS with the script and monitor the incoming requests on the webhook's website.
// 1. Get a temporary WebHook URL from https://webhook.site.
// Leave the website open. This is where you'll see your incoming delivery reports.

// 2. Edit the previous code example by adding the delivery URL to the request.
var omnimessage = new Omnimessage(
    to: "<recipient_phone_number>",
    messages: messages,
    dlrUrl: "<webhook_url>"
);

// 3. Send an SMS with the script and monitor the incoming requests on the webhook's website.
# 1. Get a temporary WebHook URL from https://webhook.site.
# Leave the website open. This is where you'll see your incoming delivery reports.

# 2. Edit the previous code example by adding the delivery URL to the request.
curl -X POST \
  'https://api.messente.com/v1/omnimessage' \
  -u YOUR_MESSENTE_API_USERNAME:YOUR_MESSENTE_API_PASSWORD \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "<recipient_phone_number>",
    "dlr_url": "<webhook_url>",
    "messages": [
      {
        "channel": "sms",
        "sender": "<sender name (optional)>",
        "text": "hello sms"
      }
    ]
  }'


# 3. Send an SMS with the script and monitor the incoming requests on the webhook's website.

4. Send a message to multiple channels with fallback

You can also send a single message to multiple channels by setting a fallback priority in the outgoing request. If the message recipient has not signed up or is not available on one of the channels, then Messente picks the next channel from the priority list.

In the following case, a message is sent to Viber first and if the user is not registered to Viber, then SMS is tried. Finally, if all the other options were unsuccessful, Messente sends an SMS.

# pip install messente-api

from pprint import pprint
from messente_api import (
    OmnimessageApi,
    SMS,
    Omnimessage,
    Configuration,
    ApiClient,
    Viber,
)
from messente_api.rest import ApiException

configuration = Configuration()
configuration.username = "YOUR_MESSENTE_API_USERNAME"
configuration.password = "YOUR_MESSENTE_API_PASSWORD"

api_instance = OmnimessageApi(ApiClient(configuration))

viber = Viber(sender="<sender name (optional)>", text="hello viber")

sms = SMS(sender="<sender name (optional)>", text="hello sms")

omnimessage = Omnimessage(
    messages=(viber, sms), to="<recipient_phone_number>"
)

try:
    response = api_instance.send_omnimessage(omnimessage)
    print(
        "Successfully sent Omnimessage with id: %s that consists of the following messages:"
        % response.omnimessage_id
    )
    for message in response.messages:
        pprint(message)
except ApiException as exception:
    print("Exception when sending an omnimessage: %s\n" % exception)
// npm i messente_api

const MessenteApi = require('messente_api');

const defaultClient = MessenteApi.ApiClient.instance;
const basicAuth = defaultClient.authentications['basicAuth'];
basicAuth.username = 'YOUR_MESSENTE_API_USERNAME';
basicAuth.password = 'YOUR_MESSENTE_API_PASSWORD';

const api = new MessenteApi.OmnimessageApi();

const viber = MessenteApi.Viber.constructFromObject({
  text: 'hello viber',
  sender: '<sender name (optional)>',
});

const sms = MessenteApi.SMS.constructFromObject({
  text: 'hello sms',
  sender: '<sender name (optional)>',
});

const omnimessage = MessenteApi.Omnimessage.constructFromObject({
  messages: [viber, sms],
  to: '<recipient_phone_number>',
});

api.sendOmnimessage(omnimessage, (error, data) => {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ', data);
  }
});
<?php

// composer require messente/messente-api-php

require_once __DIR__.'/vendor/autoload.php';

use Messente\Api\Api\OmnimessageApi;
use Messente\Api\Model\Omnimessage;
use Messente\Api\Configuration;
use Messente\Api\Model\SMS;
use Messente\Api\Model\Viber;

$config = Configuration::getDefaultConfiguration()
    ->setUsername('YOUR_MESSENTE_API_USERNAME')
    ->setPassword('YOUR_MESSENTE_API_PASSWORD');

$apiInstance = new OmnimessageApi(
    new GuzzleHttp\Client(),
    $config
);

$omnimessage = new Omnimessage([
    'to' => '<recipient_phone_number>',
]);

$viber = new Viber(
    [
        'text' => 'hello viber',
        'sender' => '<sender name (optional)>',
    ]
);



$sms = new SMS(
    [
        'text' => 'hello sms',
        'sender' => '<sender name (optional)>',
    ]
);

$omnimessage->setMessages([$viber, $sms]);

try {
    $result = $apiInstance->sendOmnimessage($omnimessage);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling sendOmnimessage: ', $e->getMessage(), PHP_EOL;
}
import com.messente.ApiClient;
import com.messente.ApiException;
import com.messente.api.OmniMessageCreateSuccessResponse;
import com.messente.api.Omnimessage;
import com.messente.api.OmnimessageApi;
import com.messente.api.SMS;
import com.messente.api.Viber;
import com.messente.auth.HttpBasicAuth;

import java.util.Arrays;

// repositories { jcenter() }
// dependencies { implementation 'com.messente.api:messente-api' }

public class Main {
    public static void main(String[] args) {
        ApiClient apiClient = new ApiClient();

        HttpBasicAuth basicAuth = (HttpBasicAuth) apiClient.getAuthentication("basicAuth");
        basicAuth.setUsername("YOUR_MESSENTE_API_USERNAME");
        basicAuth.setPassword("YOUR_MESSENTE_API_PASSWORD");

        Viber viber = new Viber();
        viber.text("hello viber");
        viber.sender("<sender name (optional)>");

        SMS sms = new SMS();
        sms.text("hello sms");
        sms.sender("<sender name (optional)>");

        OmnimessageApi apiInstance = new OmnimessageApi(apiClient);
        Omnimessage omnimessage = new Omnimessage();
        omnimessage.setMessages(Arrays.asList(viber, sms));
        omnimessage.setTo("<recipient_phone_number>");

        try {
            OmniMessageCreateSuccessResponse result = apiInstance.sendOmnimessage(omnimessage);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println(e.getResponseBody());
        }
    }
}
# gem install messente_api

require 'messente_api'

MessenteApi.configure do |config|
  config.username = 'YOUR_MESSENTE_API_USERNAME'
  config.password = 'YOUR_MESSENTE_API_PASSWORD'
end

api_instance = MessenteApi::OmnimessageApi.new
omnimessage = MessenteApi::Omnimessage.new
omnimessage.to = '<recipient_phone_number>'
omnimessage.messages = [
  MessenteApi::Viber.new(
    sender: '<sender name (optional)>',
    text: 'hello viber'
  ),
  MessenteApi::WhatsApp.new(
    sender: '<sender name (optional)>',
    text: MessenteApi::WhatsAppText.new(
      body: 'hello whatsapp!'
    )
  ),
  MessenteApi::SMS.new(
    sender: '<sender name (optional)>',
    text: 'hello sms'
  )
]

begin
  result = api_instance.send_omnimessage(omnimessage)
  puts result
rescue MessenteApi::ApiError => e
  puts "Exception when calling send_omnimessage: #{e}"
  puts e.response_body
end
// PM > Install-Package com.Messente.Api

using System;
using System.Diagnostics;
using System.Collections.Generic;
using com.Messente.Api.Api;
using com.Messente.Api.Client;
using com.Messente.Api.Model;

namespace Example
{
    public class SendOmniMessageExample
    {
        public static void Main()
        {
            Configuration conf = new Configuration();
            conf.Username = "YOUR_MESSENTE_API_USERNAME";
            conf.Password = "YOUR_MESSENTE_API_PASSWORD";
            var apiInstance = new OmnimessageApi(conf);

            var viber = new Viber(
                sender: "<sender name (optional)>",
                text: "hello viber"
            );


            var sms = new SMS(
                sender: "<sender name (optional)>",
                text: "hello sms"
            );

            List<object> messages = new List<object>
            {
                viber,
                sms
            };


            var omnimessage = new Omnimessage(
                to: "<recipient_phone_number>",
                messages: messages
            );

            try
            {
                var result = apiInstance.SendOmnimessage(omnimessage);
                Debug.WriteLine(result.ToJson());
            }
            catch (Exception e)
            {
                Debug.Print("Exception when calling SendOmnimessage: " + e.Message);

            }
        }
    }
}
curl -X POST \
  'https://api.messente.com/v1/omnimessage' \
  -u MESSENTE_API_USERNAME:MESSENTE_API_PASSWORD \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "<recipient_phone_number>",
    "messages": [
      {
        "channel": "viber",
        "sender": "<sender name (optional)>",
        "text": "hello viber"
      },
      {
        "channel": "sms",
        "sender": "<sender name (optional)>",
        "text": "hello sms"
      }
    ]
  }'

To start sending Viber messages please contact our support.

Next steps

Integrating SMS to your application should never take more than a day. Now that you have things set up it's time to get yourself a proper sender name.

Related topics

Everything about Sender Names

How to read Delivery Reports

Try out Two-Step Authentication

Check out our Pricing