Send a notification
Before we begin
This tutorial assumes you have followed the quick start guide and are familiar with XPKit resources and how to call API endpoints with an Authorization header. We continue to use the EMEA region in the examples below.
Workflow
XPKit currently supports email and SMS notifications. The workflow to send a notification is as follows:
- Create a notification campaign resource where you specify the email / SMS provider you wish to use and all the configuration options such as subject lines, templates and sender information per language.
- Send a notification based on some trigger using the configuration defined
Configuration
XPKit Portal
Usually you would define your campaign in XPKit Portal by going to the Notifications > Configurations section. This is the recommended approach as there are a lot of available options and using Portal allows non-technical people to set up your campaigns. For this tutorial we will configure everything via the API endpoints.
In the following example we will create an email campaign using Mandrill as the sender. If you plan to follow along you will need a Mandrill API key and have verified your sending domain with Mandrill.
Example campaign resource:
{
"campaign_name": "Welcome to the conference (Mandrill)",
"experience_id": "game-developers-conference-2024",
"object_id": "reception-tablet",
"gateway": "mandrill",
"notification_type": "email",
"gateway_config": {
"api_key": "xxx",
},
"content": {
"_default": "en_GB",
"en_GB": {
"from_email": "registration@gdc-conference.com",
"from_name": "GDC 2024 conference registration",
"subject_line": "Welcome to GDC {{first_name}}",
"template_html": "https://gdc-conference.s3.amazonaws.com/registration_en.html",
"template_text": "https://gdc-conference.s3.amazonaws.com/registration_en.txt"
},
"fr_FR": {
"from_email": "registration@gdc-conference.comm",
"from_name": "GDC 2024 inscription à la conférence",
"subject_line": "Bienvenue à GDC {{first_name}}",
"template_html": "https://gdc-conference.s3.amazonaws.com/registration_fr.html",
"template_text": "https://gdc-conference.s3.amazonaws.com/registration_fr.txt"
}
},
"webhook_url": "https://events.gdc-conference.com/callback"
}
This campaign provides templates for English and French recipients. The campaign also provides a webhook_url field. Once a notification request is made using this campaign the result will be posted to this URL. You should read the API specification to learn more about callbacks and all the available options including the multiple ways you can provide templates.
We will now call the campaign create endpoint to save this resource:
import requests
endpoint = 'https://notifications.emea.xpkit.net/api/campaign/'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'}
resource = {
'campaign_name': 'Welcome to the conference (Mandrill)',
'experience_id': 'game-developers-conference-2024',
'object_id': 'reception-tablet',
'gateway': 'mandrill',
'notification_type': 'email',
'gateway_config': {
'api_key': 'xxx',
},
'content': {
'_default': 'en_GB',
'en_GB': {
'from_email': 'registration@gdc-conference.com',
'from_name': 'GDC 2024 conference registration',
'subject_line': 'Welcome to GDC {{first_name}}',
'template_html': 'https://gdc-conference.s3.amazonaws.com/registration_en.html',
'template_text': 'https://gdc-conference.s3.amazonaws.com/registration_en.txt'
},
'fr_FR': {
'from_email': 'registration@gdc-conference.comm',
'from_name': 'GDC 2024 inscription à la conférence',
'subject_line': 'Bienvenue à GDC {{first_name}}',
'template_html': 'https://gdc-conference.s3.amazonaws.com/registration_fr.html',
'template_text': 'https://gdc-conference.s3.amazonaws.com/registration_fr.txt'
}
},
'webhook_url': 'https://events.gdc-conference.com/callback'}
req = requests.post(headers=headers, url=endpoint, json=resource)
result = req.json()
async function postData(url, data) {
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
},
body: JSON.stringify(data),
});
return response.json();
}
const jsonData = {
'campaign_name': 'Welcome to the conference (Mandrill)',
'experience_id': 'game-developers-conference-2024',
'object_id': 'reception-tablet',
'gateway': 'mandrill',
'notification_type': 'email',
'gateway_config': {
'api_key': 'xxx',
},
'content': {
'_default': 'en_GB',
'en_GB': {
'from_email': 'registration@gdc-conference.com',
'from_name': 'GDC 2024 conference registration',
'subject_line': 'Welcome to GDC {{first_name}}',
'template_html': 'https://gdc-conference.s3.amazonaws.com/registration_en.html',
'template_text': 'https://gdc-conference.s3.amazonaws.com/registration_en.txt'
},
'fr_FR': {
'from_email': 'registration@gdc-conference.comm',
'from_name': 'GDC 2024 inscription à la conférence',
'subject_line': 'Bienvenue à GDC {{first_name}}',
'template_html': 'https://gdc-conference.s3.amazonaws.com/registration_fr.html',
'template_text': 'https://gdc-conference.s3.amazonaws.com/registration_fr.txt'
}
},
'webhook_url': 'https://events.gdc-conference.com/callback'
};
postData('https://notifications.emea.xpkit.net/api/campaign/', jsonData).then((data) => {
const result = data;
});
Encoding
If using JavaScript ensure you are sending UTF-8 encoded payloads. This can be achieved in a browser by setting the charset like so: <meta charset="UTF-8">.
All being well we will receive back the saved resource:
{
"resource": {
"campaign_id": "welcome-to-the-conference-mandrill",
"campaign_name": "Welcome to the conference (Mandrill)",
"content": {
"_default": "en_gb",
"en_gb": {
"from_email": "registration@gdc-conference.com",
"from_name": "GDC 2024 conference registration",
"subject_line": "Welcome to GDC {{first_name}}",
"template_html": "https://gdc-conference.s3.amazonaws.com/registration_en.html",
"template_text": "https://gdc-conference.s3.amazonaws.com/registration_en.txt"
},
"fr_fr": {
"from_email": "registration@gdc-conference.comm",
"from_name": "GDC 2024 inscription à la conférence",
"subject_line": "Bienvenue à GDC {{first_name}}",
"template_html": "https://gdc-conference.s3.amazonaws.com/registration_fr.html",
"template_text": "https://gdc-conference.s3.amazonaws.com/registration_fr.txt"
}
},
"created": "2023-07-07T03:52:46Z",
"experience_id": "game-developers-conference-2024",
"gateway": "mandrill",
"gateway_config": {
"api_key": "xxx"
},
"last_modified": "2023-07-07T03:52:46Z",
"notification_type": "email",
"object_id": "reception-tablet",
"webhook_url": "https://events.gdc-conference.com/callback"
},
"resource_id": "36308466-730e-421e-90ea-55c71c39fc50",
"resource_url": "/api/campaign/36308466-730e-421e-90ea-55c71c39fc50/"
}
Take a note of the auto-generated campaign_id as we'll use this later.
Triggering a send
There are two ways to send a notification:
- Make an API request to the trigger endpoint to send now or at a scheduled time in future
- Create a rule to send based on creation of a particular type of activity
Let's go through these two approaches individually...
API request
We can call the trigger endpoint with a notification resource:
{
"campaign_id": "welcome-to-the-conference-mandrill",
"recipient_email": "firstname.lastname@example.com",
"language": "en_GB",
"content": {
"template": {
"first_name": "Example",
"last_name": "Person"
}
},
"send_at": "2024-03-18T11:00:00+11"
}
This specifies the recipient information, personalisation context data for the templates and the language to use. An optional send_at field can be provided if you need to send the email in the future. If this is required note that you can cancel scheduled emails before they are sent in XPKit Portal under the Notifications > Scheduled section.
An example request:
import requests
endpoint = 'https://notifications.emea.xpkit.net/api/notification/'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'}
resource = {
'campaign_id': 'welcome-to-the-conference-mandrill',
'recipient_email': 'firstname.lastname@example.com',
'language': 'en_GB',
'content': {
'template': {
'first_name': 'Example',
'last_name': 'Person'
}
},
'send_at': '2024-03-18T11:00:00+11'}
req = requests.post(headers=headers, url=endpoint, json=resource)
result = req.json()
async function postData(url, data) {
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
},
body: JSON.stringify(data),
});
return response.json();
}
const jsonData = {
'campaign_id': 'welcome-to-the-conference-mandrill',
'recipient_email': 'firstname.lastname@example.com',
'language': 'en_GB',
'content': {
'template': {
'first_name': 'Example',
'last_name': 'Person'
}
},
'send_at': '2024-03-18T11:00:00+11'
};
postData('https://notifications.emea.xpkit.net/api/notification/', jsonData).then((data) => {
const result = data;
});
You'll receive an acknowledgement response and the notification will be sent when requested.
Rule based
In XPKit Portal under the Notifications > Rules section it is possible to create rules to send notifications when particular activities have been created. An example rule could be:
When an activity is created with the field: activity_action
Equal to the value of: send-registration-email
Send the notification: welcome-to-the-conference-mandrill
Everytime an activity is created that has a field called activity_action with a value of send-registration-email, the campaign we created above will be sent to the activity owner (profile resource), if they have an email. If they have more than one email, the first one in the profile's email array will be used.
Profile data
If the profile has a language field this will be provided to the trigger endpoint, and the corresponding template will be used. If no language is available the default for the campaign will be used.
If the following fields are available in the profile they will be provided to the trigger endpoint so they can be used in personalisation tags in templates: email, first_name, last_name, rfid, qr_code, title. The profile's resource ID will also be made available as profile_id.
Additional context data
For any activity that triggers a rule, if you define a notification_data object under the payload in the activity, any fields provided here will also be made available in the template. Example:
{
"experience_id": "game-developers-conference-2024",
"owner_id": "c48ea5a2-1f6e-4772-a23f-c4bc09732b47",
"activity_type": "registration",
"activity_action": "send-registration-email",
"payload": {
"object_id": "registration-website",
"number_of_tickets": 5,
"notification_data": {
"home_country": "Japan",
"company": "Kojima Productions"
}
}
}
In this example you would be able to access {{home_country}} and {{company}} in the template, as well as the profile fields documented above.