Business Messenger Campaign API
1. Overview
The Business Messenger (BM) Campaign API is a standard REST HTTP API with JSON payload. It can be used to programmatically manage BM campaign data. BM API authorization is implemented as the industry-standard OAuth2 protocol.
The subject domain of an endpoint URL is:
https://api{separator}{platform_domain}/news/v1
Note: Replace {platform_domain} with your platform domain. {separator} can be either . or -, depending on your platform configuration.
The subject domain of an endpoint URL depends on your domain used to access our services.
Please check with your CRM Account Manager, what is the subject domain you should use.
2. Getting credentials
In order to be able to use the API, you need to provide a name for your custom app, IP address from which you will be authorizing the app and the BM account name whose contacts data your app will be managing. It is expected that your app will be a server-side implementation and as such will use the OAuth2 client credentials grant type.
In return, the support team will create an API account for your app and you will be given: client_id and client_secret credentials.
3. Authorization
In order to be able to call any API endpoint, you need to obtain a valid access token. Each access token has an expiration time so you need to obtain a new one if the existing one is expired. Here's a cURL example of how an access token can be obtained (please replace CLIENT_ID and CLIENT_SECRET with the ones you were given in the previous step):
curl https://accounts{separator}{platform_domain}/oauth2/access-token -d 'grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET'
Note: Replace {platform_domain} with your platform domain. {separator} can be either . or -, depending on your platform configuration.
If the parameters are valid, and the call is made from the authorized IP address, the server will respond with JSON containing the access token:
{"access_token":"ACCESS_TOKEN","token_type":"Bearer","expires_in":604800}
For more details, please check the OAuth2 Authentication Guidelines page.
4. Cloning existing campaign
An existing campaign, eg. draft one, can be cloned and activated, the call can be as simple as:
curl -X 'POST' \
'https://api{separator}{platform_domain}/news/v1/services/SERVICE_UUID/campaigns' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
"clone_uuid": "CLONE_UUID",
"template_vars": {
"temp": "-22C",
"wind": "100km/h"
},
"name": "Bad weather conditions"
}'
CLONE_UUID is an UUID of an existing campaign we want to clone from.
Replace SERVICE_UUID, ACCESS_TOKEN, CLONE_UUID with proper values. template_vars is a simple dictionary of key/value pairs. It is expected that the campaign you are cloning from, has variables in the text content {temp}, {wind}
Note that name is optional. Additional fields depend on your wish what exact fields you want to overwrite compared to the existing campaign you are cloning from.