Skip to main content

Webhooks

Bandwidth uses HTTP Callbacks webhooks to send events to any publicly addressable url, as defined in your messaging application.

Overview​

  • All Message callbacks are sent as a list/array [ {message metadata} ] to the webhook url in the application.
  • You MUST Reply with a HTTP 2xx status code for every callback/delivery receipt. Bandwidth will retry every callback over the next 24 hours until a HTTP 2xx code is received for the callback. After 24 hours, Bandwidth will no longer try to send the callback.
  • Bandwidth's Messaging platform has a 10 second timeout for callbacks. This means your server must respond to the callback request within 10 seconds, otherwise the platform will try again at a later time.
  • Because we guarantee "at least once delivery" of events, it is possible (but not common) to receive duplicate message events. Your server should be able to handle duplicates.

Inbound Message Webhooks​

For incoming messages sent to your numbers, a callback will also be received, notifying your Application of the incoming message. For group messages where you own multiple recipient phone numbers, you will receive a distinct event and messageId for each individual recipient.

In order to receive text messages events, you need to ensure you have set up your application to send callbacks to your server's URL

When sending to Group Messages, there is a maximum of 10 participants in a Group.

For inbound messages, we do not limit the amount of recipients. We will pass along any messages we receive, even if there are more than 10 recipients. If you wanted to reply to all 9+{n} recipients using V2 APIs, Bandwidth will reply with a 400 error (as you are limited to 10 recipients when sending outbound). You will need to break up the responses into separate messages to respond to more than 9+{n} participants

Message Received​

You will receive this webhook when a message is sent to a message-enabled Bandwidth telephone number on your account.

Request Parameters​

ParameterTypeDescription
typestringThe Event type
timestringThe time of the event described in the receipt
descriptionstringA detailed description of the event described by the receipt
tostringThe destination number for an outbound message receipt
messageObjectAn object of message information
message.idstringThe unique ID of this message
message.ownerstringThe phone number this particular message is associated with.
For an outbound message, this is always the from number.
For an inbound message, this will be (one of) the to number(s).
For instance, if this is an inbound group message, the owner field will be set to the to number that this particular copy of the group message belongs to.
message.timestringThe time stamp of when message was created
message.directionstringWhether the message was sent from Bandwidth, or received by a Bandwidth number
message.toarrayThe phone number (or numbers) the message the message is sent to. On a POST, this can be a String, or an array of one or more numbers. In all other places, this will be an array.
message.fromstringThe phone number the message was sent from
message.textstringThe text content of the message
message.applicationIdstringThe ID of the Application your from number is associated with.
message.mediaarrayA list of URLs to include as media attachments as part of the message.
Using the v2 media api you can download the media WITHIN 2 DAYS

The URL will look something like:
https://messaging.bandwidth.com/api/v2/users/{accountId}/media/{uploaded-file-name}

Where filename is the original filename of your uploaded media.
message.segmentCountintThis indicates the number of segments the original message from the user is broken into before sending over to carrier networks. Segmentation of messages depends on the size and encoding. Bandwidth will segment the message if the character count is over the below limits:

- 160 for GSM-7
- 70 for UCS-2

For MMS messages the segment count will always be set to 1

Examples​

POST /your_url HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: BandwidthAPI/v2

[
  {
    "time"          : "2025-01-06T15:43:35.502180Z",
    "type"          : "message-received",
    "to"            : "+12345678902",
    "description"   : "Incoming message received",
    "message"       : {
      "id"            : "14762070468292kw2fuqty55yp2b2",
      "owner"         : "+12345678902",
      "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",
      "time"          : "2025-01-06T15:43:34.000000Z",
      "segmentCount"  : 1,
      "direction"     : "in",
      "to"            : ["+12345678902"],
      "from"          : "+12345678901",
      "text"          : "Hey, check out this SMS!"
    }
  }
]

Outbound Message Webhooks​

Callbacks will be sent via an HTTP POST request to the Callback URL for the Application associated with the applicationId field sent with the send message payload. You will get a callback for any event related to that message.

  • For example, you will get an HTTP callback when your message is delivered, or blocked. In addition, you will get an event for any kind of Delivery Receipt that the destination carrier sends back, regarding the delivery of your message.

For each outbound message, you will receive either (but not both) a Message Delivered or Message Failed event.

  • It is essential to check the direction of the message in the callback you receive. For example, if your use case depends on responding to inbound messages, you do not want to respond to an outbound message callback. This could create a loop of messages being sent from your account as you continuously respond to outbound message callbacks.

Messaging delivery receipts are enabled by default for all accounts but can be disabled on request (Message Sending, Message Delivered, Message Failed).

Message Sending​

This callback will be sent to your configured callback URL only when an MMS message is sent to the mobile aggregator or carrier, but before the terminal events (message delivered, message failed).

Message Delivered​

This callback will be sent to your configured callback URL when the carrier or aggregator confirms that they received and successfully sent the message to the recipient.

Message Failed​

This callback will be sent to your configured callback URL if your message failed to be delivered to the carrier or was rejected by the carrier. The error code will be included in the callback.

Request Parameters​

ParameterTypeDescription
typestringThe Event type
timearrayThe time of the event described in the receipt
descriptionstringA detailed description of the event described by the receipt
tostringThe destination number for an outbound message receipt
messageObjectAn object of message information
message.idstringThe unique ID of this message
message.ownerstringThe phone number this particular message is associated with.
For an outbound message, this is always the from number.
For an inbound message, this will be (one of) the to number(s).
For instance, if this is an inbound group message, the owner field will be set to the to number that this particular copy of the group message belongs to.
message.timestringThe time stamp of when message was created
message.directionstringThe direction of the message relative to Bandwidth. Will only be out for this event
message.toarrayThe phone number (or numbers) the message the message is sent to. On a POST, this can be a String, or an array of one or more numbers. In all other places, this will be an array.
message.fromstringThe phone number the message was sent from
message.textstringEmpty text/string. Message text content will not be sent in callback.
message.applicationIdstringThe ID of the Application your from number is associated with.
message.mediaarrayA list of URLs to include as media attachments as part of the message
message.tagstringAn custom String that you can use to track this particular message
message.segmentCountintThis indicates the number of segments the original message from the user is broken into before sending over to carrier networks

Examples​

POST /your_url HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: BandwidthAPI/v2

[
    {
        "time": "2020-06-25T18:42:36.979833Z",
        "type": "message-sending",
        "to": "+15554443333",
        "description": "Message is sending to carrier",
        "message": {
            "id": "1593110555875xo7watq5px6rbe5d",
            "owner": "+15552221111",
            "applicationId": "cfd4fb83-7531-4acc-b471-42d0bb76a65c",
            "time": "2020-06-25T18:42:35.876004Z",
            "segmentCount": 1,
            "direction": "out",
            "to": ["+15554443333"],
            "from": "+15552221111",
            "text": "",
            "media": ["https://dev.bandwidth.com/images/bandwidth-logo.png"],
            "tag": "v2 lab"
        }
    }
]
Need help? Reach out to our team for dev tips
Contact Us
Our Company
About UsBlogContactNewsroomCareersInvestor RelationsLeadership
Quicklinks
SupportService StatusDevelopersResourcesSecurityPartner ProgramCustomersRelease NotesGlossaryTwilio AlternativeRegulations
Legal
GeneralAccessibilityLaw Enforcement GuideBandwidth Privacy NoticeReport a Phone NumberCookie NoticeTerms of Use
Request trialTalk to an expert
Call Us
+1 800 808 5150
Bandwidth.com CLEC, LLC is a wholly owned subsidiary of Bandwidth Inc. ©2025