Vox’s Programmable SMS API enables you to send and receive SMS messages to and from any country across the world through a simple REST API.

Get Started

In order to use Vox’s API, you need to have an account with Vox, please contact your Vox representative.


Vox's API uses user name and password to authenticate requests. You can create, retrieve and manage your API credentials by contacting your Vox Account Manager.
Each API call requires your API credentials as part of the JSON body:

username: string
password: string

SMS API Endpoint

Vox’s API uses HTTP verbs to understand if you want to create (POST) an object.

The format of the request must be JSON:

POST https://:8002/api

API Reference

This section provides detailed information about the request and the response parameters, the request status codes, and the message delivery statuses returned in the delivery reports.

Required Parameters

commandstringRequest type. Possible values: “submit”, "query", "mo". To send a message over HTTP, specify command=submit
anistringSender ID, can be numeric or alpha numeric. Alpha-numeric up to 32 symbols. Additional limitations can be caused by destination regulations.
dnisstringDestination number. Must be sent in international E.164 format (up to 15 digits allowed).
messagestringRepresents the content of the SMS message.
dataCodinginteger0: SMSC Default Alphabet (SMPP 3.4)/MC Specific (SMPP 5.0)
1: IA5 (CCITT T.50)/ASCII (ANSI X3.4)
3: Latin 1 (ISO-8859-1)
6: Cyrillic (ISO-8859-5)
7: Latin/Hebrew (ISO-8859-8)
8: UCS2 (ISO/IEC-10646)
10: ISO-2022-JP (Music Codes)
14: KS C 5601
longMessageModestringType of long message processing. The following values allowed: cut (default setup) - shortens the message leaving only first 140 bytes to be sentsingle_id_split  - split the message but return the message ID common for all segments

If the message contains characters outside the range of the GSM Standard and Extended tables, then the character encoding shall be set to 8 – UCS2 (dataCoding=8 as a query parameter). 

Response Parameters

message_idyesID string of the SMS message.
dnisyesIf the request contains more than one destination number – dnis. 

Note: The response is returned in JSON data format.

Callback Query Parameters

These are the Callback API parameters with which you can retrieve information about a sent SMS. Both GET and POST methods are supported. For setting and formatting Callback API parameters, please contact account manager to set it on your account. 

Parameter NameDescription
message_idMessage ID
delivery_timeTime when delivery report was generated
delivery_statusDelivery status
aniReceiver number
mccMobile country code
mncMobile network code
rateMessage cost 
result_codeError code 
country_nameCountry name

Delivery Reports

Delivery reports related to the sent SMS messages are available via callbacks to a dedicated callback URL. The callback URL is individual for each Vox customer – and can be set up with your Vox Account Manager. 

Delivery reports can also be queried and sent as an API response. 

GET request is used for querying the delivery report and the following parameters must be included:

Parameter NameDescription
messageIdMessage ID
commandRequest type. Must be set to “query” value.

All parameters are mandatory.

Message Delivery Status

These are the statuses returned in the delivery reports:

ENROUTEMessage is in routing stage. The status can be returned to the client if the message is in the SENT status
DELIVRDMessage has been delivered to the Subscriber
UNDELIVMessage cannot be delivered
ACCEPTDMessage is accepted by SMSC
REJECTDMessage was rejected by the carrier
EXPIREDMessage storage period expired
DELETEDMessage was deleted
UNKNOWNUnknown message status. Information on statuses is stored in the in-memory database for 24 hours (by default). Therefore, this status may be returned if the client has requested a status quite late and it was already removed from the memory.
IM_EXPDDelivery report was not received from the IM provider within the im_ttl timeout

Using the API

This section shows how to use the Vox’s SMS API. 

Send SMS

This example shows how to send an SMS saying “Hello, this is Vox!” with the default character encoding

to the recipient +381 63 XXXXXXX:

curl --location 'https://XXXXXXXXX:8002/api' \
--header 'Content-Type: application/json' \
--data '{
"ani":"Vox SMS",
"message":"Hello, this is Vox!"


    "message_id": "9be2ea-32028-e8cb8-11552-36b84-24825"

Send bulk SMS

This example shows how to send a BULK SMS saying “Hello, this is Vox 123!” with default character encoding to multiple recipients:

curl --location 'https://XXXXXXXXX:8002/api' \
--header 'Content-Type: application/json' \
--data '{
"ani":"Vox SMS",
"dnis":"38163XXXXXXX, 38164YYYYYYY",
"message":"Hello, this is Vox!"


[{"dnis":"38163XXXXXXX ","message_id":"5b4c46a8-8dc9-34b4-f55f-3bef56819305"},
{"dnis":"38164YYYYYYY ","message_id":"5b4c46a8-46bc-7uu6-4a16-7d4e5a0d14af"}]

Encoding of the Message

This example shows how to send an SMS with Unicode characters:

curl --location 'https://XXXXXXXXX:8002/api' \
--header 'Content-Type: application/json' \
--data '{
"ani":"Vox SMS",
"message":"Hello, this is Vox ❤️ !"

Send Long Messages

This example shows how to send an SMS with a text that exceeds the maximum allowed number of characters (160 for UTF-8, 70 for Unicode). 

curl --location 'https://XXXXXXXXX:8002/api' \
--header 'Content-Type: application/json' \
--data '{
"ani":"Vox SMS",
"message":"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"


    "message_id": "1175d2-11575-48a3a-03818-eedf2-16692"


SMPP Protocol

This section provides the necessary technical details for software architects and developers to create Short Message Peer-to-Peer (SMPP) clients to integrate with Vox’s SMPP interface. These details include integration requirements, supported methods, bind types, authentication requirements, data coding schemes, timers, delivery reports, error codes, and other message details.

Important: Vox is compliant with version 3.4 


SMPP is an open, industry standard protocol (see definition at Wikipedia) designed to simplify interconnections between various entities. SMPP also enables sending and receiving of short text messages (SMS) over the internet.

Connecting to Vox using the SMPP protocol requires a thorough understanding of SMPP. To learn more before reading further about the specifics of Vox SMPP integration, visit There you can also find reference documents for v3.4 of the specification (the versions that Vox supports).

Required SMPP Configuration

The following must be configured in each ESME:

SMPP gateway addressThe address of the Vox (server) the client will be connecting to.
PortThe port that the client will be connecting to and that Vox will be listening on.
UsernameIdentifies the client requesting to bind to Vox. Serves as a username.

Type: C-Octet String

Maximum Size: 16 octets.
PasswordAuthenticates the client requesting to bind to Vox

Type: C-Octet String

Maximum Size: 9 octets

Supported PDUs

Vox supports the following protocol data unit (PDU) commands:

ESME to Vox
Vox to ESME

Supported Session Types

Vox allows three types of ESME-initiated sessions:

Clients can enable up to all three session types, although persistent TRX binds are preferred. Contact your Vox representative to enable and configure these sessions.

Connection Information

SMPP gateway address:

Port: 2876
IP Address:


Each ESME requesting to bind to the Vox must provide a username for identification and a password for authentication.

Obtain these credentials by filling out Vox SMPP Interconnection form. Your Vox representative will share the latest version with you. Once your account has been created, they will provide you with your username (System ID) and password.

SMPP passwords cannot be recovered for you by Vox.

Password reset - You can reset the SMPP password by asking your Vox representative to do so for you.

Operational Requirements

Clients must follow these operational requirements when connecting to Vox via SMPP, in order for Vox to provide the highest level of quality, security, and connectivity.

Clients must:

Send SMS

  1. Setting up a session using a bind request

After entering the connectivity parameters provided by Vox (IP, port, username, password) into the SMPP client, a connection between your system and Vox will be established using one of the bind operations described above.

If you want to be able to send Outbound SMS and to receive the DLRs, you need either one transceiver session or one transmitter and one receiver session.

The same bandwidth will be available to you no matter how many sessions you establish.

  1. Acknowledge bind request

After Vox receives a bind request with the correct authentication parameters, a bind_resp will be issued and the session is available for communication.

  1. Submitting a message

Messages are submitted to Vox using the submit_sm operation. The submit_sm operation and the PDU are described in detail in the SMPP 3.4 documentation.

  1. Acknowledge submitted message

After Vox received a correct submit_sm request, a submit_sm_resp will be issued. The submit_sm_resp contains the message ID in the message_id parameter, which is a unique identifier for each message. It may vary in format and length.

The submission of the message to Vox is finalized with the issuing of the submit_sm_resp. The messages are stored in the Vox SMSC and will be delivered to the receiver. If the initial delivery attempt is not successful – e.g. the receiving mobile phone is turned off – further attempts of delivering the message will be made. The message will be kept in the Vox SMSC for up to 48 hours, after which it will expire.

  1. Submitting a delivery receipt (DLR), optional

Once a message reaches a final status (delivered, cannot be delivered, expired), Vox creates a delivery receipt if this is requested in the initial submit_sm. The DLR will be submitted to you via an existing receiver or transceiver session using the deliver_sm operation. The delivery receipt itself is included in the text parameter of the deliver_sm PDU.

  1. Acknowledge submitted DLR

You need to acknowledge the receipt of a deliver_sm with a deliver_sm_resp, otherwise Vox will keep on resending the deliver_sm.

Receive SMS

  1. Setting up a session using a bind request

After entering the connectivity parameters provided by Vox (IP, port, username, password) into the SMPP client, a connection between your system and Vox will be established using one of the bind operations described above. For receiving SMS from Vox, a receiver or transceiver session is needed. The session needs to stay open in order for us to be able to deliver the messages to you.

  1. Acknowledge bind request

After Vox receives a bind request with the correct authentication, a bind_resp will be issued and the session is available for communication.

  1. Receiving a message

When Vox receives a message on one of the inbound numbers assigned to you, it is relayed to your platform using the deliver_sm operation. For details on the deliver_sm operation and the PDU, please refer to the SMPP 3.4 documentation.

  1. Acknowledge received message

After you receive a deliver_sm, you need to acknowldege the receipt by answering with a deliver_sm_resp. Otherwise, we will resend the deliver_sm.