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>

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",
      "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
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",
  "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

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

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.

• No authentication: URI called without authentication
• Basic Authentication: URI called with provided username and password
• Bearer Authentication: URI called with provided token

Callbacks can be managed in the Voxtelesys Portal.

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.

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.

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.

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.

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