How to switch from the Transactional API to the Profile API?

As part of the migration from the Batch MEP to the CEP, you might want to switch from the Transactional API (or its variant, the Partner API) to a more user-friendly option: sending custom events via the Profile API and scheduling your Trigger Push Automations directly from the Automation Builder.

This option is not applicable yet if you are targeting Installation IDs with the Transactional API. It will be available soon.

Step-by-step

1

Audit your current usage of the Transactional API

Establish the list of your running Transactional API calls. You can refer to the Analytics > Notifications > Transactional tab on the Batch dashboard to get the list of messages sent via the Transactional API over a specific time period.

2

[Back-end] Prepare your calls to the Profile API

• Associate each Transactional message with a new Custom Event:

  • Event name: For consistency, you can use the "Group ID" of your current Transactional API call.

  • Additional data: If your transactional message contains personalization, associate the personalization values as attributes of these events.

• Get ready to send these events via the Profile API each time you were calling the Transactional API.

3

[Dashboard] Prepare your Trigger Automations

• Create one trigger automation for each transactional message using the Batch Automation Builder. The trigger event must be the one defined in step 2.

• Activate these automations.

4

[Back-end] Switch from the Transactional API to the Profile API

Once the automations are running on the dashboard, stop calling the Transactional API and start sending the custom events via the Profile API so that the automations created in step 3 are triggered.

Example: Order shipped 📦

Let's apply the above steps to an example:

1

Audit your current usage of the Transactional API

You currently notify clients when their order has been shipped. To do so, you call the Transactional API with a payload that looks like this:

{
	"group_id": "order_shipped",
	"recipients": {
		"custom_ids": ["129c7819-9c88-496e-9a5f-62db34a3ce61"]
	},
	"message": {
		"title": "📦 Your order BC257637 has been shipped!",
		"body": "Click here to keep track of your parcel"
	},
	"deeplink" : "https://wwww.mybrand.com/BC257637"
}

2

[Back-end] Prepare your calls to the Profile API

• You prepare your calls to the Profile API by associating your transactional message with a new Custom Event:

  • Event name: You choose to call it order_shipped, just as the group ID of your call to the Transactional API.

  • Additional data: For personalization purposes, this use case requires the order ID and the parcel tracking link. So you add 2 attributes to the new event: id (String) and parcel_tracking_link (URL).

• Here is how the payload you will include in your Profile API call will look like:

[
    {
        "identifiers": {
            "custom_id": "129c7819-9c88-496e-9a5f-62db34a3ce61"
        },
        "events": [
            {
                "name": "order_shipped",
                "attributes": {
                    "id": "BC257637",
                    "url(parcel_tracking_link)": "https://wwww.mybrand.com/BC257637"
                }
            }
        ]
    }
]

3

[Dashboard] Prepare your Trigger Automations

• You create a dedicated trigger automation for this use case:

You add the personalization values from the trigger event order_shipped in the title (id) and the deeplink (parcel_tracking_link) fields of your message, using the {...} buttons:

• Then you activate this automation ("Run" button).

4

[Back-end] Switch from the Transactional API to the Profile API

Now that the automation is running on the dashboard, you stop calling the Transactional API and start sending the custom event order_shipped via the Profile API so that the automation created in step 3 is triggered.