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.
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: stringVox’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/apiThis 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.
| Parameter | Type | Description |
|---|---|---|
| command | string | Request type. Possible values: “submit”, "query", "mo". To send a message over HTTP, specify command=submit |
| ani | string | Sender ID, can be numeric or alpha numeric. Alpha-numeric up to 32 symbols. Additional limitations can be caused by destination regulations. |
| dnis | string | Destination number. Must be sent in international E.164 format (up to 15 digits allowed). |
| message | string | Represents the content of the SMS message. |
| dataCoding | integer | 0: 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 |
| longMessageMode | string | Type 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).
| Parameter | Mandatory | Description |
|---|---|---|
| message_id | yes | ID string of the SMS message. |
| dnis | yes | If the request contains more than one destination number – dnis. |
Note: The response is returned in JSON data format.
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 Name | Description |
|---|---|
| message_id | Message ID |
| delivery_time | Time when delivery report was generated |
| delivery_status | Delivery status |
| ani | Receiver number |
| mcc | Mobile country code |
| mnc | Mobile network code |
| rate | Message cost |
| result_code | Error code |
| country_name | Country name |
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 Name | Description |
|---|---|
| messageId | Message ID |
| username | Login |
| password | Password |
| command | Request type. Must be set to “query” value. |
All parameters are mandatory.
These are the statuses returned in the delivery reports:
| Status | Description |
|---|---|
| ENROUTE | Message is in routing stage. The status can be returned to the client if the message is in the SENT status |
| DELIVRD | Message has been delivered to the Subscriber |
| UNDELIV | Message cannot be delivered |
| ACCEPTD | Message is accepted by SMSC |
| REJECTD | Message was rejected by the carrier |
| EXPIRED | Message storage period expired |
| DELETED | Message was deleted |
| UNKNOWN | Unknown 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_EXPD | Delivery report was not received from the IM provider within the im_ttl timeout |
This section shows how to use the Vox’s SMS API.
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 '{
"username":"xxxxxx",
"password":"yyyyy",
"command":"submit",
"ani":"Vox SMS",
"dnis":"38163XXXXXXX",
"message":"Hello, this is Vox!"
}'
Response:
{
"message_id": "9be2ea-32028-e8cb8-11552-36b84-24825"
}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 '{
"username":"xxxxxx",
"password":"yyyyy",
"command":"submit",
"ani":"Vox SMS",
"dnis":"38163XXXXXXX, 38164YYYYYYY",
"message":"Hello, this is Vox!"
}'
Response:
[{"dnis":"38163XXXXXXX ","message_id":"5b4c46a8-8dc9-34b4-f55f-3bef56819305"},
{"dnis":"38164YYYYYYY ","message_id":"5b4c46a8-46bc-7uu6-4a16-7d4e5a0d14af"}]This example shows how to send an SMS with Unicode characters:
curl --location 'https://XXXXXXXXX:8002/api' \
--header 'Content-Type: application/json' \
--data '{
"username":"xxxxxx",
"password":"yyyyy",
"command":"submit",
"ani":"Vox SMS",
"dnis":"38163XXXXXXX",
"dataCoding":"8",
"message":"Hello, this is Vox ❤️ !"
}'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 '{
"username":"xxxxxx",
"password":"yyyyy",
"command":"submit",
"ani":"Vox SMS",
"dnis":"38163XXXXXXX",
"longMessageMode":"single_id_split",
"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"
}'
Response:
Response:
{
"message_id": "1175d2-11575-48a3a-03818-eedf2-16692"
}
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 smpp.org. There you can also find reference documents for v3.4 of the specification (the versions that Vox supports).
The following must be configured in each ESME:
| Feature | Description |
|---|---|
| SMPP gateway address | The address of the Vox (server) the client will be connecting to. |
| Port | The port that the client will be connecting to and that Vox will be listening on. |
| Username | Identifies the client requesting to bind to Vox. Serves as a username. Type: C-Octet String Maximum Size: 16 octets. |
| Password | Authenticates the client requesting to bind to Vox Type: C-Octet String Maximum Size: 9 octets |
Vox supports the following protocol data unit (PDU) commands:
| ESME to Vox | Vox to ESME |
|---|---|
| bind_transceiver | bind_transceiver_resp |
| bind_transmitter | bind_transmitter_resp |
| bind_receiver | bind_receiver_resp |
| submit_sm | submit_sm_resp |
| enquire_link | enquire_link_resp |
| enquire_link_resp | enquire_link |
| deliver_sm_resp | deliver_sm |
| unbind | unbind_resp |
| unbind_resp | unbind |
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.
SMPP gateway address: sms.voxcarrier.com
Port: 2876
IP Address: 163.172.233.79
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.
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:
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.
After Vox receives a bind request with the correct authentication parameters, a bind_resp will be issued and the session is available for communication.
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.
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.
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.
You need to acknowledge the receipt of a deliver_sm with a deliver_sm_resp, otherwise Vox will keep on resending the deliver_sm.
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.
After Vox receives a bind request with the correct authentication, a bind_resp will be issued and the session is available for communication.
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.
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.