Easily automate your workflows by integrating Blackbell Broadcasts to third party softwares.
There are three public api endpoints to manage broadcasts, aka automated campaigns:
POST /api/i/broadcasts - sends an existing broadcast or creates and sends a new one
GET /api/i/automated_campaign_receipts - get all broadcasts receipts
GET /api/i/automated_campaign_receipts/:id - get a broadcast receipt by id
Please note that all public APIs require API-KEY request header.
Setup
Before we go to examples let’s satisfy few preconditions:
create a draft broadcast and remember it’s id
ensure you know an id of at least 1 active (non-archived) visitor, who will receive the broadcast
How can I use POST /api/i/broadcasts ?
Step 1: Get your API key
Contact Blackbell support to get your API key
Step 2: Compose broadcast parameters
You can use this api endpoint to send an existing broadcast or create a new one.
To send an existing broadcast the api parameters should be the following:
visitor_ids
automated_campaign_id
label_ids
communication_channel
translation_texts
To create new broadcast and send the api parameters should be the following:
visitor_ids
translation_texts
label_ids
communication_channel
forced_locale
communication_channel can be
push_or_email
push_and_email
push_notification
To reflect the options
Step 3: Send request
Let’s say we have a draft broadcast (id: 549) with the following parameters (this is an example of a push notification for all active visitors):
{
"archived":false,
"button_links":[
],
"campaign_type":"broadcast",
"cloudinary_attachment_links":[
],
"communication_channel":"push_notification",
"coupon_id":null,
"enabled":true,
"id":549,
"is_editable":true,
"schedule_configuration":{
},
"segmentation_configuration":{
"ransack_query":{
}
},
"template_configuration":{
},
"translation_texts":{
"body":"<div>testing public api</div>",
"title":"test broadcast"
},
"user_jobs":[
],
"welcome_template":false
}
And we want to send it to visitor with id 11120 as an email
Then send the request skeleton is:
curl 'https://www.blackbellapp.com/api/i/broadcasts' -X POST -H 'api-key: <YOURAPIKEY>' -H 'content-type: application/json; charset=UTF-8' --data-binary $'{\n "params": {<BROADCASTPARAMS>}\n}'
Note that you have to add content-type: application/json; charset=UTF-8 header.
Example with some values of a demo app:
curl 'https://www.bbserver2.com/api/i/broadcasts' -X POST -H 'api-key: 1f125461b742cb1d4fea7d4adb1b9ef1' -H 'content-type: application/json; charset=UTF-8' --data-binary $'{\n "params": {\n "visitor_ids": [11120],\n "automated_campaign_id": 549,\n "communication_channel": "email"\n }\n}'
In case you’re using postman:
create a new broadcast & send
curl 'https://www.bbserver2.com/api/i/broadcasts' -X POST -H 'api-key: 1f125461b742cb1d4fea7d4adb1b9ef1' -H 'content-type: application/json; charset=UTF-8' --data-binary $'{"params": { "visitor_ids": [11120], "communication_channel": "email" }, "translation_texts": { "title": "new test broadcast title", "body": "new test broadcast BODY" }, "forced_locale": "en" }'
In case you’re using postman:
Step 4: check the results
email received
broadcast attributes updated
Step 4: Done!
👌
How can I use GET /api/i/automated_campaign_receipts ?
Once a broadcast is sent to visitors, Blackbell starts monitoring broadcast’s events, aka receipts.
There are 4 possible “success” events for now:
sent - a broadcast is sent successfully
opened - a visitor opened the broadcast. Note: some users are probably using an email client which blocks the open tracker technology.
clicked - a visitor clicked a broadcast message link
buy - not implemented yet…
And 1 “error“ event:
failed - visitors did not receive your broadcast
To get all events for all broadcasts you have tried to send follow these steps:
Step 1: Get your API key
Contact Blackbell support to get your API key
Step 2: Send request
curl 'https://www.blackbellapp.com/api/i/automated_campaign_receipts' -H 'api-key: <YOURAPIKEY>'
example with some values of a demo app:
curl 'https://www.bbserver2.com/api/i/automated_campaign_receipts' -H 'api-key: 1f125461b742cb1d4fea7d4adb1b9ef1'
In case you’re using postman:
Step 3: Make sure you get good response
your response should be like:
[
{
"id":2670,
"visitor_id":11120,
"automated_campaign_id":519,
"event_type":"failed",
"event_timestamp":"2020-04-21T09:11:19.707Z"
},
{
"id":2673,
"visitor_id":11120,
"automated_campaign_id":521,
"event_type":"opened",
"event_timestamp":"2020-04-21T10:55:46.000Z"
},
{
"id":2672,
"visitor_id":11120,
"automated_campaign_id":521,
"event_type":"sent",
"event_timestamp":"2020-04-21T09:15:18.118Z"
},
{
"id":2721,
"visitor_id":11120,
"automated_campaign_id":549,
"event_type":"opened",
"event_timestamp":"2020-05-13T06:49:17.000Z"
},
{
"id":2717,
"visitor_id":11120,
"automated_campaign_id":549,
"event_type":"sent",
"event_timestamp":"2020-05-13T06:49:19.937Z"
}
]";"
Note that the response contains 1 failed event
Step 4: Done!
👌
How can I use GET /api/i/automated_campaign_receipts/:id ?
Step 1: Get your API key
Contact Blackbell support to get your API key
Step 2: Send request
You should know receipt id.
curl 'https://www.blackbellapp.com/api/i/automated_campaign_receipts/:id' -H 'api-key: <YOURAPIKEY>'
example with some values of a demo app:
curl 'https://www.bbserver2.com/api/i/automated_campaign_receipts/2670' -H 'api-key: 1f125461b742cb1d4fea7d4adb1b9ef1'
In case you’re using postman:
Step 3: Make sure you get good response
your response should be like:
{
"id":2670,
"visitor_id":11120,
"automated_campaign_id":519,
"event_type":"failed",
"event_timestamp":"2020-04-21T09:11:19.707Z"
}
Step 4: Done!
👌
Here is an example to get metrics related to broadcast 549:
curl 'https://www.bbserver2.com/api/i/automated_campaign_receipts?q%5Bautomated_campaign_id_eq%5D=549' -H 'api-key: 1f125461b742cb1d4fea7d4adb1b9ef1'
Here is an example to get metrics related to broadcast 549 only related to visitor_id":11120"
curl 'https://www.bbserver2.com/api/i/automated_campaign_receipts?q%5Bautomated_campaign_id_eq%5D=549&q%5Bvisitor_id_eq%5D=11120' -H 'api-key: 1f125461b742cb1d4fea7d4adb1b9ef1'