Skip to main content

SMS Message

Sending SMS messages with Omnichannel API.


tip

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.

# 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)

The API will return a response with an omnimessage_id, as well as a message_id for each "sub-message" (fallback channel). You can use these IDs to track the delivery status of the message.

{
"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"
}

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. You can use our SMS calculator to check how many characters your message contains and how many SMS messages it will take to send it.

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.

info

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

autoconvert: on(default)|full|off

SMS Length Calculator

How to configure which characters get replaced

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.

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"
}
]
}
titleError message
detailLonger description of the error message
sourceLocation in the request body for this error message
codeMachine-readable error code: 101 - Not found 102 - Forbidden 103 - Unauthorized 104 - Internal Server Error 105 - Invalid data 106 - Missing data 107 - Method not allowed