Campaign Automation Details
DIRECT CAMPAIGN API ACTIONS: as a means to help Syniverse customers control their downstream partner campaigns (and all CSPs behind them) this API endpoints allow SUSPENSION (Including Removal from SDG) and RESUME options.
Users can find more details about this method in the Campaign Automation Details section as well as the specific API for:
- Suspend Campaign Method (Remove from T-Mobile SDG)
- Resume Campaign Method
Note: this atuomation will produce a set of status changes as well as designated ESS status update evetns like this ESS example of "campaign_status": "SUSPENDED".
AUTOMATIC (INDIRECT) CAMPAIGN API ACTIONS: As described in the introduction, with the exception of SUSPEND/RESUME, most of the campaign related activities are indirect automated actions triggered by TCR Events reaching our system due to customer's actinons in that 3rd party platform.
This means Syniverse is doing provisioning in T-Mobile because of customer actions in TCR. Syniverse automation backend will turn to T-Mobile and create an equivalent of a TCR campaign in the T-Mobile SDG Platform and send ESS Notifications to keep our customer provisioning systems informed.
Indirectly TCR invoked DCA CAMPAIGN actions: occur after the TCR Campaign is Approved and the connectivity partner is selected. At that point TCR will perform two things in parallel:
1. Create an equivalent of a TCR Brand called Content Provider in the T-Mobile SDG Platform
2. Send an event to Syniverse (DCA_Update_Event) that will trigger the Campaign automation flow
TCR also provides status notifications for existing campaigns. These TCR notification events are the triggers for the Syniverse 10DLC Provisioning Actions for Campaigns. Those actions include the following MNO (T-Mobile) Provisioning activities: Deployment of the Campaign on T-Mobile, Removal of the campaign from T-Mobile due to expiration.
Indirectly TCR invoked DCA CAMPAIGN actions are:
· CAMPAIGN DEPLOYMENT
· CAMPAIGN DELETION
Success or failure to execute those flows are then directly communicated to the customer via ESS Provisioning Notification events. Customers must subscribe their provisioning systems to Syniverse ESS Notifications via the Syniverse Developer Community UI. It is only after a Campaign is DEPLOYED that a customer can move to the next phase of the provisioning process: Application Address Management API.
Only campaigns in DEPLOY status will accept 10 DLC LONGCODE/NUMBER POOL association via Directly Invoked Customer Action Requests to Syniverse 10DLC A2P Provisioning REST API Endpoints.
Direct CAMPAIGN actions (SUSPEND/RESUME) actions: Due to carrier penalties around Campaigns that are not in use, including campaigns with no long codes or number pool associations, Syniverse introduced one new status option: SUSPENDED that can be managed via our 10DLC provisioning API.
About Syniverse Campaign Status
In order to better understand the mechanics of the backend process, v2 release consider a campaign can be:
PENDING = an interim status that implies TCR notified Syniverse there is a new campaign for a specific Actor (Customer) that must be deployed via our automation tool. Happens when TCR sends a DCA_UPDATE_EVENT signal.
DEPLOYED = means a campaign is successfully provisioned in MNOs (Particularly T-Mobile SDG this is then the campaign activation fee applies) and is the only valid status to request number association actions (add/remove).
DEPLOYED_FAILED = the system founds non-retriable errors on MNO API or exhausts the retry mechanism while trying either to remove the campaign or the application addresses in it.
MARK_REMOVED = TCR request campaign removal received and indicates the beginning of the removal process, where Syniverse will remove all the associated application addresses in that campaign and set the campaign as removed.
REMOVE_FAILED = the system receives non-retriable errors from the MNO API or exhausts the retry mechanism while trying to remove the campaign or the application addresses (Long Codes and Number Pools) in it.
REMOVED = Means the campaign is no longer active, has been set to Remove in T-Mobile, typically due to a TCR DELETE/EXPIRE request.
-- Campaign Status Customer Managed Options (Direct API SUSPEND/RESUME methods)
Due to carrier penalties around Campaigns that are not in use, including campaigns with no long codes or number pool associations, Syniverse introduced one new status option that can be managed via our 10DLC provisioning API called Suspend Campaign Method triggering the following status changes:
MARK_SUSPENDED=Customer initiated the suspension of a campaign and the activity is in progress. Suspension of a campaign will remove all long code and number pool associations.
SUSPENDED=Capaign is in suspended status, that means the Syniverse system knows about the campaign but it has been removed from MNO platforms. Campaigns in this status will not accept changes. Suspension of a campaign will automatically remove all long code and number pool associations.
SUSPEND_FAILED the system receives non-retriable errors from the MNO API or exhausts the retry mechanism while trying to Suspend the campaign and REMOVE the application addresses (Long Codes and Number Pools) in it.
- TIP: Please contact customer support and open only 1 ticket for all the campaigns you have in SUSPEND_FAILED status.
If the customer wants to use the campaign in the future it shall use the Resume Campaign Method :
-- At this step the platform will set the status to PENDING and attempt to move this campaign back to DEPLOYED state. From here customers can add long codes / or number pool as required to run traffic.
If a campaign expires in TCR then the customer shall not expect this request to be successful.
Detailed Campaign Provisioning Flows
The following flow follows January 2023 changes to TCR DCA-2 election changes.
Customers (Actors) with a CSP/CnP Role will work as follows:
ESS Notifications Structure and Samples
The full structure of the ESS Notifications is present in the following section, customers can get this event by setting up subscriptions in the SDC admin portal to
"Topic: "TenDlc-Provisioning"
Event Type: "TenDlc_Campaign"
ESS Notification Body: Interim notification
|
{ |
ESS Notification Body: final notification DEPLOYED
|
{ |
ESS Events for DIRECT CAMPAIGN ACTIONS (SUSPEND)
The events follow the same structure as any other campaign status change notificaiton, since the changes were recentrly introduced we wanted to share specific example for quick reference:
{
"topic": "TenDlc-Provisioning-V2",
"attempt": 1,
"event": {
"fld-val-list": {
"application_id": 9160,
"campaign_status": "SUSPENDED",
"campaign_description": "Your request to suspend campaign CZ21234 has been processed. All longcodes have been deleted from the campaign.",
"reason_code": "",
"reason_description": "",
"tcr_campaignId": "CZ21234",
"number_pool_type": "",
"number_pool_id": "",
"company-id": 111307
},
"evt-tp": "TenDlc_Campaign_V2",
"timestamp": "2022-08-01T05:26:04.844Z"
},
"event-id": "WzOvhZtET2qeRJOLEagjDA"
}
ESS Notification Body: final notification in case of an error
|
{ |
GET single Campaign details
Syniverse has implemented a self-service endpoint for troubleshooting purposes (please do not abuse) remember that for real time purposes customers must use ESS Event Subscriptions.
GET https://api.syniverse.com/engage/tendlc-services/v2/campaigns/{CampaignId} response
|
200 OK RESPONSE |
| { "code": 200, "message": "Request received", "status": "Ok", "timestamp": "2022-07-27T12:05:30.631Z", "data": { "campaignId": "CQWFXXX", "status": "DEPLOYED", "cspId": "S73Gxxx", "brandId": "BU6VXXX", "customerActorId": "S73GXXX", "policy": "policy_10dlc", "useCase": "two-factor-authentication", "subUseCase": null, "msgServiceType": "two-factor-authentication", "firstDeployedTime": "2022-06-30T17:40:55.807", "insertedTime": "2022-07-20T18:33:55.807", "updatedTime": "2022-07-20T18:34:26.865", "applicationAddresses": [ { "applicationAddress": "12345678999", "status": "ADDED", "updatedTime": "2022-09-12T15:48:12.641" } ] } } |