Manage Messaging Transfer Confirmation

note

The Messaging Transfer Confirmation API will not be available until January 2026

This guide walks through how to manage requests to take messaging using webhook notifications and the Messaging Transfer Confirmation API.

Webhooks Subscription

To receive notifications of Messaging Transfer Confirmation requests you must first subscribe to the notifications using Bandwidth's Subscriptions Platform.

Subscribing can be accomplished in the Bandwidth App under Account -> Notifications. Select Messaging Transfer Confirmation as the Event Type.

You can also subscribe programmatically using the Subscriptions API. To do so use the Create Subscription endpoint to create a webhookSubscriptionRequest. It is important to use the Messaging_Transfer_Confirmation subscription definition name when creating the subscription.

Example

{
    "accountId": "1003520",
    "customName": "My MTC Subscription",
    "subscriptionDefinitionName": "Messaging_Transfer_Confirmation",
    "deliveryType": "WEBHOOK",
    "webhookSubscription": {
        "url": "https://test.example.com/webhook-endpoint",
        "authentication": {
            "basicAuthentication": {
                "username": "apiUser",
                "password": "testPassword"
            }
        }
    },
    "filters": [
        {
            "field": "oldNnid",
            "operator": "EQ",
            "value": "103462"
        }
    ]
}

Webhook Payload Formats

The following lists the two possible payload formats for Messaging Transfer Confirmation webhooks. A third party generated request is one that originates from a carrier outside of Bandwidth. A Bandwidth generated request is one that originates from another Bandwidth account.

Third Party Generated

Parameter	Type	Description
notificationType	string	PORTOUT_REQUEST
phoneNumber	string	The time of the event described in the receipt
oldNnid	string	The current NNID
newNnid	string	The destination NNID
overwriterCarrier	string	Identifier of the carrier requesting enablement
requestId	string	Unique identifier for the request
activation	date-time	Timestamp of when the request was made

Bandwidth Generated

Parameter	Type	Description
notificationType	string	PORTOUT_REQUEST
phoneNumber	string	The time of the event described in the receipt
oldNnid	string	The current NNID
newNnid	string	The destination NNID
overwriterCarrier	string	Identifier of the carrier requesting enablement
requestId	string	Unique identifier for the request
activation	date-time	Timestamp of when the request was made
newAccountId	string	The Bandwidth account ID of the new account requesting the messaging on the phone number
newAccountBusinessName	string	The business name of the account requesting the messaging on the phone number

Approving or Denying Requests

Once you receive a Messaging Transfer Confirmation request via webhook, you can approve or deny the request using the Messaging Transfer Confirmation API, specifically the Approve or Deny Endpoint. The requestId from the webhook payload must be provided in the URL path.

Example Approval

{
    "status": "APPROVED"
}

Example Denial

{
    "status": "DENIED",
    "comment": "Optional comment"
}