Application Address Mechanics
Longcode Provisioning:
To be able to send A2P messaging traffic for 10DLC campaigns to registered subscribers on T-Mobiles network requires additional implementation steps beyond OSR updates that are required as part of the provisioning for other MNO’s.
For T-Mobile, customers must map individual phone numbers to the campaigns to allow for A2P messaging to be delivered on T-Mobile’s network.
Unregistered traffic will NOT be accepted on T-Mobile A2P Routes. It is important that OSR is updated for the phone number(s) used for your campaigns with the ‘A2P’ context flag.
Syniverse provides a 10DLC API that will provision phone numbers to the T-Mobile platform accordingly.
Syniverse’s longcode provisioning api supports the following actions:
- Customer can call the Syniverse API for adding longcodes to the campaign.
- Customer can call the Syniverse API for deleting longcodes from the campaign.
In addition to provisioning the longcodes for your campaigns to T-Mobiles platform, the API also performs validation checks prior to submission to the MNO that will help ensure the longcode is set-up correctly and is successfully provisioned.
E.g. The api performs validation checks to ensure certain longcode provisioning is correct in OSR before sending the request to the MNO.
The following OSR checks are performed:
- NNID validation – check that a nnid exists in OSR for the longcode to be provisioned.
- Longcode ownership – check the nnid for the longcode to be provisioned is owned by the customer making the longcode provisioning request.
- Campaign Id cross-check – Check the campaign Id provisioned in OSR is the same as the campaign Id sent as part of the longcode provisioning request.
An ESS event will be sent to the customer should the longcode provisioning request fail any of the OSR validations defined above.
Note: To avoid potential provisioning issues with longcode add requests (and further down the line, message delivery), the customer needs to ensure OSR is updated with the campaign Id, A2P context flag and your nnid for each longcode provisioned to a campaign to reduce the risk of longcode provisioning failures at T-Mobile and for the correct delivery of your messaging.
The api for adding longcodes to a campaign is:
POST /engage/tendlc-services/v2/campaigns/{campaignId}/longcodes/{longcode}
When can I provision longcodes to my campaign?
Longcode add requests can be submitted following successful provisioning of the campaign to T-Mobile and the campaign is considered DEPLOYED.
Following the successful implementation of the campaign at T-Mobile, customers will receive an ESS event from Syniverse confirming the campaign is in a DEPLOYED state.
On receipt of this event notification, longcode add requests can be submitted to Syniverse.
Note: Longcode provisioning requests made to a campaign where the campaign is not in a DEPLOYED state will be rejected. It is important that you wait to receive the DEPLOYED ESS event from Syniverse before adding longcodes.
Following the successful provisioning of a longcode to the MNO platform, Syniverse will return an ADDED ESS event to the customer with the following description:
10DLC <longcode> added to campaign <campaignId> successfully.
What information do I provide as part of a longcode provisioning request?
Longcode provisioning requests will be triggered from the customers own provisioning application by calling the Syniverse API. Syniverse’s API for adding longcodes to a 10DLC campaign requires 2 parameters to be provided as part of the provisioning request:
- Campaign Id – The campaign Id the longcode is to be mapped to.
- Longcode – The longcode (phone number) from which messaging traffic will be sent.
The result of the longcode provisioning request will be communicated back to the customer via ESS notification events.
Application Address Management API
Once notification has been received confirming the successful provisioning of the longcode, messaging traffic can be sent to the MNO on the sanctioned 10DLC A2P routes.
Deleting longcodes from a campaign:
A similar flow exists where the customer wishes to delete a longcode from a campaign.
Syniverse’s API for removing longcodes from a 10DLC campaign requires 2 parameters to be provided as part of the provisioning request:
- Campaign Id – The campaign Id the longcode is to be removed from.
- Longcode – The longcode (phone number) that is to be removed from the campaign.
The api for removal of a longcode is:
DELETE /engage/tendlc-services/v2/campaigns/{campaignId}/longcodes/{longcode}
Following the successful deletion of a longcode from the campaign registered on the MNO platform, Syniverse will return a DELETED ESS event to the customer with the following description:
10DLC <longcode> deleted from campaign <campaign Id> successfully.
About Syniverse Long Code Status
Once accepted into queue for processing a 10 Digit Long Code can have one of the following statuses:
PENDING = is an interim status that indicates a customer requested association of an Application Address Long Code with a campaign has been received.
DEPLOYED = Longcode is in the process of being provisioned to T-Mobile.
ADDED = longcode has been successfully added to the campaign.
DEPLOYED_FAILED / ADD_FAILED = the system receives a non-retriable error from T-Mobile or exhausts the retry mechanism while trying to deploy and add that application address to a campaign.
MARK_DELETE = Customer API call requesting a longcode to be removed from a campaign has been received.
DELETED = Longcode has been successfully disassociated from the campaign.
REMOVED = Longcode has been completely removed from T-Mobile and is available for reuse. Longcodes in this status can be recycled and added to a different campaign.
DELETE_FAILED / REMOVE_FAILED = the system receives non-retriable error from the MNO API or exhausts the retry mechanism while trying to remove the application address from the campaign or set long code free and in remove state.
ESS events for longcode provisioning
| ESS status | Description | Additional Comments |
| ADDED | "10DLC xxxxxxxxxxx added to campaign Cxxxxxx successfully." | |
| ADD_FAILED | <text staring with keywords RETRY: or TICKET: or INFO: followed by a message>", | There is no fixed text response for longcodes that fail during the longcode add provisioning flow. Syniverse will pass on the error response received from the downstream platform as part of the ESS event. |
| DELETED | 10DLC xxxxxxxxxxx deleted from campaign Cxxxxxx successfully. | |
| DELETE_FAILED | <text staring with keywords RETRY: or TICKET: or INFO: followed by a message>", | There is no fixed text response for longcodes that fail during the longcode removal provisioning flow. Syniverse will pass on the error response received from the downstream platform as part of the ESS event. |
ESS Notification examples for Adding/Deleting longcodes and OSR validation checks
Successful operation ESS Notification Event Payload
|
NOTIFICATION final notification successful Long Code addition |
|
|
{ } |
|
|
NOTIFICATION final notification successful Long Code Delete operation |
|||||||||||||
|
{
|
|||||||||||||
Number Pools - Campaigns with more 49 longcodes
T-Mobile imposes a limit of 49 longcodes that may be provisioned for a single campaign. Where the customer identifies the campaign use requires > 49 longcodes, they must apply for a ‘Number Pool Id’ for the campaign.
A number pool request for a campaign should be made by your account team via your customer management contact(s) at Syniverse as they do not exist for a campaign by default.
It is recommended that you make the request for a number pool to be added to your campaign as soon as you are aware that your campaign requires > 49 longcodes.
All number pool requests will be audited to ensure the requirement for the number pool is considered valid for the customer campaign and use case.
The process for the application and approval of your number pool request can take multiple days to process therefore, customers should start considering a number pool if the number of longcodes for the campaign grows to 20+ numbers.
You should not wait until reaching the maximum allowed number of longcodes for a campaign to reach the limit of 49 before making the requests to avoid any complications and potential disruption of the service.
Note: Longcodes do not need to be provisioned to T-Mobile where a number pool has been assigned to a campaign. Only OSR updates are required to assign the number pool Sub Id parameter to the longcodes for the campaign.