Template campaigns are created using the UI on the platform but triggered later via the external API.
You can find API Triggered Campaigns on the Create Campaign page:
You can build these campaigns like any regular campaign:
Any available outbound channel may be triggered by an API execution and multiple channels can be used in your template if required:
These message are typically transactional with a mixture of fixed content in the template and variables sent via API. Use the double curly braces syntax to add variables - {{variable_name}}:
If using richer messaging formats with more copy space such as email then more variable content can be added and it can be more complex you can see an example here:
Once the template is configured with channel, content, variables etc. put the campaign live with the Review & Launch button like any other campaign. Then you will go to live campaigns where you will see your campaign listed:
The campaign ID is appended to the campaign and will be used when executing the campaign via API.
Triggering a Campaign Template via API
The execute API method is used to trigger template campaigns details below:
Execute
Used to trigger a template campaign, targeting it at specific users and adding variables if needed.
URL
/api/external/execute/campaign
Parameters
| Parameter | Description |
|---|---|
| apptoken | Your App token |
| id | Campaign id can be found appended to title in live campaigns section |
| target |
The list of targeted user ids: |
| target_with_params | An alternative to 'target' parameter if you want to pass the values of any personalization params you have in your campaign template message:{"user1": {"fname":"Alex","balance":"100 EUR"}, "user2": {"fname":"John", "balance": "80 EUR"}} |
| params |
Optional way of setting the personalisation params if you are targeting a single user or all messages are to be modified with the same params, use like: |
| target_by | An optional parameter to specify the type of user identifier used in 'target' or 'target_with_params' fields. Available values are: - id (xtremepush device id - default value) - user_id (set by client typically unique user/customer id) - token (push token) - external_id (id set by client, typically CRM user id) |
| time |
An optional parameter to specify when to execute the campaign. It will be executed immediately if this param is omitted. You can use both date string and unix timestamp as a value. |
| async |
An optional parameter. If set to 0 your request will be processed completely before API response is returned. In this way you enable an extra level of error reporting being able to receive errors like: "Recipient not found", "Message is suppressed due to insufficient personalization params". The limitation of non-async mode is that you're only allowed to target a single profile/device. In case you need an extra level of reporting for batch sends you should use a separate query to fetch batch send status. |
| Other campaign params | Set/Over-write any of the other campaign params as found here |
Server Response
| success |
True - the request was successfully processed. Note, it doesn't mean that the message was successfully delivered to gateway, it means that all validations were passed (such as - campaign exists, target set, params are passed in correct format). False - the request was not processed and no messages were sent. Errors list should contain the reason of failure. Also note, because your request could be used to send multiple messages, it is possible that some of the messages were sent and some were not sent. It could be due to channel misconfiguration or having insufficient params to send the message. In this case 'success' will be 'true', but the errors list will contain information about failed messages. |
| errors | A list of errors occurred during campaign execution. When processing the response you should check if it contains any errors. If so - it has to be reviewed in order to eliminate future errors. |
Example
Executing a campaign, targeting a single user by external ID and setting a number a variables in the campaign text.
curl -X POST -d '{"apptoken": "YOURAPPTOKEN", "id": "CAMPAIGNID", "target_with_params": {"crm-user-1": {"fname": "Alex", "balance": "100 EUR"}, "crm-user-2": {"fname": "John", "balance": "80 EUR"}}, "target_by": "external_id"}' https://external-api.xtremepush.com/api/external/execute/campaign
Executing a campaign on a specific time:
curl -X POST -d '{"apptoken": "YOURAPPTOKEN", "id": "CAMPAIGNID", "target": ["user1", "user2"], "target_by": "external_id", "time": "2017-01-01 12:00 UTC"}' https://external-api.xtremepush.com/api/external/execute/campaign
Executing a campaign that enables the webpush 'require interaction' option, and has a retry period of 2 weeks:
curl -X POST -d '{
"apptoken": "YOURAPPTOKEN",
"id": "CAMPAIGNID",
"target_by": "user_id",
"target": ["12345"],
"messages": {
"3": {
"push_require_interaction": false
}
},
"retry_for": 2,
"retry_for_period": "weeks"
}' https://external-api.xtremepush.com/api/external/execute/campaign
You can use any of the regular campaign params to add content, segment users etc., for example you could add a payload like a deeplink to be used when the notification is opened:
curl -X POST -d '{"apptoken": "YOURAPPTOKEN", "id": "CAMPAIGNID", "target": [123456], "payload_add": [{"key": "URL_KEY", "value": "https://m.example.com/deeplink/123456"}]}' https://external-api.xtremepush.com/api/external/execute/campaign
Example response from a successfully executed campaign:
{
"success":true,
"code":200,
}
Example response from a failed execution:
{
"success":false,
"code":400,
"errors": {
"campaign": [
"Campaign is not active"
]
}
}
Example response from an individual message failure:
{
"success":true,
"code":200,
"errors": {
"execute": [
"Web Push: one or multiple messages were suppressed due to insufficient personalization params"
]
}
}
Comments
0 comments
Article is closed for comments.