Manage Third-Party Text Enablement

note

The Third Party Text Enablement API will not be available until January 2026

This guide walks through how to manage requests to take messaging using webhook notifications and the Third Party Text Enablement API.

Webhooks Subscription

To receive notifications of third-party text enablement 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 Third Party Text Enablement 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 Third_Party_Text_Enablement subscription definition name when creating the subscription.

Example

{
  "accountId": "1003520",
  "customName": "My TPTE Subscription",
  "subscriptionDefinitionName": "Third_Party_Text_Enablement",
  "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 third-party text enablement 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 third-party text enablement request via webhook, you can approve or deny the request using the Third Party Text Enablement API, specifically the Approve or Deny Endpoint. The requestId from the webhook payload must be provided in the URL path.

Example Approval

{
  "approval": "YES"
}

Example Denial

{
  "approval": "NO",
  "comment": "Optional comment"
}