SMS Messaging API

Notice: The SMS Messaging API is in Alpha. Please contact your CSM or the support team for more information.

Overview

The SMS Messaging API provides the following functionality:

  • manage SMS-enabled phone numbers

  • send SMS messages

  • retrieve SMS messages and their associated Delivery Reports

Authentication and Authorization

The SMS Messaging API uses OAuth2 Tokens for authentication and authorization. Please see Design Principles for more information about generating an OAuth2 Token in the Invoca platform. Unlike other Invoca APIs, the SMS Messaging API uses the Bearer authentication scheme, and this must be indicated in the Authorization header of requests. For example: Authorization: Bearer <token>

Pagination

The following URL parameters are used to control pagination and are common to all GET requests.

Pagination URL Parameters

Parameter

Description

Default Value

Max Value

Required

limit

The maximum number of records returned per page

100

500

False

page

The next or previous page as taken directly from the response body payload of a previous API request for the previous page of the same read operation

N/A (assumed to be the first page)

N/A

False

Sorting

The records returned by GET requests can be sorted using the sort URL parameter. The value of the sort parameter is comprised of:

  • an optional valid sortable field

  • an optional sort direction (asc or desc) separated from the sortable field by a colon (:)

For example: https://messaging.invoca.net/sms/2022-08-01/messages?sort=created_at:asc

If only a sort direction is provided, the response body will be sorted in the provided direction according to the default sortable field.

If only a sortable field is provided, the default sort direction (asc) will be assumed.

Each GET request denotes the valid sortable fields in its response body. Please see the API examples below for more information.

At this time, responses may be sorted by one field only.

By default, responses are sorted in ascending order according to their created_at field.

Filtering

The records returned by GET requests can be filtered using URL parameters. Filters are comprised of the following required components:

  • a valid filterable field

  • a bracketed operator appended to the filterable field

  • a filter value separated from the filterable field and its associated operator by an equal sign (=)

For example: https://messaging.invoca.net/sms/2022-08-01/messages?created_at[lte]=2022-11-03T23:59:00.000Z.

The following operators are supported:

Supported Filter Operators

Operator

Description

Example

eq

Return only those records where the filtered field is equal to the value found on the right-hand side of the = in this parameter

direction[eq]=in

lte

Return only those records where the filtered field is less than or equal to the value found on the right-hand side of the = in this parameter

created_at[lte]=2022-11-03T23:59:00.000Z

gte

Return only those records where the filtered field is greater than or equal to the value found on the right-hand side of the = in this parameter

created_at[gte]=2022-11-03T23:59:00.000Z

empty

Return only those records where the filtered field has an empty value such as integer 0, MySQL NULL/null, or an empty string

deleted_at[empty]

Each GET request denotes the valid filterable fields in its response body. Please see the API examples below for more information.

For ranges of filtered data, such as dates, the lte and gte operators may be combined for the same filterable field. For example:

created_at[gte]=2022-11-01T23:59:00.000Z&created_at[lte]=2022-11-03T23:59:00.000Z.

Any combination of filters assumes AND operations between members of the completed set of filters.

If an E.164-formatted phone number is provided as a query parameter value, the leading + must be url-encoded as %2B.

For example: https://messaging.invoca.net/sms/2022-08-01/messages?from[eq]=%2B1234567890

By default, responses are filtered by created_at for the current date.

Example Requests

Base endpoint: https://messaging.invoca.net/sms/2022-08-01