Messaging API Introduction
Welcome to the Voxtelesys Messaging REST API. This API offers an easy, secure solution to SMS/MMS messaging. Using this API, you can send and receive messages, track the delivery of sent messages, and manage subscriber lists. If at any point you have questions or would like more information please reach out to support.
Base URL
All URLs referenced in the API documentation have the following base:
https://smsapi.voxtelesys.net/api/v1
This API is served over HTTPS to ensure data privacy. Unencrypted HTTP is not supported.
Number Formatting
This API uses E.164 number formatting. E.164 is an international standard for the PSTN that ensures number uniqueness. E.164 numbers are formatted [country code][subscriber number] and can have a maximum of 15 digits.
Examples:
E.164 Format | Country | Country Code | Subscriber Number |
---|---|---|---|
17019299797 | US | 1 | 7019299797 |
Authentication
Request:
curl -X GET \
--url https://smsapi.voxtelesys.net/api/v1/apps \
--header 'authorization: Bearer YOUR_API_KEY'
The Voxtelesys Messaging API uses API keys to authenticate requests. You can view and manage your API keys via the Voxtelesys Portal. Be sure to keep your API keys secure, and do not share in publicly accessible areas such as GitHub, client-side code, etc.
To use your API key, simply pass the key in the Authorization
header:
Authorization: Bearer <YOUR_API_KEY>
Applications
Applications provide automated functionality for your SMS/MMS enabled numbers. They define the actions to execute based upon inbound messaging and also control real-time callbacks for inbound messaging and outbound delivery receipts.
A few common use cases include:
- Forwarding inbound messages and delivery receipts to a web server for real-time chat services.
- Building and maintaining lists of mobile subscribers to comply with CTIA best practices.
- Setting up automatic reply keywords for one-time downloads.
Once setup, applications can be used for a single SMS/MMS enabled number or for groups of numbers. This makes it very simple to setup common functionality between all, or a subset, of your numbers. Please refer to the longcodes namespace to see how to assign an application to a longcode.
Actions
Applications are constructed from one or more automated actions. The following is a list of actions that can be utilized when creating and updating an application.
mo_callback
Example:
{
"mo_callback": {
"url": "https://example.com/api/v1/callbacks",
"method": "post",
"bearer": "d8533c7063af11eabc550242ac130003"
}
}
The mo_callback
action forwards inbound messages (MOs) to the provided URL. This is the recommended method to receive inbound messages for real-time communication. Refer to inbound message callbacks for more details.
Property | Type | Default | Description |
---|---|---|---|
url | string |
required | URL of server to receive callbacks |
method | string |
post | HTTP method; must be get, post |
basic | string |
null | username:password for basic authentication |
bearer | string |
null | token to be used for bearer authentication |
dr_callback
Example:
{
"dr_callback": {
"url": "https://example.com/api/v1/callbacks",
"method": "post",
"basic": "usr:pwd",
"type": "per_recipient"
}
}
The dr_callback
action forwards delivery receipts (DRs) to the provided URL. Delivery receipts will contain final message statuses and will be sent on a per recipient basis or upon batch completion. Refer to delivery receipt callbacks for more details.
Property | Type | Default | Description |
---|---|---|---|
url | string |
required | URL of server to receive callbacks |
method | string |
post | HTTP method; must be get, post |
basic | string |
null | username:password for basic authentication |
bearer | string |
null | token to be used for bearer authentication |
type | string |
summary | type of delivery report; must be per_recipient, summary, detailed |
auto_reply
Example:
{
"auto_reply": [
{
"keywords": ["HELP", "INFO"],
"reply": "VTS: Please give us a call at 402-403-4435 for assistance."
},
{
"keywords": ["download"],
"reply": "Please download our mobile app: https://example.com/download"
}
]
}
The auto_reply
action sends an automatic response to an inbound message matching one of the specified keywords
. Multiple sets of keywords/replies can be defined by adding multiple objects within the auto_reply
array. All keyword comparisons are case-insensitive.
Property | Type | Default | Description |
---|---|---|---|
keywords | array |
required | keywords to initiate auto reply |
reply | string |
required | reply message |
opt_in
Example:
{
"opt_in": [
{
"keywords": ["VTS"],
"reply": "VTS: You have chosen to receive system alerts. Reply CONFIRM to opt-in. Reply STOP to opt-out. Reply HELP for support. Msg&Data rates may apply. T&Cs: http://bit.ly/2BBnp34",
"status": "init"
},
{
"keywords": ["CONFIRM"],
"reply": "VTS: Your have successfully been subscribed for network alerts!",
"status": "double"
}
]
}
The opt_in
action adds the mobile user to the respective list with the specified status
and sends the reply
message in response to inbound messages matching one of the specified keywords
. Multiple sets of opt-in keywords/replies can be defined by adding multiple objects within the opt_in
array. All keyword comparisons are case-insensitive.
Property | Type | Default | Description |
---|---|---|---|
keywords | array |
required | keywords to initiate opt-in |
reply | string |
required | reply message |
status | string |
required | msisdn will be added into list with this status; must be init, single, double, verified |
opt_out
Example:
{
"opt_out": [
{
"keywords": ["stop","cancel","end","quit"],
"reply": "You have been unsubscribed and will no longer receive network alerts."
}
]
}
The opt_out
action marks the mobile user as opted-out of the respective list and sends the reply
message in response to inbound messages matching one of the specified keywords
. Multiple sets of opt-out keywords/replies can be defined by adding multiple objects within the opt_out
array. All keyword comparisons are case-insensitive.
Property | Type | Default | Description |
---|---|---|---|
keywords | array |
required | Keywords to initiate opt-out |
reply | string |
required | Reply message |
Create an application
Request:
curl --request POST \
--url https://smsapi.voxtelesys.net/api/v1/apps \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '{
"name": "test app",
"script": {
"mo_callback": {
"url": "https://example.com/api/v1/callbacks",
"method": "post",
"bearer": "d8533c7063af11eabc550242ac130003"
},
"opt_out": [
{
"keywords": ["stop","cancel","end","quit"],
"reply": "You have been unsubscribed and will no longer receive network alerts."
}
],
"opt_in": [
{
"keywords": ["VTS"],
"reply": "VTS: You have chosen to receive system alerts. Reply CONFIRM to opt-in. Reply STOP to opt-out. Reply HELP for support. Msg&Data rates may apply. T&Cs: http://bit.ly/2BBnp34",
"status": "init"
},
{
"keywords": ["CONFIRM"],
"reply": "VTS: Your have successfully been subscribed for network alerts!",
"status": "double"
}
],
"auto_reply": [
{
"keywords": ["HELP","INFO"],
"reply": "VTS: Please give us a call at 402-403-4435 for assistance."
},
{
"keywords": ["download"],
"reply": "Please download our mobile app: https://example.com/download"
}
]
}
}'
Response:
200
{
"id": "9Nskupdq_byZSygx",
"name": "test app",
"created_at": "2019-02-19T21:08:10Z",
"modified_at": "2019-02-19T21:08:10Z",
"script": {
"mo_callback": {
"url": "https://example.com/api/v1/callbacks",
"method": "post",
"bearer": "************"
},
"opt_out": [
{
"keywords": ["stop","cancel","end","quit"],
"reply": "You have been unsubscribed and will no longer receive network alerts."
}
],
"opt_in": [
{
"keywords": ["vts"],
"reply": "VTS: You have chosen to receive system alerts. Reply CONFIRM to opt-in. Reply STOP to opt-out. Reply HELP for support. Msg&Data rates may apply. T&Cs: http://bit.ly/2BBnp34",
"status": "init"
},
{
"keywords": ["confirm"],
"reply": "VTS: Your have successfully been subscribed for network alerts!",
"status": "double"
}
],
"auto_reply": [
{
"keywords": ["help","info"],
"reply": "VTS: Please give us a call at 402-403-4435 for assistance."
},
{
"keywords": ["download"],
"reply": "Please download our mobile app: https://example.com/download"
}
]
}
}
Endpoint for creating applications.
HTTP Request
POST https://smsapi.voxtelesys.net/api/v1/apps
JSON Body Parameters
Param | Type | Required | Description | Example |
---|---|---|---|---|
name | string |
false | name of application | foo_bar |
script | object |
true | actions to execute | see sample request |
script.mo_callback | object |
false | mo-callback action | mo_callback |
script.dr_callback | object |
false | dr-callback action | dr_callback |
script.auto_reply | array |
false | auto-reply action | auto_reply |
script.opt_in | array |
false | opt-in action | opt_in |
script.opt_out | array |
false | opt-out action | opt_out |
Replace an application
Request:
curl --request PUT \
--url https://smsapi.voxtelesys.net/api/v1/apps/9Nskupdq_byZSygx \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '{
"script": {
"auto_reply": [
{
"keywords": ["HELP", "INFO"],
"reply": "VTS: Please give us a call at 402-403-4435 for assistance."
}
]
}
}'
Response:
200
{
"id": "9Nskupdq_byZSygx",
"name": "test app",
"created_at": "2019-02-19T21:08:10Z",
"modified_at": "2019-02-19T21:17:00Z",
"script": {
"auto_reply": [
{
"keywords": ["help", "info"],
"reply": "VTS: Please give us a call at 402-403-4435 for assistance."
}
]
}
}
Endpoint for replacing an application. The existing script is overwritten with the provided script.
HTTP Request
PUT https://smsapi.voxtelesys.net/api/v1/apps/{id}
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
id | string |
ID of application | 9Nskupdq_byZSygx |
JSON Body Parameters
Param | Type | Required | Description | Example |
---|---|---|---|---|
name | string |
false | name of application | foo_bar |
script | object |
true | actions to execute | see sample request |
script.mo_callback | object |
false | mo-callback action | mo_callback |
script.dr_callback | object |
false | dr-callback action | dr_callback |
script.auto_reply | array |
false | auto-reply action | auto_reply |
script.opt_in | array |
false | opt-in action | opt_in |
script.opt_out | array |
false | opt-out action | opt_out |
Modify an application
Request:
curl --request PATCH \
--url https://smsapi.voxtelesys.net/api/v1/apps/9Nskupdq_byZSygx \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '{
"script": {
"opt_out": [
{
"keywords": ["stop","cancel","end","quit"],
"reply": "You have been unsubscribed and will no longer receive network alerts."
}
]
}
}'
Response:
200
{
"id": "9Nskupdq_byZSygx",
"name": "test app",
"created_at": "2019-02-19T21:08:10Z",
"modified_at": "2019-02-19T21:22:46Z",
"script": {
"auto_reply": [
{
"keywords": ["help","info"],
"reply": "VTS: Please give us a call at 402-403-4435 for assistance."
}
],
"opt_out": [
{
"keywords": ["stop","cancel","end","quit"],
"reply": "You have been unsubscribed and will no longer receive network alerts."
}
]
}
}
Endpoint for modifying an existing application. Actions in the existing script will not be replaced unless the action is in the provided script.
HTTP Request
PATCH https://smsapi.voxtelesys.net/api/v1/apps/{id}
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
id | string |
ID of application | 9Nskupdq_byZSygx |
JSON Body Parameters
Param | Type | Required | Description | Example |
---|---|---|---|---|
name | string |
false | name of application | foo_bar |
script | object |
true | actions to execute | see sample request |
script.mo_callback | object |
false | mo-callback action | mo_callback |
script.dr_callback | object |
false | dr-callback action | dr_callback |
script.auto_reply | array |
false | auto-reply action | auto_reply |
script.opt_in | array |
false | opt-in action | opt_in |
script.opt_out | array |
false | opt-out action | opt_out |
List applications
Request:
curl --request GET \
--url https://smsapi.voxtelesys.net/api/v1/apps \
--header 'authorization: Bearer YOUR_API_KEY'
Response:
200
{
"page": 1,
"page_size": 10,
"page_count": 1,
"count": 1,
"results": [
{
"id": "9Nskupdq_byZSygx",
"name": "test app",
"created_at": "2019-02-19T21:08:10Z",
"modified_at": "2019-02-19T21:22:46Z",
"script": {
"auto_reply": [
{
"keywords": ["help","info"],
"reply": "VTS: Please give us a call at 402-403-4435 for assistance."
}
]
}
}
]
}
Endpoint for retrieving your list of applications.
HTTP Request
GET https://smsapi.voxtelesys.net/api/v1/apps
Query Parameters
Param | Type | Description | Example |
---|---|---|---|
page | integer |
page number starting from 1; default 1 | 1 |
page_size | integer |
number of records to retrieve per page; default 25 | 50 |
Retrieve an application
Request:
curl --request GET \
--url https://smsapi.voxtelesys.net/api/v1/apps/9Nskupdq_byZSygx \
--header 'authorization: Bearer YOUR_API_KEY'
Response:
200
{
"id": "9Nskupdq_byZSygx",
"name": "test app",
"created_at": "2019-02-19T21:08:10Z",
"modified_at": "2019-02-19T21:22:46Z",
"script": {
"auto_reply": [
{
"keywords": ["help","info"],
"reply": "VTS: Please give us a call at 402-403-4435 for assistance."
}
]
}
}
Endpoint for retrieving a specific application.
HTTP Request
GET https://smsapi.voxtelesys.net/api/v1/apps/{id}
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
id | string |
ID of application | 9Nskupdq_byZSygx |
Delete an application
Request:
curl --request DELETE \
--url https://smsapi.voxtelesys.net/api/v1/apps/rdDdVqWLbwsCtDY2 \
--header 'authorization: Bearer YOUR_API_KEY'
Response:
204
Endpoint for deleting a specific application.
HTTP Request
DELETE https://smsapi.voxtelesys.net/api/v1/apps/{id}
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
id | string |
ID of application | 9Nskupdq_byZSygx |
Longcodes
A long code is a standard phone number that is used to send and receive voice calls and SMS/MMS messages. The term "long code" (10-digit numbers in many countries) is typically used when comparing numbers to short codes (5-6 digit numbers). Numbers can be purchased and managed via the Voxtelesys Portal. For more information, please reach out to sales.
List longcodes
Request:
curl --request GET \
--url https://smsapi.voxtelesys.net/api/v1/longcodes \
--header 'authorization: Bearer YOUR_API_KEY'
Response:
200
{
"page": 1,
"page_size": 25,
"page_count": 1,
"count": 2,
"results": [
{
"longcode": "14029999402",
"sub_account_id": null,
"app_id": "9Nskupdq_byZSygx"
},
{
"longcode": "14024034435",
"sub_account_id": "1001",
"app_id": "U0EFxA3mFcWZxUHf"
}
]
}
Endpoint for retrieving your list of longcodes.
HTTP Request
GET https://smsapi.voxtelesys.net/api/v1/longcodes
Query Parameters
Param | Type | Description | Example |
---|---|---|---|
page | integer |
page number starting from 1; default 1 | 1 |
page_size | integer |
number of longcodes to retrieve per page; default 25 | 50 |
Retrieve a longcode
Request:
curl --request GET \
--url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402 \
--header 'authorization: Bearer YOUR_API_KEY'
Response:
200
{
"longcode": "14029999402",
"sub_account_id": null,
"app_id": "9Nskupdq_byZSygx"
}
Endpoint for retrieving a specific longcode.
HTTP Request
GET https://smsapi.voxtelesys.net/api/v1/longcodes/{longcode}
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
longcode | string |
longcode | 14029999402 |
Update a longcode
Request:
curl --request PUT \
--url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402 \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '{
"app_id": "U0EFxA3mFcWZxUHf"
}'
Response:
200
{
"longcode": "14029999402",
"sub_account_id": null,
"app_id": "U0EFxA3mFcWZxUHf"
}
Endpoint for modifying the application and/or sub account associated with the specified longcode.
HTTP Request
PUT https://smsapi.voxtelesys.net/api/v1/longcodes/{longcode}
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
longcode | string |
longcode | 14029999402 |
JSON Body Parameters
Param | Type | Required | Description | Example |
---|---|---|---|---|
sub_account_id | string |
false | ID of sub account | 1010 |
app_id | string |
false | ID of application | U0EFxA3mFcWZxUHf |
Subscribers
Subscriber lists provide an easy mechanism to manage opted-in and opted-out mobile users, referred to as MSISDNs. Please refer to the applications section to see how to setup automated opt-in and opt-out actions on your SMS/MMS enabled numbers. Furthermore, when sending outbound messages the batches namespace allows you to check the status of your mobile subscribers, ensuring that you compliant with CTIA best practices.
Retrieve subscriber list
Request:
curl --request GET \
--url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402/list \
--header 'authorization: Bearer YOUR_API_KEY'
Response:
200
{
"page": 1,
"page_size": 25,
"page_count": 1,
"count": 3,
"results": {
"verified": [
"14021113333",
"14021114444"
],
"single": [
"14021112222"
]
}
}
Endpoint for retrieving your subscribers.
HTTP Request
GET https://smsapi.voxtelesys.net/api/v1/longcodes/{longcode}/list
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
longcode | string |
longcode | 14029999402 |
Query Parameters
Param | Type | Description | Example |
---|---|---|---|
page | integer |
page number starting from 1; default 1 | 1 |
page_size | integer |
number of msisdns to retrieve per page; default 25 | 50 |
status | string |
retrieve msisdns with this status; must be opt-out, init, single, double, or verified | single |
Retrieve subscriber
Request:
curl --request GET \
--url https://smsapi.voxtelesys.net/api/v1/longcodes/4029999402/list/14021112222 \
--header 'authorization: Bearer YOUR_API_KEY'
Response:
200
{
"msisdn": "14021112222",
"status": "single",
"modified_at": "2019-03-06T02:02:01Z"
}
Endpoint for retrieving an existing subscriber.
HTTP Request
GET https://smsapi.voxtelesys.net/api/v1/longcodes/{longcode}/list/{msisdn}
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
longcode | string |
longcode | 14029999402 |
msisdn | string |
msisdn subscribed to longcode | 14024434559 |
Update subscriber
Request:
curl --request PUT \
--url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402/list/14021112222 \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '{
"status": "opt-out"
}'
Response:
200
{
"msisdn": "14021112222",
"status": "opt-out",
"modified_at": "2019-03-06T03:02:01Z"
}
Endpoint for modifying an existing subscriber.
HTTP Request
PUT https://smsapi.voxtelesys.net/api/v1/longcodes/{longcode}/list/{msisdn}
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
longcode | string |
longcode | 14029999402 |
msisdn | string |
msisdn subscribed to longcode | 14024434559 |
Create subscriber
curl --request POST \
--url https://smsapi.voxtelesys.net/api/v1/longcodes/4029999402/list \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '{
"msisdn": "14021112222",
"status": "opt-out"
}'
Response:
200
{
"msisdn": "14021112222",
"status": "opt-out",
"modified_at": "2019-03-06T02:02:01Z"
}
Endpoint for creating a new subscriber.
HTTP Request
POST https://smsapi.voxtelesys.net/api/v1/longcodes/{longcode}/list
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
longcode | string |
longcode | 14029999402 |
JSON Body Parameters
Param | Type | Required | Description | Example |
---|---|---|---|---|
msisdn | string |
true | msisdn to subscribe to longcode | 14024434559 |
status | string |
true | must be opt-out, init, single, double, or verified | single |
Delete subscriber
Request:
curl --request DELETE \
--url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402/list/14021112222 \
--header 'authorization: Bearer YOUR_API_KEY'
Response:
204
Endpoint for deleting an existing subscriber.
HTTP Request
DELETE https://smsapi.voxtelesys.net/api/v1/longcodes/{longcode}/list/{msisdn}
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
longcode | string |
longcode | 14029999402 |
msisdn | string |
msisdn subscribed to longcode | 14024434559 |
Batches
The Batches namespace provides the methods necessary to delivery and manage one-to-one and one-to-many SMS/MMS messaging. Batches can be scheduled to start at a specific time, and likewise expire. For larger batches, the API offers body parameterization and start, pause, cancel capabilities.
List batches
Request:
curl --request GET \
--url https://smsapi.voxtelesys.net/api/v1/sms \
--header 'authorization: Bearer YOUR_API_KEY'
Response:
200
{
"page": 1,
"page_size": 30,
"page_count": 1,
"count": 1,
"results": [
{
"id": "BPBPqNgILE2urR4S",
"from": "14024431550",
"to": ["14024431550","14024431551","14024439159"],
"body": "Hi ${name}, your package is delivering to ${address} and should arrive around ${time}.",
"parameters": {
"definition": ["name","address","time"],
"default": ["Customer",0,0],
"14024431550": ["John","1111 Westroads Street","12:30 PM"],
"14024431551": ["Luke","2222 Eastroads Plaza","1:00 PM"],
"14024439159": ["Sarah","3333 Southroads Lane","4:45 PM"]
},
"send_at": "2019-02-20T04:18:56Z",
"expire_at": "2019-02-23T04:18:56Z",
"modified_at": "2019-02-20T04:19:02Z",
"check_opt_in": false,
"check_opt_out": true,
"status": "pre-processing"
}
]
}
Endpoint for retrieving your batches.
HTTP Request
GET https://smsapi.voxtelesys.net/api/v1/sms
Query Parameters
Param | Type | Description | Example |
---|---|---|---|
page | integer |
page number starting from 1; default 1 | 1 |
page_size | integer |
number of batches to retrieve per page; default 25 | 50 |
start_date | string |
retrieve batches at or after this time; must be ISO 8601 format | 2018-03-01 08:00 -0600 |
end_date | string |
retrieve batches at or before this time; must be ISO 8601 format | 2018-03-28 08:00 -0600 |
status | string |
retrieve batches with this status | in-progress |
from | string |
retrieve batches originated from this number | 14029999402 |
sub_account_id | string |
retrieve batches associated with this sub account | 1011 |
fields | string |
returns a partial response with specified fields | status,from,body |
Retrieve a batch
Request:
curl --request GET \
--url https://smsapi.voxtelesys.net/api/v1/sms/BPBPqNgILE2urR4S \
--header 'authorization: Bearer YOUR_API_KEY'
Response:
200
{
"id": "BPBPqNgILE2urR4S",
"from": "14024431550",
"to": ["14024431550","14024431551","14024439159"],
"body": "Hi ${name}, your package is delivering to ${address} and should arrive around ${time}.",
"parameters": {
"definition": ["name","address","time"],
"default": ["Customer",0,0],
"14024431550": ["John","1111 Westroads Street","12:30 PM"],
"14024431551": ["Luke","2222 Eastroads Plaza","1:00 PM"],
"14024439159": ["Sarah","3333 Southroads Lane","4:45 PM"]
},
"send_at": "2019-02-20T04:18:56Z",
"expire_at": "2019-02-23T04:18:56Z",
"modified_at": "2019-02-20T04:19:02Z",
"check_opt_in": false,
"check_opt_out": true,
"status": "pre-processing"
}
Endpoint for retrieving an existing batch.
HTTP Request
GET https://smsapi.voxtelesys.net/api/v1/sms/{id}
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
id | string |
ID of batch | BPBPqNgILE2urR4S |
Send a batch
Request: SMS without parameterization
curl --request POST \
--url https://smsapi.voxtelesys.net/api/v1/sms \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '{
"to": ["14024431111"],
"from": "14024430000",
"body": "Hi John, your package is delivering to 1111 Westroads Street and should arrive around 12:30 PM."
}'
Response:
200
{
"id": "BPBPqNgILE2urR4S",
"to": ["14024431111"],
"from": "14024430000",
"body": "Hi John, your package is delivering to 1111 Westroads Street and should arrive around 12:30 PM.",
"modified_at": "2019-02-20T04:19:02Z",
"status": "pre-processing"
}
Request: SMS with parameterization
curl --request POST \
--url https://smsapi.voxtelesys.net/api/v1/sms \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '{
"to": ["14024431111","14024432222","14024433333"],
"from": "14024430000",
"body": "Hi ${name}, your package is delivering to ${address} and should arrive around ${time}.",
"parameters": {
"definition": ["name","address","time"],
"default": ["Customer",0,0],
"14024431111": ["John","1111 Westroads Street","12:30 PM"],
"14024432222": ["Luke","2222 Eastroads Plaza","1:00 PM"]
}
}'
Response:
200
{
"id": "BPBPqNgILE2urR4S",
"to": ["14024431111","14024432222","14024433333"],
"from": "14024430000",
"body": "Hi ${name}, your package is delivering to ${address} and should arrive around ${time}.",
"parameters": {
"definition": ["name","address","time"],
"default": ["Customer",0,0],
"4024431111": ["John","1111 Westroads Street","12:30 PM"],
"4024432222": ["Luke","2222 Eastroads Plaza","1:00 PM"]
},
"modified_at": "2019-02-20T04:19:02Z",
"status": "pre-processing"
}
Request: MMS
curl --request POST \
--url https://smsapi.voxtelesys.net/api/v1/sms \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '{
"to": ["14024431111"],
"from": "14024430000",
"body": "Hello world with picture!",
"media": ["http://smsapi.voxtelesys.com/images/vox-logo.png"]
}'
Response:
200
{
"id": "BPBPqNgILE2urR4S",
"to": ["14024431111"],
"from": "14024430000",
"body": "Hello world with picture!",
"media": ["http://smsapi.voxtelesys.com/images/vox-logo.png"],
"modified_at": "2019-02-20T04:19:02Z",
"status": "pre-processing"
}
Endpoint for sending SMS/MMS messages.
Parameterization
When creating an SMS/MMS batch, it can be convenient to customize part(s) of the message on a per recipient basis. Parameterization allows you to do just that!
When defining the message body, just insert as many parameter keys as is required. A key is defined by entering ${key}
in the message body, where "key" is the name of the parameter. For each specified parameter key, a recipient and parameter value must also be provided.
For example, the message body "Your appointment is scheduled for ${time}." contains the parameter key "time". When sending the batch, this key would be replaced with the defined value.
Parameter values are then provided per recipient, or default values are provided. When providing parameter values, there are three component:
definition: Specifies the order in which parameter values will be provided in the default
and {recipient}
arrays.
default: Specifies the default values. The default value is used if an associated recipient array is not provided. Array size must be the same as definition
, where an integer of 0 represents NULL or not provided.
recipient: Specifies the parameter values to use for the specified recipient. Again, array size must be the same as definition
, where an integer of 0 represents NULL or not provided.
Multimedia (MMS)
To send media like pictures, videos, and documents you will need to provide the media
parameter with one or more URL.
HTTP Request
POST https://smsapi.voxtelesys.net/api/v1/sms
JSON Body Parameters
Param | Type | Required | Description | Example |
---|---|---|---|---|
to | array |
true | list of recipients | ["14024431550","14024431551"] |
from | string |
true | originator of message | 14029999402 |
body | string |
true | message body | Hello world, this is a test message! |
media | array |
false | list of URLs to include as media attachments | ["http://path.to.image"] |
tag | string |
false | string which will be included in callback events (max 256 chars) | 261f6924-6982-11ea-bc55-0242ac130003 |
parameters | object |
false | object to hold params | see sample request |
parameters.definition | array |
false | order of params | ["name","address","time"] |
parameters.default | array |
false | default params | ["Customer",0,0] |
parameters.{recipient} | array |
false | params for specific recipient | ["John","12:30 PM"] |
send_at | string |
false | time to start campaign; must be ISO 8601 format | 2018-01-01 8:00:00 -0600 |
expire_at | string |
false | time to expire campaign; must be ISO8601 format | 2018-01-01 16:00:00 -0600 |
check_opt_in | boolean |
false | only send to opted-in subscribers | false |
check_opt_out | boolean |
false | do not send to opted-out subscribers | false |
add_to_list | string |
false | list to add recipients to; must be init, single, double, or verified | init |
Manage a batch
Request:
curl --request PUT \
--url https://smsapi.voxtelesys.net/api/v1/sms/BPBPqNgILE2urR4S \
--header 'authorization: Bearer YOUR_API_KEY'
--header 'content-type: application/json' \
--data '{
"action": "pause"
}
Response:
204
Endpoint for starting, pausing, or canceling an existing batch.
HTTP Request
PUT https://smsapi.voxtelesys.net/api/v1/sms/{id}
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
id | string |
ID of batch | BPBPqNgILE2urR4S |
JSON Body Parameters
Param | Type | Required | Description | Example |
---|---|---|---|---|
action | string |
true | must be start, pause, or cancel | pause |
Retrieve a delivery report
Request:
curl --request GET \
--url https://smsapi.voxtelesys.net/api/v1/sms/BPBPqNgILE2urR4S/delivery_report?type=detailed \
--header 'authorization: Bearer YOUR_API_KEY'
Response:
200
{
"batch_id": "Z0S0jQOf8_hl9YRt",
"batch_status": "completed",
"count": 3,
"results": [
{
"status": "delivered",
"count": 3,
"to": [
"14024439159",
"14024431551",
"14024431550"
]
}
]
}
Endpoint for retrieving a delivery report.
HTTP Request
GET https://smsapi.voxtelesys.net/api/v1/sms/{id}/delivery_report
URL Parameters
Param | Type | Description | Example |
---|---|---|---|
id | string |
ID of batch | BPBPqNgILE2urR4S |
Query Parameters
Param | Type | Description | Example |
---|---|---|---|
type | string |
report type; must be detailed or summary | summary |
Callbacks
Voxtelesys uses HTTP callbacks, also referred to as webhooks, to relay inbound messages (MOs) and delivery receipts (DRs). Callbacks can be sent as either POST or GET requests. For POST requests the MO/DR will be JSON encoded. For GET requests the MO/DR will be URL encoded. You must reply with a HTTP 2xx
status code. If a HTTP 2xx
is not received, then the callback will be retried over the next 24 hours until a HTTP 2xx
is received. After 24 hours, Voxtelesys will discard the callback.
Callbacks offer the below authentication methods. Please see the MO callback and DR callback actions to see how to setup authentication.
- No authentication: URI called without authentication
- Basic Authentication: URI called with provided username and password
- Bearer Authentication: URI called with provided token
Inbound message (MO)
Example: SMS message
{
"type": "mo",
"to": "14029999402",
"from": "14022770210",
"body": "Example SMS message!",
"received_at": "2019-02-19T21:22:46Z"
}
Example: MMS message
{
"type": "mo",
"to": "14029999402",
"from": "14022770210",
"body": "Example MMS message!",
"media": ["https://smsapi.voxtelesys.net/api/v1/media/9ce86fa9-1111-0000-85e1-7d3e789858fb.jpg?token=Nhk-CVQENT123Ho-diAWOTU="],
"received_at": "2019-02-19T21:22:46Z"
}
Inbound message callbacks, often referred to as mobile originated (MO) callbacks, are generated when messages are sent to your SMS/MMS enabled numbers. In order to receive MO callbacks, you need to ensure that you setup your application(s) with the mo_callback action.
Property | Type | Required | Description |
---|---|---|---|
type | string |
true |
callback type |
to | string |
true |
phone number the message was sent to |
from | string |
true |
phone number the message was sent from |
body | string |
true |
body of message |
media | array |
false |
URLs of media, if MMS |
received_at | string |
true |
time message was received in ISO 8601 format |
Per recipient (DR)
Delivery receipts sent on a per recipient basis generate one callback for every recipient in a batch. The delivery receipt is sent when the message reaches a final status. In order to receive DR callbacks, you need to ensure that you setup your application(s) with the dr_callback action.
Example: delivered message
{
"type": "per_recipient",
"batch_id": "Z0S0jQOf8_hl9YRt",
"message_id": "5e66da76e53cd156f205c612",
"to": "14024431111",
"status": "delivered",
"time": "2019-02-19T21:22:46Z"
}
Example: failed message
{
"type": "per_recipient",
"batch_id": "Z0S0jQOf8_hl9YRt",
"message_id": "5e66f1dbe53cd156f205c614",
"to": "14024431112",
"status": "failed ",
"time": "2019-02-19T21:22:46Z",
"error": {
"code": 4504,
"description": "carrier rejected invalid message"
}
}
Property | Type | Required | Description |
---|---|---|---|
type | string |
true |
callback type |
batch_id | string |
true |
ID of batch |
message_id | string |
true |
ID of message |
tag | string |
false |
custom string sent with batch |
to | string |
true |
phone number the message was sent to |
status | string |
true |
final message status |
time | string |
true |
time message was sent in ISO 8601 format |
error | object |
false |
error of message |
error.code | int |
false |
detailed error code |
error.description | string |
false |
detailed error description |
Batch summary (DR)
Delivery receipts sent on a per batch basis only generate one callback per batch. The delivery receipt is sent when the batch reaches a final status. Summary receipts are a condensed receipt that do not include the list of recipients. In order to receive DR callbacks, you need to ensure that you setup your application(s) with the dr_callback action.
Example:
{
"type": "summary",
"batch_id": "Z0S0jQOf8_hl9YRt",
"batch_status": "completed",
"count": 3,
"results": [
{
"status": "delivered",
"count": 3
}
]
}
Property | Type | Required | Description |
---|---|---|---|
type | string |
true |
callback type |
batch_id | string |
true |
ID of batch |
batch_status | string |
true |
final batch status |
tag | string |
false |
custom string sent with batch |
count | string |
true |
number of messages in batch |
results | array |
true |
final message results for batch |
results.status | string |
true |
final message status |
results.count | int |
true |
number of messages with status |
Batch detailed (DR)
Delivery receipts sent on a per batch basis only generate one callback per batch. The delivery receipt is sent when the batch reaches a final status. Detailed receipts are an expanded receipt that include the list of recipients. In order to receive DR callbacks, you need to ensure that you setup your application(s) with the dr_callback action.
Example:
{
"type": "detailed",
"batch_id": "Z0S0jQOf8_hl9YRt",
"batch_status": "completed",
"count": 3,
"results": [
{
"status": "delivered",
"count": 3,
"to": [
"14021112221",
"14021112222",
"14021112223"
]
}
]
}
Property | Type | Required | Description |
---|---|---|---|
type | string |
true |
callback type |
batch_id | string |
true |
ID of batch |
batch_status | string |
true |
final batch status |
tag | string |
false |
custom string sent with batch |
count | string |
true |
number of messages in batch |
results | array |
true |
final message results for batch |
results.status | string |
true |
final message status |
results.count | int |
true |
number of messages with status |
results.to | array |
true |
list of phone numbers with status |
Statuses
Message statuses
Every message has an associated status. Once a message reaches a final
status, no further actions will be taken with the message. The list of possible statuses is provided below.
Status | Type | Description |
---|---|---|
queued | intermediate |
Message has been queued and will be sent according to account rate limit. |
delivering | intermediate |
Message has been sent and is awaiting final delivery status. |
delivered | final |
Message has been delivered. |
failed | final |
Message failed to be delivered. |
unknown | final |
Final delivery state is unknown. |
canceled | final |
Message was canceled before being sent. |
expired | final |
Message expired before being sent. |
Batch statuses
Every batch has an associated status. Once a batch reaches a final
status, all messaging has been completed and no further actions will be taken with the batch. The list of possible statuses is provided below.
Status | Type | Description |
---|---|---|
pre-processing | intermediate |
Batch is being validated. |
in-progress | intermediate |
Batch has been validated and is actively sending messages. |
paused | intermediate |
Batch has been paused by user; no messages are sent while in this state. |
scheduled | intermediate |
Batch has been successfully loaded, and will be sent out at the specified send_at time. |
canceled | final |
Batch was canceled by user. |
completed | final |
Batch completed successfully. |
expired | final |
Batch expired before it was completed. All queued messages are deleted and no further messaging is sent from this batch. |
Errors
Voxtelesys reports outbound messaging errors via HTTP callbacks. Errors while interacting with the REST API are returned in response to the request. If you have any questions or need help resolving errors please contact support.
HTTP errors
Code | Description |
---|---|
401 | Unauthorized - The provided credentials failed. Please see authentication for more details. |
404 | Not Found - The request URL and/or HTTP method was not found. |
422 | Unprocessable Entity - The request data and/or parameters are not valid. |
500 | Internal Server Error - An error occurred within the server. Please contact Voxtelesys with the provided error_id to resolve this error. |
Messaging errors
Code | Description |
---|---|
4101 | rejected as SPAM |
4102 | invalid message encoding |
4103 | invalid to number |
4104 | invalid from number |
4105 | forbidden to number |
4106 | forbidden from number |
4107 | unallocated to number |
4108 | unallocated from number |
4109 | invalid media url |
4110 | invalid media size |
4111 | forbidden country |
4112 | invalid message length |
4113 | opt-in not satisfied |
4114 | opt-out satisfied |
4115 | invalid body mapping |
4116 | duplicate to number |
4501 | carrier rejected invalid service type |
4502 | carrier rejected invalid destination address |
4503 | carrier rejected invalid source address |
4504 | carrier rejected invalid message |
4505 | carrier rejected message too long |
4506 | carrier rejected as SPAM |
4507 | carrier rejected user opt out |
4508 | carrier rejected unknown msisdn |
4509 | carrier rejected bad msisdn |
5101 | carrier service unavailable |
5102 | carrier service error |
5103 | carrier application error |
5104 | carrier routing error |
5105 | carrier unknown error |
5300 | internal error |
5301 | internal error |
5302 | internal error |
5303 | internal error |
5304 | internal error |
5305 | internal error |
5306 | internal error |
5307 | internal error |
5308 | internal error |
5309 | internal error |
5310 | internal error |
5311 | internal error |