SMS Message

Sending SMS messages with Omnichannel API.


The easiest way to use Omnichannel API is with our official libraries. Libraries will take care of authentication, request validation and response handling.

Send a single SMS

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

// PM > Install-Package com.Messente.Omnichannel

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

namespace Example
{
    public class SendOmniMessageExample
    {
        public static void Main()
        {
            // Configure HTTP basic authorization: basicAuth
            Configuration.Default.Username = "MESSENTE_API_USERNAME";
            Configuration.Default.Password = "MESSENTE_API_PASSWORD";

            List messages = new List();
            var sms = new SMS(sender: "YOUR_PHONE_NUMBER", text: "Hello SMS!");

            messages.Add(sms);

            var apiInstance = new OmnimessageApi();
            var omnimessage = new Omnimessage(to: "RECIPIENT_PHONE_NUMBER", messages: messages);

            try
            {
                OmniMessageCreateSuccessResponse result = apiInstance.SendOmnimessage(omnimessage);
                Debug.Print("SMS successfully sent!");
                Debug.WriteLine(result);
            }
            catch (Exception e)
            {
                Debug.Print("There was a problem sending SMS: " + e.Message);
            }

        }
    }
}
    
curl https://api.messente.com/v1/omnimessage \
    -u MESSENTE_API_USERNAME:MESSENTE_API_PASSWORD \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{ "to": "RECIPIENT_PHONE_NUMBER", "messages": [{ "channel": "sms", "sender": "YOUR_PHONE_NUMBER", "text": "Happy messaging!" }] }'
    
// compile "com.messente.omnichannel:omnichannel-java"

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

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

        OmnimessageApi apiInstance = new OmnimessageApi();
        Omnimessage omnimessage = new Omnimessage();

        SMS sms = new SMS();
        sms.text("Happy messaging!");
        sms.sender("YOUR_PHONE_NUMBER");

        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("Exception when sending SMS message");
            e.printStackTrace();
        }
    }
}
    
// npm install omnichannel_api --save

const OmnichannelApi = require('omnichannel_api');

const defaultClient = OmnichannelApi.ApiClient.instance;

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

const api = new OmnichannelApi.OmnimessageApi();

const sms = OmnichannelApi.SMS.constructFromObject({
    text: "Happy messaging!",
    sender: 'YOUR_PHONE_NUMBER'
});

const omnimessage = OmnichannelApi.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-omnichannel-php

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

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

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

$apiInstance = new OmnimessageApi(new GuzzleHttp\Client(), $config);
$omnimessage = new Omnimessage(["to" => "RECIPIENT_PHONE_NUMBER"]);

$sms = new SMS(["text" => "Happy messaging!", "sender" => "YOUR_PHONE_NUMBER"]);
$omnimessage->setMessages([$sms]);

try {
    $result = $apiInstance->sendOmnimessage($omnimessage);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling OmknimessageApi->sendOmnimessage: ', $e->getMessage(), PHP_EOL;
}
    
# pip install omnichannel-api

from omnichannel import OmnimessageApi, SMS, Omnimessage, Configuration, ApiClient
from omnichannel.rest import ApiException

# API information from https://dashboard.messente.com/api-settings
configuration = Configuration()
configuration.username = "MESSENTE_API_USERNAME"
configuration.password = "MESSENTE_API_PASSWORD"

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

sms = SMS(sender="YOUR_PHONE_NUMBER", text="Happy messaging!" )

omnimessage = Omnimessage(to="RECIPIENT_PHONE_NUMBER", messages=(sms,))

try:
    response = api_instance.send_omnimessage(omnimessage)
    print("SMS successfully sent with id %s:" % response.omnimessage_id)
except ApiException as e:
    print("There was a problem sending message: %s\n" % e)
    
# gem 'omnichannel', '~> 1.0.0'

require 'omnichannel'

# setup authorization
Omnichannel.configure do |config|
    # Configure HTTP basic authorization: basicAuth
    config.username = 'MESSENTE_API_USERNAME'
    config.password = 'MESSENTE_API_PASSWORD'
end

api_instance = Omnichannel::OmnimessageApi.new

omnimessage = Omnichannel::Omnimessage.new
omnimessage.to = 'RECIPIENT_PHONE_NUMBER'
omnimessage.messages = [
    Omnichannel::SMS.new(
        {
            :sender => "YOUR_PHONE_NUMBER",
            :text => "Hello SMS!"
        }
    )
]

begin
    result = api_instance.send_omnimessage(omnimessage)
    puts "SMS successfully sent!"
rescue Omnichannel::ApiError => e
    puts "There was a problem sending SMS: #{e}"
    puts e.response_body
end
    

Response

{
  "messages": [
    {
      "channel": "sms",
      "message_id": "fr593ce7-68de-5e44-bc50-044a3ad0a7fa",
      "sender": "YOUR_PHONE_NUMBER"
    }
  ],
  "omnimessage_id": "632c6f3d-49d0-4a8f-5k2n-74023d31e51d",
  "to": "RECIPIENT_PHONE_NUMBER"
}

Use the omnimessage_id to keep track of the message delivery status.


Constructing Messages

There are few things to keep in mind when composing SMS messages.

Be aware of non-GSM friendly characters

A single SMS can contain 160 characters. However, SMS is built to use 7-bit GSM 03.38 character encoding set and this means that certain unicode characters (that are not in GSM character set) don't fit into the message.

If your message contains any characters not listed in the 7-bit alphabet then the message encoding will be set to UCS-2. With it, the message length is limited to 70 characters.

By default, the API will convert all non-GSM friendly characters to similar characters in GSM 03.38 encoding set. This allows you to send messages with non-unicode characters and not worry about the GSM specification.

You can turn the character replace feature off by configuring the autoconvert parameter in the message.

autoconvert: on(default)|full|off

Message Validity and Retry Policy

Messente forwards the SMS request to the operators, who, in turn, will retry SMS delivery for a minimum of 6 hours.

That being said, operators differ in their policies so some may retry SMS delivery up to 48 hours in total, starting with shorter retry intervals and switching to longer retry intervals towards the end. Some, on the other hand, may only retry for the required minimum of 6 hours indicated by us.


Receiving Messages

Receiving messages is currently not supported for SMS in the Omnichannel API.

We provide receiving messages feature with our SMS API. SMS API is a legacy service that will be deprecated in the future, but it's still safe to use for integration. We have no intention of removing support for this API any time soon.

Adding two-way message capabilities to Omnichannel API is a high priority to us. Let us know if you are interested in this feature.

SMPP protocol

Although we don't encourage it we also support SMPP protocol for sending SMS messages.

Learn how to set up SMPP integration.

Error example

{
  "errors": [
    {
      "code": "105",
      "detail": "Invalid or disallowed sender Messente",
      "source": "payload[sms][sender]",
      "title": "Invalid data"
    }
  ]
}
Key Value
title Error message
detail Longer description of the error message
code Machine-readable error code

101 Not found
102 Forbidden
103 Unauthorized
104 Invalid data
105 Internal Server Error
106 Missing data
107 Method not allowed
source Location in the request body for this error message