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.

Delivery receipts are now supported for MMS & Group Messaging. During this beta phase, you will need to request this functionality to be enabled on your account. Once enabled you will need to support all three possible callback events for MMS (Message Delivered, Message Failed, & Message Queued callbacks). Visit our Support Site to learn more about enabling MMS DLR on your account.

Message Sending​

You will receive this callback between when the message is received by Bandwidth and the terminal events (message delivered, message failed) for MMS only if you have the Feature_MMS_DLR feature flag enabled.

Message Delivered​

MMS and Group messages do currently support delivery receipts. However, you will need to have this enabled. Without the delivery receipts enabled, you will still receive a message delivered event when the message is sent. The message delivered event will not represent true delivery for only MMS and Group Messages. This will mean your message has been handed off to the Bandwidth's MMSC network, but has not been confirmed at the downstream carrier.

Message Failed​

For MMS and Group Messages, you will only receive this callback if you have enabled delivery receipts on MMS.

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