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/@@SMS_MESSAGING_API_VERSION/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/@@SMS_MESSAGING_API_VERSION/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/@@SMS_MESSAGING_API_VERSION/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/@@SMS_MESSAGING_API_VERSION

Interactive API examples are available via the Swagger UI embedded in the original developer portal. Please contact your CSM or support team for access to the live API reference.

​Overview

​Authentication and Authorization

​Pagination

​Pagination URL Parameters

​Sorting

​Filtering

​Supported Filter Operators

​Example Requests

Overview

Authentication and Authorization

Pagination

Pagination URL Parameters

Sorting

Filtering

Supported Filter Operators

Example Requests