Messaging API Introduction

Welcome to the Voxtelesys Messaging REST API. This API offers an easy, secure solution to SMS/MMS messaging. If at any point you have questions or would like more information please reach out to support.

Base URL

All URLs referenced in this document have the following base: https://smsapi.voxtelesys.net/api/v1

Authentication

The Messaging API utilizes tokens to authenticate its resources. When setting up an SMS/MMS account, users have the option to choose between a persistent token or short-lived tokens. In most applications, persistent tokens will provide adequate security.

Persistent tokens

Persistent tokens are configured during the on-boarding process and do not expire. If a persistent token has been issued to your account, simply provide the token via Bearer authentication when sending requests.

Authorization: Bearer {TOKEN}

Example:

Authorization: Bearer f2d1c9b6-1158-11e6-bb4e-26a732fd0877

Short-lived tokens

Short-lived tokens provide additional security, as they expire after 10 minutes of inactivity. This style of implementation is very similar to OAuth2.0. If your account is setup to use short-lived tokens, then a username and password will be assigned to your account during the on-boarding process.

To get started with short-lived tokens, the user must first request a token via a login request. The login method utilizes HTTP basic authentication.

Request:

curl --request GET \
  --url https://smsapi.voxtelesys.net/api/v1/authorize/login \
  --header 'authorization: Basic ZGVtbzpwd2Q='

Response: 200

{
  "status": {
    "status": "Authorized",
    "token": "7bdf5350-5895-46ec-a25a-a531613c5046",
    "account_id": 190761,
    "account_name": "voxtelesys vts",
    "service_group_id": 70001
  },
  "services": [
    {
      "full_name": "SMS Messaging",
      "service_id": 6,
      "short_name": "SMS"
    }
  ],
  "error": ""
}

GET https://smsapi.voxtelesys.net/api/v1/authorize/login

Header	Type	Required	Description	Example
Authorization	string	true	basic authentication	`Authentication: Basic dXNyOnB3ZA==`

The assigned token is valid for 10 minutes, refreshing for an additional 10 minutes with subsequent successful requests. As a further layer of protection, the assigned token is only valid for the IP address from which the HTTP request was attempted. For applications making request to the Messaging API via separate IP addresses, you must obtain unique tokens per application.

The token can then be utilized via Bearer authentication when sending requests.

Authorization: Bearer {TOKEN}

Example:

Authorization: Bearer f2d1c9b6-1158-11e6-bb4e-26a732fd0877

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 reporting.

A few common use cases include:

Forwarding inbound messages to an on-site server for real-time chat services.
Building and maintaining lists of mobile subscribers for bulk messaging.
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
dr_callback
auto_reply
opt_in
opt_out

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 configured endpoint. 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 configured endpoint. 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 176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --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 176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --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 176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --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 176a78b0-8e81-4e56-9e3f-da67d17915bb'

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 176a78b0-8e81-4e56-9e3f-da67d17915bb'

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 176a78b0-8e81-4e56-9e3f-da67d17915bb'

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

Longcodes are standard 10-digit dedicated phone numbers (TFNs / DIDs) that enable businesses to receive SMS/MMS messaging and voice. To get started with longcodes, please reach out to sales.

List longcodes

Request:

curl --request GET \
  --url https://smsapi.voxtelesys.net/api/v1/longcodes \
  --header 'authorization: Bearer 176a78b0-8e81-4e56-9e3f-da67d17915bb'

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 176a78b0-8e81-4e56-9e3f-da67d17915bb'

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`	10-digit longcode	`4029999402`

Update a longcode

Request:

curl --request PUT \
  --url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402 \
  --header 'authorization: Bearer 176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --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`	10-digit longcode	`4029999402`

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 are not violating CTIA guidelines.

Retrieve subscriber list

Request:

curl --request GET \
  --url https://smsapi.voxtelesys.net/api/v1/longcodes/14029999402/list \
  --header 'authorization: Bearer 176a78b0-8e81-4e56-9e3f-da67d17915bb'

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`	10-digit longcode	`4029999402`

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/4021112222 \
  --header 'authorization: Bearer 176a78b0-8e81-4e56-9e3f-da67d17915bb'

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`	10-digit longcode	`4029999402`
msisdn	`string`	msisdn subscribed to longcode	`4024434559`

Update subscriber

Request:

curl --request PUT \
  --url https://smsapi.voxtelesys.net/api/v1/longcodes/4029999402/list/4021112222 \
  --header 'authorization: Bearer 176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --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`	10-digit longcode	`4029999402`
msisdn	`string`	msisdn subscribed to longcode	`4024434559`

Create subscriber

curl --request POST \
  --url https://smsapi.voxtelesys.net/api/v1/longcodes/4029999402/list \
  --header 'authorization: Bearer 176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --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`	10-digit longcode	`4029999402`

JSON Body Parameters

Param	Type	Required	Description	Example
msisdn	`string`	true	msisdn to subscribe to longcode	`4024434559`
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/4029999402/list/4021112222 \
  --header 'authorization: Bearer 176a78b0-8e81-4e56-9e3f-da67d17915bb'

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`	10-digit longcode	`4029999402`
msisdn	`string`	msisdn subscribed to longcode	`4024434559`

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 176a78b0-8e81-4e56-9e3f-da67d17915bb'

Response: 200

{
  "page": 1,
  "page_size": 30,
  "page_count": 1,
  "count": 1,
  "results": [
    {
      "id": "BPBPqNgILE2urR4S",
      "from": "14024431550",
      "to": ["4024431550","4024431551","4024439159"],
      "body": "Hi ${name}, your package is delivering to ${address} and should arrive around ${time}.",
      "parameters": {
        "definition": ["name","address","time"],
        "default": ["Customer",0,0],
        "4024431550": ["John","1111 Westroads Street","12:30 PM"],
        "4024431551": ["Luke","2222 Eastroads Plaza","1:00 PM"],
        "4024439159": ["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	`4029999402`
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 176a78b0-8e81-4e56-9e3f-da67d17915bb'

Response: 200

{
  "id": "BPBPqNgILE2urR4S",
  "from": "14024431550",
  "to": ["4024431550","4024431551","4024439159"],
  "body": "Hi ${name}, your package is delivering to ${address} and should arrive around ${time}.",
  "parameters": {
    "definition": ["name","address","time"],
    "default": ["Customer",0,0],
    "4024431550": ["John","1111 Westroads Street","12:30 PM"],
    "4024431551": ["Luke","2222 Eastroads Plaza","1:00 PM"],
    "4024439159": ["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: without parameterization

curl --request POST \
  --url https://smsapi.voxtelesys.net/api/v1/sms \
  --header 'authorization: Bearer 176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --header 'content-type: application/json' \
  --data '{
    "to": ["4024431111"],
    "from": "4024430000",
    "body": "Hi John, your package is delivering to 1111 Westroads Street and should arrive around 12:30 PM."
  }'

Response: 200

{
  "id": "BPBPqNgILE2urR4S",
  "to": ["4024431111"],
  "from": "4024430000",
  "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: with parameterization

curl --request POST \
  --url https://smsapi.voxtelesys.net/api/v1/sms \
  --header 'authorization: Bearer 176a78b0-8e81-4e56-9e3f-da67d17915bb' \
  --header 'content-type: application/json' \
  --data '{
    "to": ["4024431111","4024432222","4024433333"],
    "from": "4024430000",
    "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"]
    }
  }'

Response: 200

{
  "id": "BPBPqNgILE2urR4S",
  "to": ["4024431111","4024432222","4024433333"],
  "from": "4024430000",
  "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"
}

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.

HTTP Request

POST https://smsapi.voxtelesys.net/api/v1/sms

JSON Body Parameters

Param	Type	Required	Description	Example
to	`array`	true	list of recipients	`["4024431550","4024431551","4024439159"]`
from	`string`	true	originator of message	`14029999402`
body	`string`	true	message body	`Hello world, this is a test message!`
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","1111 Westroads Street","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 176a78b0-8e81-4e56-9e3f-da67d17915bb'
  --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 176a78b0-8e81-4e56-9e3f-da67d17915bb'

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)

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.

Example:

{
  "type": "mo",
  "to": "14029999402",
  "from": "14022770210",
  "body": "Hello there, this is a test message!",
  "received_at": "2019-02-19T21:22:46Z"
}

Property	Type	Description
type	`string`	callback type
to	`string`	phone number the message was sent to
from	`string`	phone number the message was sent from
body	`string`	body of message
received_at	`string`	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	Description
type	`string`	callback type
batch_id	`string`	ID of batch
message_id	`string`	ID of message
tag	`string`	custom string sent with batch
to	`string`	phone number the message was sent to
status	`string`	final message status
time	`string`	time message was sent in ISO 8601 format
error	`object`	error of message
error.code	`int`	detailed error code
error.description	`string`	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	Description
type	`string`	callback type
batch_id	`string`	ID of batch
batch_status	`string`	final batch status
tag	`string`	custom string sent with batch
count	`string`	number of messages in batch
results	`array`	final message results for batch
results.status	`string`	final message status
results.count	`int`	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	Description
type	`string`	callback type
batch_id	`string`	ID of batch
batch_status	`string`	final batch status
tag	`string`	custom string sent with batch
count	`string`	number of messages in batch
results	`array`	final message results for batch
results.status	`string`	final message status
results.count	`int`	number of messages with status
results.to	`array`	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

Messaging API Introduction

Base URL

Authentication

Persistent tokens

Short-lived tokens

Login Request

Applications

Actions

mo_callback

dr_callback

auto_reply

opt_in

opt_out

Create an application

HTTP Request

JSON Body Parameters

Replace an application

HTTP Request

URL Parameters

JSON Body Parameters

Modify an application

HTTP Request

URL Parameters

JSON Body Parameters

List applications

HTTP Request

Query Parameters

Retrieve an application

HTTP Request

URL Parameters

Delete an application

HTTP Request

URL Parameters

Longcodes

List longcodes

HTTP Request

Query Parameters

Retrieve a longcode

HTTP Request

URL Parameters

Update a longcode

HTTP Request

URL Parameters

JSON Body Parameters

Subscribers

Retrieve subscriber list

HTTP Request

URL Parameters

Query Parameters

Retrieve subscriber

HTTP Request

URL Parameters

Update subscriber

HTTP Request

URL Parameters

Create subscriber

HTTP Request

URL Parameters

JSON Body Parameters

Delete subscriber

HTTP Request

URL Parameters

Batches

List batches

HTTP Request

Query Parameters

Retrieve a batch

HTTP Request

URL Parameters

Send a batch

Parameterization

HTTP Request

JSON Body Parameters

Manage a batch

HTTP Request

URL Parameters

JSON Body Parameters

Retrieve a delivery report

HTTP Request

URL Parameters