Manage Messaging Transfer Confirmation

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 Format

There are two types of Messaging Transfer requests: Third party and Bandwidth. 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. The following lists the format for Messaging Transfer Confirmation webhooks. The format is the same for both types of requests.

Parameter	Type	Description
notificationType	string	PORTOUT_REQUEST
phoneNumber	string	The phone number being transferred, in E.164 format (e.g. +15555555555)
oldNnid	string	The current NNID
newNnid	string	The destination NNID
overwriterCarrier	string	Identifier of the carrier requesting enablement. Will be bandwidth for Bandwidth generated requests.
requestId	string	Unique identifier for the request
activation	date-time	Timestamp of when the request was made

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"
}