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.
- Sign up to Messente and receive your API keys (no credit card required).
- Verify your phone number as sender ID or request a branded Sender name.
- 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.
Follow this guide to send a message, once you have received your API keys.
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.
- Python
- Node
- PHP
- Java
- Ruby
- .NET
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
Install with composer
composer require messente/messente-api-php
Maven users
Allow fetching messente-api from jcenter by placing a settings.xml file to ~/.m2 maven folder containing the following:
<?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>4.2.0</version>
</dependency>
Now, you can install the library by running:
mvn clean install
Gradle users
Add jcenter repository to your project's build file:
repositories { jcenter() }
Also add the dependency to your project's build file:
dependencies { implementation 'com.messente.api:messente-api' }
Others
Firstly, 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
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.
Send a single SMS
Use the following example to send an SMS using Omnichannel API.
- Python
- Node
- PHP
- Java
- Ruby
- .NET
- cURL
# pip install messente-api
from pprint import pprint
from messente_api import (
OmnimessageApi,
SMS,
Omnimessage,
Configuration,
ApiClient,
OmnimessageMessagesInner,
)
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")
sms_inner = OmnimessageMessagesInner(sms)
omnimessage = Omnimessage(messages=[sms_inner], 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);
}
});
// 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.*;
import com.messente.auth.HttpBasicAuth;
import java.util.List;
// repositories { mavenCentral() }
// dependencies { implementation 'com.messente.api:messente-api' }
public class Main {
public static void main(String[] args) {
ApiClient apiClient = new ApiClient();
OmnimessageApi apiInstance = new OmnimessageApi(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)>");
OmnimessageMessagesInner smsOmnimessageInner = new OmnimessageMessagesInner(sms);
smsOmnimessageInner.setActualInstance(sms);
Omnimessage omnimessage = new Omnimessage();
omnimessage.setMessages(List.of(smsOmnimessageInner));
omnimessage.setTo("<recipient_phone_number>");
try {
OmniMessageCreateSuccessResponse result = apiInstance.sendOmnimessage(omnimessage);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling sendOmnimessage");
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
{
Username = "YOUR_MESSENTE_API_USERNAME",
Password = "YOUR_MESSENTE_API_PASSWORD"
};
var apiInstance = new OmnimessageApi(conf);
var sms = new SMS(sender: "<sender name (optional)>", text: "Hello SMS!");
OmnimessageMessagesInner smsOmnimessageInner = new OmnimessageMessagesInner(sms)
{
ActualInstance = sms
};
var omnimessage = new Omnimessage(
to: "<recipient_phone_number>",
messages: new List { smsOmnimessageInner }
);
try
{
var result = apiInstance.SendOmnimessage(omnimessage);
Console.WriteLine(result.ToJson());
}
catch (Exception e)
{
Console.WriteLine("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"
}
]
}'
Detailed API Reference on sending an SMS
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.
- Python
- Node
- PHP
- Java
- Ruby
- .NET
- cURL
# 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.
Learn more about the delivery status
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.
- Python
- Node
- PHP
- Java
- Ruby
- .NET
- cURL
# pip install messente-api
from pprint import pprint
from messente_api import (
OmnimessageApi,
SMS,
Omnimessage,
Configuration,
ApiClient,
Viber,
WhatsApp,
WhatsAppParameter,
WhatsAppComponent,
WhatsAppTemplate,
WhatsAppLanguage,
OmnimessageMessagesInner,
)
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")
viber_inner = OmnimessageMessagesInner(viber)
wa_parameters = [WhatsAppParameter(type="text", text="hello whatsapp")]
wa_component = WhatsAppComponent(type="body", parameters=wa_parameters)
wa_template = WhatsAppTemplate(
name="<template name>",
language=WhatsAppLanguage(code="<language_code>"),
components=[wa_component],
)
whatsapp = WhatsApp(sender="<sender name (optional)>", template=wa_template)
whatsapp_inner = OmnimessageMessagesInner(whatsapp)
sms = SMS(sender="<sender name (optional)>", text="hello sms")
sms_inner = OmnimessageMessagesInner(sms)
omnimessage = Omnimessage(
messages=(viber_inner, whatsapp_inner, sms_inner),
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 whatsAppText = MessenteApi.WhatsAppText.constructFromObject({
body: "hello whatsapp",
});
const whatsapp = MessenteApi.WhatsApp.constructFromObject({
text: whatsAppText,
});
const sms = MessenteApi.SMS.constructFromObject({
text: "hello sms",
sender: "<sender name (optional)>",
});
const omnimessage = MessenteApi.Omnimessage.constructFromObject({
messages: [viber, whatsapp, sms],
to: "<recipient_phone_number>",
});
api.sendOmnimessage(omnimessage, (error, data) => {
if (error) {
console.error(error);
} else {
console.log("API called successfully. Returned data: ", data);
}
});
// 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;
use Messente\Api\Model\WhatsAppText;
use Messente\Api\Model\WhatsApp;
$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)>',
]
);
$whatsAppText = new WhatsAppText(
[
'body' => 'hello whatsapp',
]
);
$whatsapp = new WhatsApp(
[
'text' => $whatsAppText,
'sender' => '<sender name (optional)>',
]
);
$sms = new SMS(
[
'text' => 'hello sms',
'sender' => '<sender name (optional)>',
]
);
$omnimessage->setMessages([$viber, $whatsapp, $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.*;
import com.messente.auth.HttpBasicAuth;
import java.util.Arrays;
import java.util.List;
// repositories { mavenCentral() }
// dependencies { implementation 'com.messente.api:messente-api' }
public class Main {
public static void main(String[] args) {
ApiClient apiClient = new ApiClient();
OmnimessageApi apiInstance = new OmnimessageApi(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)>");
OmnimessageMessagesInner viberOmnimessageInner = new OmnimessageMessagesInner(viber);
viberOmnimessageInner.setActualInstance(viber);
SMS sms = new SMS();
sms.text("hello sms");
sms.sender("<sender name (optional)>");
OmnimessageMessagesInner smsOmnimessageInner = new OmnimessageMessagesInner(sms);
smsOmnimessageInner.setActualInstance(sms);
WhatsAppParameter whatsAppParameter = new WhatsAppParameter();
whatsAppParameter.type("text");
whatsAppParameter.text("hello whatsapp");
WhatsAppComponent whatsAppComponent = new WhatsAppComponent();
whatsAppComponent.type("body");
whatsAppComponent.setParameters(List.of(whatsAppParameter));
WhatsAppTemplate whatsAppTemplate = new WhatsAppTemplate();
whatsAppTemplate.name("<template_name>");
whatsAppTemplate.language(new WhatsAppLanguage().code("<language_code>"));
whatsAppTemplate.setComponents(List.of(whatsAppComponent));
WhatsApp whatsApp = new WhatsApp();
whatsApp.sender("<sender name (optional)>");
whatsApp.template(whatsAppTemplate);
OmnimessageMessagesInner whatsAppOmnimessageInner = new OmnimessageMessagesInner(whatsApp);
whatsAppOmnimessageInner.setActualInstance(whatsApp);
Omnimessage omnimessage = new Omnimessage();
omnimessage.setMessages(
Arrays.asList(
smsOmnimessageInner,
viberOmnimessageInner,
whatsAppOmnimessageInner
)
);
omnimessage.setTo("<recipient_phone_number>");
try {
OmniMessageCreateSuccessResponse result = apiInstance.sendOmnimessage(omnimessage);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling sendOmnimessage");
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 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
{
Username = "YOUR_MESSENTE_API_USERNAME",
Password = "YOUR_MESSENTE_API_PASSWORD"
};
var apiInstance = new OmnimessageApi(conf);
var sms = new SMS(sender: "<sender name (optional)>", text: "Hello SMS!");
OmnimessageMessagesInner smsOmnimessageInner = new OmnimessageMessagesInner(sms)
{
ActualInstance = sms
};
var viber = new Viber(sender: "<sender name (optional)>", text: "Hello viber!");
OmnimessageMessagesInner viberOmnimessageInner = new OmnimessageMessagesInner(viber)
{
ActualInstance = viber
};
WhatsAppParameter whatsAppParameter = new WhatsAppParameter(
type: "text",
text: "hello whatsapp"
);
WhatsAppComponent whatsAppComponent = new WhatsAppComponent(
type: "body",
parameters: new List { whatsAppParameter }
);
WhatsAppTemplate whatsAppTemplate = new WhatsAppTemplate(
name: "<template_name>",
language: new WhatsAppLanguage(code: "<language_code>"),
components: new List { whatsAppComponent }
);
var whatsapp = new WhatsApp(
sender: "<sender name (optional)>",
template: whatsAppTemplate
);
OmnimessageMessagesInner whatsAppOmnimessageInner = new OmnimessageMessagesInner(whatsapp)
{
ActualInstance = whatsapp
};
var omnimessage = new Omnimessage(
to: "<recipient_phone_number>",
messages: new List {
smsOmnimessageInner,
viberOmnimessageInner,
whatsAppOmnimessageInner
}
);
try
{
var result = apiInstance.SendOmnimessage(omnimessage);
Console.WriteLine(result.ToJson());
}
catch (Exception e)
{
Console.WriteLine("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": "whatsapp",
"sender": "<sender name (optional)>",
"text": {
"body": "hello whatsapp"
}
},
{
"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.