Messaging (4.3.0)
Download OpenAPI specification:Download
The API Specification for Bandwidth's Messaging Platform
List Messages
Returns a list of messages based on query parameters.
Authorizations:
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) | |||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||
Array of objects (listMessageItem) | |||||||||||||||||||||||||||||||||||
Array
|
Request samples
- cURL
- C#
- Java
- Node.js
- PHP
- Python
- Ruby
curl 'https://messaging.bandwidth.com/api/v2/users/12345/messages?sourceTn=+15554443333' \ -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='
Response samples
- 200
- 400
- 401
- 403
- 404
- 415
- 429
- 500
{- "totalCount": 100,
- "pageInfo": {
- "prevPageToken": "DLAPE902",
- "nextPageToken": "GL83PD3C"
}, - "messages": [
- {
- "messageId": "1589228074636lm4k2je7j7jklbn2",
- "accountId": "9900000",
- "sourceTn": "+15554443333",
- "destinationTn": "+15554442222",
- "messageStatus": "RECEIVED",
- "messageDirection": "INBOUND",
- "messageType": "sms",
- "segmentCount": 1,
- "errorCode": 9902,
- "receiveTime": "2020-04-07T14:03:07.000Z",
- "carrierName": "other",
- "messageSize": 27,
- "messageLength": 18,
- "attachmentCount": 1,
- "recipientCount": 1,
- "campaignClass": "T",
- "campaignId": "CJEUMDK"
}
]
}
Create Message
Endpoint for sending text messages and picture messages using V2 messaging.
Authorizations:
path Parameters
accountId required | string Example: 9900000 Your Bandwidth Account ID. |
Request Body schema: application/jsonrequired
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 |
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
- Payload
- cURL
- C#
- Java
- Node.js
- PHP
- Python
- Ruby
{- "applicationId": "93de2206-9669-4e07-948d-329f4b722ee2",
- "to": [
- "+15554443333",
- "+15552223333"
], - "from": "+15551113333",
- "text": "Hello world",
- "tag": "custom string",
- "priority": "default",
- "expiration": "2021-02-01T11:29:18-05:00"
}
Response samples
- 202
- 400
- 401
- 403
- 404
- 406
- 415
- 429
- 500
{- "id": "1589228074636lm4k2je7j7jklbn2",
- "owner": "+15554443333",
- "applicationId": "93de2206-9669-4e07-948d-329f4b722ee2",
- "time": "2022-09-14T18:20:16.000Z",
- "segmentCount": 2,
- "direction": "in",
- "to": [
- "+15552223333"
], - "from": "+15553332222",
- "text": "Hello world",
- "tag": "custom tag",
- "priority": "default",
- "expiration": "2021-02-01T11:29:18-05:00"
}
Callback payload samples
{- "time": "2016-09-14T18:20:16.000Z",
- "type": "message-received",
- "to": "+15552223333",
- "description": "Incoming message received",
- "message": {
- "id": "1661365814859loidf7mcwd4qacn7",
- "owner": "+15553332222",
- "applicationId": "93de2206-9669-4e07-948d-329f4b722ee2",
- "time": "2016-09-14T18:20:16.000Z",
- "segmentCount": 1,
- "direction": "in",
- "to": [
- "+15552223333"
], - "from": "+15553332222",
- "text": "Hello world",
- "tag": "custom string",
- "priority": "default"
}
}
List Media
Gets a list of your media files. No query parameters are supported.
Authorizations:
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
Continuation-Token | string Continuation token used to retrieve subsequent media. |
Response Schema: application/json
content | string |
contentLength | integer |
mediaName | string |
Request samples
- cURL
- C#
- Java
- Node.js
- PHP
- Python
- Ruby
curl 'https://messaging.bandwidth.com/api/v2/users/12345/media' \ -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='
Response samples
- 200
- 400
- 401
- 403
- 404
- 406
- 415
- 429
- 500
[- {
- "content": "string",
- "contentLength": 0,
- "mediaName": "string"
}
]
Get Media
Downloads a media file you previously uploaded.
Authorizations:
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
Successful Operation
Request samples
- cURL
- C#
- Java
- Node.js
- PHP
- Python
- Ruby
curl 'https://messaging.bandwidth.com/api/v2/users/12345/media/media-id-123' \ -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='
Response samples
- 400
- 401
- 403
- 404
- 406
- 415
- 429
- 500
{- "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:
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
Responses
Request samples
- Payload
- cURL
- C#
- Java
- Node.js
- PHP
- Python
- Ruby
"string"
Response samples
- 400
- 401
- 403
- 404
- 406
- 415
- 429
- 500
{- "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:
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
- C#
- Java
- Node.js
- PHP
- Python
- Ruby
curl 'https://messaging.bandwidth.com/api/v2/users/12345/media/media-id-123' \ -X DELETE \ -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='
Response samples
- 400
- 401
- 403
- 404
- 406
- 415
- 429
- 500
{- "type": "string",
- "description": "string"
}