Navbar
shell
  • Messaging API Introduction
  • Authentication
  • Applications
  • Longcodes
  • Subscribers
  • Batches
  • Callbacks
  • Statuses
  • Errors
  • 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": ""
    }
    

    Login Request

    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:

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

    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