# Send Messages This guide walks through sending text and picture messages using the Bandwidth Messaging API. Requests use OAuth 2.0 bearer token authentication — see [Credentials & Authentication](/docs/account/credentials/management.md) to obtain a token. ## The Request[​](#the-request "Direct link to The Request") ``` POST https://messaging.bandwidth.com/api/v2/users/{accountId}/messages HTTP/1.1 Content-Type: application/json; charset=utf-8 Authorization: Bearer {YOUR_ACCESS_TOKEN} { "to" : ["+12345678902"], "from" : "+12345678901", "text" : "Hey, check this out!", "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2", "tag" : "test message", } ``` Please visit the [API Reference](/apis/messaging-apis/messaging.md#tag/Messages/operation/createMessage) for details on all available request body parameters. Sending a text message is as simple as making an API POST request to Bandwidth's messaging API with the following information: * Who the message is `from` (a Bandwidth number) * Who the message is `to` (a PSTN number) * The `text` of the message - what you want to say. See our [FAQ](https://www.bandwidth.com/support/en/articles/12823182-what-are-bandwidth-s-sms-character-limits-and-concatenation-practices) for SMS character limits and concatenation practices. * The messaging `applicationId` associated with the `from` number * Your basic auth `username` and `password` in the `Authorization` header * Optional: A `media` url that links to an attachment/file you wish to send * Optional: A `tag` to help categorize your message * Optional: `priority` set to 'high' allows you to bump important conversational traffic to the front of your queue ### Tags[​](#tags "Direct link to Tags") If there is a need to identify individual outbound messages, or correlate them with an ID in your own application, the `tag` field can be set to any string (max 1024 chars). The custom `tag` will be included in all callbacks for an outbound message. caution The tag field is intended for use in correlation/troubleshooting. **You should not include sensitive or personally-identifiable information in the tag field.** ## The Response[​](#the-response "Direct link to The Response") ``` HTTP/1.1 202 Accepted Content-Type: application/json { "id": "14762070468292kw2fuqty55yp2b2", "owner": "+12345678901", "applicationId": "93de2206-9669-4e07-948d-329f4b722ee", "time": "2021-07-21T21:00:45.179Z", "segmentCount": 1, "direction": "out", "to": [ "+12345678902" ], "from": "+12345678901", "text": "Hello World", "tag": "test message", "priority": "default" } ``` Once successfully received, Bandwidth responds with an `HTTP 202 Accepted` response, confirming your message has been successfully created. You will recieve a unique `messageId` for each message sent, which can be used to query for status using our [`GET /messages`](/apis/messaging-apis/messaging.md#tag/Messages/operation/listMessages) endpoint. Once the message has passed through Bandwidth's network, you can elect to receive [status webhooks](/docs/messaging/webhooks.md#outbound-message-webhooks) confirming whether or not the message was successfully delivered. Bandwidth sends these to the status callback URL defined in your [messaging application](/docs/account/app-setup.md#create-a-messaging-application). note Bandwidth does not store text message content (the content in the `text` field). After sending the API request it is inaccessible and will not be returned in subsequent status callbacks or GET requests. If you need this information, it is recommended that you log or store it in your application. ## Examples[​](#examples "Direct link to Examples") Please visit the [API Reference](/apis/messaging-apis/messaging.md) for code samples using the various SDKs. ### Send a single message[​](#send-a-single-message "Direct link to Send a single message") > Request ``` POST https://messaging.bandwidth.com/api/v2/users/{accountId}/messages HTTP/1.1 Content-Type: application/json; charset=utf-8 Authorization: Bearer {YOUR_ACCESS_TOKEN} { "to" : ["+12345678902"], "from" : "+12345678901", "text" : "Hey, check this out!", "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2", "tag" : "test message", "priority" : "default" } ``` > Response ``` HTTP/1.1 202 Accepted Content-Type: application/json { "id": "14762070468292kw2fuqty55yp2b2", "owner": "+12345678901", "applicationId": "93de2206-9669-4e07-948d-329f4b722ee", "time": "2021-07-21T21:00:45.179Z", "segmentCount": 1, "direction": "out", "to": [ "+12345678902" ], "from": "+12345678901", "text": "Hello World", "tag": "test message", "priority": "default" } ``` ### Send a group message[​](#send-a-group-message "Direct link to Send a group message") > Request ``` POST https://messaging.bandwidth.com/api/v2/users/{accountId}/messages HTTP/1.1 Content-Type: application/json; charset=utf-8 Authorization: Bearer {YOUR_ACCESS_TOKEN} { "to" : ["+12345678902", "+12345678903", "+12345678904"], "from" : "+12345678901", "text" : "Hey, check this out!", "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2", "tag" : "test message", "priority" : "default" } ``` > Response ``` HTTP/1.1 202 Accepted Content-Type: application/json { "id": "14762070468292kw2fuqty55yp2b2", "owner": "+12345678901", "applicationId": "93de2206-9669-4e07-948d-329f4b722ee", "time": "2021-07-21T21:00:45.179Z", "segmentCount": 1, "direction": "out", "to": [ "+12345678902", "+12345678903", "+12345678904" ], "from": "+12345678901", "text": "Hello World", "tag": "test message", "priority": "default" } ``` ### Send a picture message[​](#send-a-picture-message "Direct link to Send a picture message") > Request ``` POST https://messaging.bandwidth.com/api/v2/users/{accountId}/messages HTTP/1.1 Content-Type: application/json; charset=utf-8 Authorization: Bearer {YOUR_ACCESS_TOKEN} { "to" : ["+12345678902"], "from" : "+12345678901", "text" : "Hey, check this out!", "media" : ["https://mySite.com/images/test_image.jpg"], "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2", "tag" : "test message", "priority" : "default" } ``` > Response ``` HTTP/1.1 202 Accepted Content-Type: application/json { "id": "14762070468292kw2fuqty55yp2b2", "owner": "+12345678901", "applicationId": "93de2206-9669-4e07-948d-329f4b722ee", "time": "2021-07-21T21:00:45.179Z", "segmentCount": 1, "direction": "out", "to": [ "+12345678902" ], "from": "+12345678901", "text": "Hey, check this out!", "media": ["https://mySite.com/images/test_image.jpg"], "tag": "test message", "priority": "default" } ```