Skip to main content

Messaging (4.3.0)

Download OpenAPI specification:Download

The API Specification for Bandwidth's Messaging Platform

Base URL

https://messaging.bandwidth.com/api/v2

Messages

List Messages

Returns a list of messages based on query parameters.

Authorizations:
Basic
path Parameters
accountId
required
string
Example: 9900000

Your Bandwidth Account ID.

query Parameters
messageId
string
Example: messageId=9e0df4ca-b18d-40d7-a59f-82fcdf5ae8e6

The ID of the message to search for. Special characters need to be encoded using URL encoding. Message IDs could come in different formats, e.g., 9e0df4ca-b18d-40d7-a59f-82fcdf5ae8e6 and 1589228074636lm4k2je7j7jklbn2 are valid message ID formats. Note that you must include at least one query parameter.

sourceTn
string
Example: sourceTn=%2B15554443333

The phone number that sent the message. Accepted values are: a single full phone number a comma separated list of full phone numbers (maximum of 10) or a single partial phone number (minimum of 5 characters e.g. '%2B1919').

destinationTn
string
Example: destinationTn=%2B15554443333

The phone number that received the message. Accepted values are: a single full phone number a comma separated list of full phone numbers (maximum of 10) or a single partial phone number (minimum of 5 characters e.g. '%2B1919').

messageStatus
string (messageStatusEnum)
Enum: "RECEIVED" "QUEUED" "SENDING" "SENT" "FAILED" "DELIVERED" "ACCEPTED" "UNDELIVERED"
Example: messageStatus=RECEIVED

The status of the message. One of RECEIVED QUEUED SENDING SENT FAILED DELIVERED ACCEPTED UNDELIVERED.

messageDirection
string (listMessageDirectionEnum)
Enum: "INBOUND" "OUTBOUND"

The direction of the message. One of INBOUND OUTBOUND.

carrierName
string
Example: carrierName=Verizon

The name of the carrier used for this message. Possible values include but are not limited to Verizon and TMobile. Special characters need to be encoded using URL encoding (i.e. AT&T should be passed as AT%26T).

messageType
string (messageTypeEnum)
Enum: "sms" "mms"
Example: messageType=sms

The type of message. Either sms or mms.

errorCode
integer
Example: errorCode=9902

The error code of the message.

fromDateTime
string
Example: fromDateTime=2022-09-14T18:20:16.000Z

The start of the date range to search in ISO 8601 format. Uses the message receive time. The date range to search in is currently 14 days.

toDateTime
string
Example: toDateTime=2022-09-14T18:20:16.000Z

The end of the date range to search in ISO 8601 format. Uses the message receive time. The date range to search in is currently 14 days.

campaignId
string
Example: campaignId=CJEUMDK

The campaign ID of the message.

sort
string
Example: sort=sourceTn:desc

The field and direction to sort by combined with a colon. Direction is either asc or desc.

pageToken
string
Example: pageToken=gdEewhcJLQRB5

A base64 encoded value used for pagination of results.

limit
integer
Example: limit=50

The maximum records requested in search result. Default 100. The sum of limit and after cannot be more than 10000.

limitTotalCount
boolean
Example: limitTotalCount=true

When set to true, the response's totalCount field will have a maximum value of 10,000. When set to false, or excluded, this will give an accurate totalCount of all messages that match the provided filters. If you are experiencing latency, try using this parameter to limit your results.

Responses

Response Schema: application/json
totalCount
integer
Example: "100"

The total number of messages matched by the search. When the request has limitTotalCount set to true this value is limited to 10,000.

object (PageInfo)
prevPage
string
Example: "https://messaging.bandwidth.com/api/v2/users/accountId/messages?messageStatus=DLR_EXPIRED&nextPage=DLAPE902"

The link to the previous page for pagination.

nextPage
string
Example: "https://messaging.bandwidth.com/api/v2/users/accountId/messages?messageStatus=DLR_EXPIRED&prevPage=GL83PD3C"

The link to the next page for pagination.

prevPageToken
string
Example: "DLAPE902"

The isolated pagination token for the previous page.

nextPageToken
string
Example: "GL83PD3C"

The isolated pagination token for the next page.

Array of objects (listMessageItem)
Array
messageId
string
Example: "1589228074636lm4k2je7j7jklbn2"

The message id

accountId
string
Example: "9900000"

The account id associated with this message.

sourceTn
string
Example: "+15554443333"

The source phone number of the message.

destinationTn
string
Example: "+15554442222"

The recipient phone number of the message.

messageStatus
string (messageStatusEnum)
Enum: "RECEIVED" "QUEUED" "SENDING" "SENT" "FAILED" "DELIVERED" "ACCEPTED" "UNDELIVERED"
Example: "RECEIVED"

The status of the message. One of RECEIVED QUEUED SENDING SENT FAILED DELIVERED ACCEPTED UNDELIVERED.

messageDirection
string (listMessageDirectionEnum)
Enum: "INBOUND" "OUTBOUND"

The direction of the message. One of INBOUND OUTBOUND.

messageType
string (messageTypeEnum)
Enum: "sms" "mms"
Example: "sms"

The type of message. Either SMS or MMS.

segmentCount
integer
Example: "1"

The number of segments the message was sent as.

errorCode
integer
Example: "9902"

The numeric error code of the message.

receiveTime
string <date-time>
Example: "2020-04-07T14:03:07.000Z"

The ISO 8601 datetime of the message.

carrierName
string or null
Example: "other"

The name of the carrier. Not currently supported for MMS coming soon.

messageSize
integer or null
Example: "27"

The size of the message including message content and headers.

messageLength
integer
Example: "18"

The length of the message content.

attachmentCount
integer or null
Example: "1"

The number of attachments the message has.

recipientCount
integer or null
Example: "1"

The number of recipients the message has.

campaignClass
string or null
Example: "T"

The campaign class of the message if it has one.

campaignId
string or null
Example: "CJEUMDK"

The campaign ID of the message if it has one.

Request samples

curl 'https://messaging.bandwidth.com/api/v2/users/12345/messages?sourceTn=+15554443333' \
    -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

Response samples

Content type
application/json
{}

Create Message

Endpoint for sending text messages and picture messages using V2 messaging.

Authorizations:
Basic
path Parameters
accountId
required
string
Example: 9900000

Your Bandwidth Account ID.

Request Body schema: application/json
required
applicationId
required
string
Example: "93de2206-9669-4e07-948d-329f4b722ee2"

The ID of the Application your from number is associated with in the Bandwidth Phone Number Dashboard.

to
required
Array of strings unique
Example: "+15554443333,+15552223333"

The phone number(s) the message should be sent to in E164 format.

from
required
string
Example: "+15551113333"

Either an alphanumeric sender ID or the sender's Bandwidth phone number in E.164 format, which must be hosted within Bandwidth and linked to the account that is generating the message. Alphanumeric Sender IDs can contain up to 11 characters, upper-case letters A-Z, lower-case letters a-z, numbers 0-9, space, hyphen -, plus +, underscore _ and ampersand &. Alphanumeric Sender IDs must contain at least one letter.

text
string <= 2048 characters
Example: "Hello world"

The contents of the text message. Must be 2048 characters or less.

media
Array of strings <uri> [ items <uri > <= 4096 characters ]
Example: "https://dev.bandwidth.com/images/bandwidth-logo.png,https://dev.bandwidth.com/images/github_logo.png"

A list of URLs to include as media attachments as part of the message. Each URL can be at most 4096 characters.

tag
string
Example: "custom string"

A custom string that will be included in callback events of the message. Max 1024 characters.

priority
string (priorityEnum)
Enum: "default" "high"
Example: "default"

The priority specified by the user.

Not supported on MMS.

expiration
string <date-time>
Example: "2021-02-01T11:29:18-05:00"

A string with the date/time value that the message will automatically expire by. This must be a valid RFC-3339 value, e.g., 2021-03-14T01:59:26Z or 2021-03-13T20:59:26-05:00. Must be a date-time in the future. Not supported on MMS.

Responses

Response Schema: application/json
id
string
Example: "1589228074636lm4k2je7j7jklbn2"

The id of the message.

owner
string
Example: "+15554443333"

The Bandwidth phone number associated with the message.

applicationId
string
Example: "93de2206-9669-4e07-948d-329f4b722ee2"

The application ID associated with the message.

time
string <date-time>
Example: "2022-09-14T18:20:16.000Z"

The datetime stamp of the message in ISO 8601

segmentCount
integer
Example: "2"

The number of segments the original message from the user is broken into before sending over to carrier networks.

direction
string (messageDirectionEnum)
Enum: "in" "out"

The direction of the message. One of in out.

to
Array of strings unique
Example: "+15552223333"

The phone number recipients of the message.

from
string
Example: "+15553332222"

The phone number the message was sent from.

media
Array of strings unique
Example: "https://dev.bandwidth.com/images/bandwidth-logo.png"

The list of media URLs sent in the message. Including a filename field in the Content-Disposition header of the media linked with a URL will set the displayed file name. This is a best practice to ensure that your media has a readable file name.

text
string
Example: "Hello world"

The contents of the message.

tag
string
Example: "custom tag"

The custom string set by the user.

priority
string (priorityEnum)
Enum: "default" "high"
Example: "default"

The priority specified by the user.

Not supported on MMS.

expiration
string <date-time>
Example: "2021-02-01T11:29:18-05:00"

The expiration date-time set by the user.

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "1589228074636lm4k2je7j7jklbn2",
  • "owner": "+15554443333",
  • "applicationId": "93de2206-9669-4e07-948d-329f4b722ee2",
  • "time": "2022-09-14T18:20:16.000Z",
  • "segmentCount": 2,
  • "direction": "in",
  • "to": [
    ],
  • "from": "+15553332222",
  • "text": "Hello world",
  • "tag": "custom tag",
  • "priority": "default",
  • "expiration": "2021-02-01T11:29:18-05:00"
}

Callback payload samples

Callback
Content type
application/json
{
  • "time": "2016-09-14T18:20:16.000Z",
  • "type": "message-received",
  • "to": "+15552223333",
  • "description": "Incoming message received",
  • "message": {}
}

Media

List Media

Gets a list of your media files. No query parameters are supported.

Authorizations:
Basic
path Parameters
accountId
required
string
Example: 9900000

Your Bandwidth Account ID.

header Parameters
Continuation-Token
string
Example: 1XEi2tsFtLo1JbtLwETnM1ZJ+PqAa8w6ENvC5QKvwyrCDYII663Gy5M4s40owR1tjkuWUif6qbWvFtQJR5/ipqbUnfAqL254LKNlPy6tATCzioKSuHuOqgzloDkSwRtX0LtcL2otHS69hK343m+SjdL+vlj71tT39

Continuation token used to retrieve subsequent media.

Responses

Response Headers
Continuation-Token
string

Continuation token used to retrieve subsequent media.

Response Schema: application/json
Array
content
string
contentLength
integer
mediaName
string

Request samples

curl 'https://messaging.bandwidth.com/api/v2/users/12345/media' \
    -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

Response samples

Content type
application/json
[
  • {
    }
]

Get Media

Downloads a media file you previously uploaded.

Authorizations:
Basic
path Parameters
accountId
required
string
Example: 9900000

Your Bandwidth Account ID.

mediaId
required
string
Example: 14762070468292kw2fuqty55yp2b2/0/bw.png

Media ID to retrieve.

Responses

Response Schema: application/octet-stream
string <binary>

Successful Operation

Request samples

curl 'https://messaging.bandwidth.com/api/v2/users/12345/media/media-id-123' \
    -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

Response samples

Content type
application/json
{
  • "type": "string",
  • "description": "string"
}

Upload Media

Upload a file. You may add headers to the request in order to provide some control to your media file.

If a file is uploaded with the same name as a file that already exists under this account, the previous file will be overwritten.

A list of supported media types can be found here.

Authorizations:
Basic
path Parameters
accountId
required
string
Example: 9900000

Your Bandwidth Account ID.

mediaId
required
string
Example: 14762070468292kw2fuqty55yp2b2/0/bw.png

Media ID to retrieve.

header Parameters
Content-Type
string
Example: audio/wav

The media type of the entity-body.

Cache-Control
string
Example: no-cache

General-header field is used to specify directives that MUST be obeyed by all caching mechanisms along the request/response chain.

Request Body schema:
required
string <binary>

Responses

Request samples

Content type
"string"

Response samples

Content type
application/json
{
  • "type": "string",
  • "description": "string"
}

Delete Media

Deletes a media file from Bandwidth API server. Make sure you don't have any application scripts still using the media before you delete.

If you accidentally delete a media file you can immediately upload a new file with the same name.

Authorizations:
Basic
path Parameters
accountId
required
string
Example: 9900000

Your Bandwidth Account ID.

mediaId
required
string
Example: 14762070468292kw2fuqty55yp2b2/0/bw.png

Media ID to retrieve.

Responses

Request samples

curl 'https://messaging.bandwidth.com/api/v2/users/12345/media/media-id-123' \
    -X DELETE \
    -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

Response samples

Content type
application/json
{
  • "type": "string",
  • "description": "string"
}