External Trigger API
Learn how to enable sending campaigns via External Trigger API.
Overview
External Trigger campaign is a feature that allows you to trigger the campaign delivery based on API calls or external events. The API endpoint enables you to send messages to designated users via External Trigger API.
Public Beta
This feature is released in Public Beta.
Base URL
The base URL varies depending on the type of External Trigger campaign. Here are the example base URLs from the account in the India region:
Campaign Type | Base URL |
---|---|
Single Campaign ID targeting one or more users | https://in1.api.clevertap.com/1/send/externaltrigger.json |
Multiple Campaigns IDs targeting one or more users | https://in1.api.clevertap.com/2/send/externaltrigger.json |
Region
Refer to Region for more details.
HTTP Method
POST
Headers
Refer to Headers for more details.
Body Parameters
The body is uploaded as a JSON payload. A payload is an object keyed with “d” whose value is an array including the following information: target user, campaign ID, and key-value pair for personalization.
Note:
CleverTap only supports String Data type for mapped property values.
Below is a sample payload for order details of the products bought by the customer:
curl --location 'https://eu1.api.clevertap.com/1/send/externaltrigger.json' \
--header 'X-CleverTap-Account-Id: 566-7Z4-W54Z' \
--header 'X-CleverTap-Passcode: 71d0054732bb4036b9fed9630b80a5c7' \
--header 'Content-Type: application/json' \
--data-raw '{
"to": {
"email": [
"[email protected]"
]
},
"campaign_id": "1695721550",
"ExternalTrigger": {
"Name": "John Doe",
"productDetails": [
{
"productName": "Apple Watch",
"productID": "APPL2209",
"imageURL": "http://example.jpg",
"pricingDetails": [
{
"name": "Transaction Fee (10%)",
"value": "$37.20"
},
{
"name": "Payment Proc. (3%)",
"value": "$11.16"
},
{
"name": "Shipping",
"value": "$8.66"
}
]
},
{
"productName": "iphone 14",
"productID": "APPL1804",
"imageURL": "http://example.jpg",
"pricingDetails": [
{
"name": "Transaction Fee (10%)",
"value": "$107.20"
},
{
"name": "Payment Proc. (3%)",
"value": "$22.16"
},
{
"name": "Shipping",
"value": "$10.66"
}
]
}
]
}
}'
curl --location 'https://eu1.api.clevertap.com/1/send/externaltrigger.json' \
--header 'X-CleverTap-Account-Id: WWW-WWW-WWRZ' \
--header 'X-CleverTap-Passcode: ICW-QKE-YSGL' \
--header 'Content-Type: application/json' \
--header 'X-CleverTap-Token: 000-000' \
--data-raw '{
"to": {
"email": [
"[email protected]",
"[email protected]"
]
},
"campaign_id": "1709550110",
"ExternalTrigger": {
"Name": "John Doe",
"productDetails": [
{
"productName": "Apple Watch",
"productID": "APPL2209",
"imageURL": "http://example.jpg",
"pricingDetails": [
{
"name": "Transaction Fee (10%)",
"value": "$37.20"
},
{
"name": "Payment Proc. (3%)",
"value": "$11.16"
},
{
"name": "Shipping",
"value": "$8.66"
}
]
},
{
"productName": "iphone 14",
"productID": "APPL1804",
"imageURL": "http://example.jpg",
"pricingDetails": [
{
"name": "Transaction Fee (10%)",
"value": "$107.20"
},
{
"name": "Payment Proc. (3%)",
"value": "$22.16"
},
{
"name": "Shipping",
"value": "$10.66"
}
]
}
]
}
}'
curl --location 'https://eu1.api.clevertap.com/2/send/externaltrigger.json' \
--header 'X-CleverTap-Account-Id: WWW-WWW-WWRZ' \
--header 'X-CleverTap-Passcode: ICW-QKE-YSGL' \
--header 'Content-Type: application/json' \
--header 'X-CleverTap-Token: 000-000' \
--data-raw '{
"to": {
"email": [
"[email protected]",
"[email protected]"
],
"identity": [
"Qwefygji",
"9851348"
],
"objectId": [
"Zfagw54thrt0syh9jinoga",
"Mpgorepk6o435mp234o"
]
},
"campaign_id_list": [1709550110, 1709550111],
"ExternalTrigger": {
"Name": "John Doe",
"productDetails": [
{
"productName": "Apple Watch",
"productID": "APPL2209",
"imageURL": "http://example.jpg",
"pricingDetails": [
{
"name": "Transaction Fee (10%)",
"value": "$37.20"
},
{
"name": "Payment Proc. (3%)",
"value": "$11.16"
},
{
"name": "Shipping",
"value": "$8.66"
}
]
},
{
"productName": "iphone 14",
"productID": "APPL1804",
"imageURL": "http://example.jpg",
"pricingDetails": [
{
"name": "Transaction Fee (10%)",
"value": "$107.20"
},
{
"name": "Payment Proc. (3%)",
"value": "$22.16"
},
{
"name": "Shipping",
"value": "$10.66"
}
]
}
]
}
}'
Parameter | Description | Type | Example Value |
---|---|---|---|
to |
| list of strings | [email protected] |
campaign_id | 1709550110 | ||
ExternalTrigger | map | "ExternalTrigger": { "Name": "John Doe", "productDetails": [ { "productName": "Apple Watch", "productID": "APPL2209", "imageURL": "http://example.jpg", "pricingDetails": [ { "name": "Transaction Fee (10%)", "value": "$37.20" }, { "name": "Payment Proc. (3%)", "value": "$11.16" }, { "name": "Shipping", "value": "$8.66" } ] }, { "productName": "iphone 14", "productID": "APPL1804", "imageURL": "http://example.jpg", "pricingDetails": [ { "name": "Transaction Fee (10%)", "value": "$107.20" }, { "name": "Payment Proc. (3%)", "value": "$22.16" }, { "name": "Shipping", "value": "$10.66" } ] } ] } |
Example Request
Here is an example cURL request to the External Trigger API showing the headers needed to authenticate the request from the account in the India region:
- For Single Campaign ID targeting one or more users
curl --location --request POST 'https://in1.api.clevertap.com/1/send/externaltrigger.json' \
--header 'X-CleverTap-Account-Id: <YOUR_ACCOUNT_ID>' \
--header 'X-CleverTap-Passcode: <YOUR_PASSCODE>' \
--header 'Content-Type: application/json' \
--data-raw '{
"to": { "email": [ "<Email ID" ] },
"campaign_id": "<campaign ID>",
"ExternalTrigger": {"<key>" : "<value>"}
}'
require 'httparty'
url = 'https://in1.api.clevertap.com/1/send/externaltrigger.json' # Replace with your actual API endpoint
headers = {
'X-CleverTap-Account-Id' => '<YOUR_ACCOUNT_ID>',
'X-CleverTap-Passcode' => '<YOUR_PASSCODE>',
'Content-Type' => 'application/json'
}
data = {
"to": {
"email": [
"<Email ID>"
]
},
"campaign_id": "<campaign ID>",
"content": {
"<key>": "<value>"
}
}
response = HTTParty.post(url, headers: headers, body: data.to_json)
# Check the response
if response.code == 200
puts "Request successful"
puts "Response: #{response.body}"
else
puts "Request failed with code #{response.code}"
puts "Error: #{response.body}"
end
import requests
import json
url = 'https://in1.api.clevertap.com/1/send/externaltrigger.json' # Replace with your actual API endpoint
headers = {
'X-CleverTap-Account-Id': '<YOUR_ACCOUNT_ID>',
'X-CleverTap-Passcode': '<YOUR_PASSCODE>',
'Content-Type': 'application/json'
}
data = {
"to": {
"email": [
"<Email ID>"
]
},
"campaign_id": "<campaign ID>",
"content": {
"<key>": "<value>"
}
}
response = requests.post(url, headers=headers, data=json.dumps(data))
# Check the response
if response.status_code == 200:
print("Request successful")
print("Response:", response.text)
else:
print(f"Request failed with code {response.status_code}")
print("Error:", response.text)
<?php
$url = 'https://in1.api.clevertap.com/1/send/externaltrigger.json'; // Replace with your actual API endpoint
$headers = array(
'X-CleverTap-Account-Id: <YOUR_ACCOUNT_ID>',
'X-CleverTap-Passcode: <YOUR_PASSCODE>',
'Content-Type: application/json'
);
$data = array(
'to' => array(
'email' => array(
'<Email ID>'
)
),
'campaign_id' => '<campaign ID>',
'content' => array(
'<key>' => '<value>'
)
);
$data_json = json_encode($data);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
if ($response === false) {
echo 'cURL Error: ' . curl_error($ch);
} else {
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($http_code == 200) {
echo 'Request successful' . PHP_EOL;
echo 'Response: ' . $response . PHP_EOL;
} else {
echo 'Request failed with code ' . $http_code . PHP_EOL;
echo 'Error: ' . $response . PHP_EOL;
}
}
curl_close($ch);
?>
const axios = require('axios');
const url = 'https://in1.api.clevertap.com/1/send/externaltrigger.json'; // Replace with your actual API endpoint
const headers = {
'X-CleverTap-Account-Id': '<YOUR_ACCOUNT_ID>',
'X-CleverTap-Passcode': '<YOUR_PASSCODE>',
'Content-Type': 'application/json',
};
const data = {
to: {
email: ['<Email ID>'],
},
campaign_id: '<campaign ID>',
content: {
'<key>': '<value>',
},
};
axios
.post(url, data, { headers })
.then((response) => {
console.log('Request successful');
console.log('Response:', response.data);
})
.catch((error) => {
if (error.response) {
console.log('Request failed with code', error.response.status);
console.log('Error:', error.response.data);
} else {
console.error('Error:', error.message);
}
});
- For Multiple Campaign IDs targeting one or more users
curl --location --request POST 'https://in1.api.clevertap.com/2/send/externaltrigger.json' \
--header 'X-CleverTap-Account-Id: <YOUR_ACCOUNT_ID>' \
--header 'X-CleverTap-Passcode: <YOUR_PASSCODE>' \
--header 'Content-Type: application/json' \
--data-raw '{
"to": { "email": [ "<Email ID" ] },
"campaign_id": [<campaign ID1>,<campaign ID2>],
"ExternalTrigger": {"<key>" : "<value>"}
}'
require "uri"
require "json"
require "net/http"
url = URI("https://in1.api.clevertap.com/2/send/externaltrigger.json")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-CleverTap-Account-Id"] = "<YOUR_ACCOUNT_ID>"
request["X-CleverTap-Passcode"] = "<YOUR_PASSCODE>"
request["Content-Type"] = "application/json"
request.body = "{\n\"to\": { \"email\": [ \"<Email ID\" ] },\n\"campaign_id\": [<campaign ID1>,<campaign ID2>],\n\"ExternalTrigger\": {\"<key>\" : \"<value>\"}\n}"
response = https.request(request)
puts response.read_body
import requests
import json
url = "https://in1.api.clevertap.com/2/send/externaltrigger.json"
payload = "{\n\"to\": { \"email\": [ \"<Email ID\" ] },\n\"campaign_id\": [<campaign ID1>,<campaign ID2>],\n\"ExternalTrigger\": {\"<key>\" : \"<value>\"}\n}"
headers = {
'X-CleverTap-Account-Id': '<YOUR_ACCOUNT_ID>',
'X-CleverTap-Passcode': '<YOUR_PASSCODE>',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://in1.api.clevertap.com/2/send/externaltrigger.json');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'X-CleverTap-Account-Id' => '<YOUR_ACCOUNT_ID>',
'X-CleverTap-Passcode' => '<YOUR_PASSCODE>',
'Content-Type' => 'application/json'
));
$request->setBody('{\n"to": { "email": [ "<Email ID" ] },\n"campaign_id": [<campaign ID1>,<campaign ID2>],\n"ExternalTrigger": {"<key>" : "<value>"}\n}');
try {
$response = $request->send();
if ($response->getStatus() == 200) {
echo $response->getBody();
}
else {
echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
$response->getReasonPhrase();
}
}
catch(HTTP_Request2_Exception $e) {
echo 'Error: ' . $e->getMessage();
}
Node js
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://in1.api.clevertap.com/2/send/externaltrigger.json',
'headers': {
'X-CleverTap-Account-Id': '<YOUR_ACCOUNT_ID>',
'X-CleverTap-Passcode': '<YOUR_PASSCODE>',
'Content-Type': 'application/json'
},
body: '{\n"to": { "email": [ "<Email ID" ] },\n"campaign_id": [<campaign ID1>,<campaign ID2>],\n"ExternalTrigger": {"<key>" : "<value>"}\n}'
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
Sample Response
The response will be a JSON object containing either the success or fail status. This varies depending on the type of External Trigger campaign, as shown below:
{
"message": "Added to queue for processing",
"status": "success"
}
{
"message": "Added to queue for processing",
"status": "partial",
"error": "The following campaignIDs have not been added to the processing queue: [65] as they have either been stopped, or are not ready, or require approval or lack type external trigger. ",
"code": 200
}
//The error indicates that the all the campaigns except the one with ID 65 have been added to the queue. The campaign with ID 65 is dropped.
Error Codes
If there is an error in the campaign delivery, the following error code indicates the nature of the error encountered:
Error Code | Details | Sample JSON Payload |
---|---|---|
400 | Occurs in the following scenarios: to parameter missing in the payload. It is a mandatory parameter.to parameter includes multiple or no recipients. Only one recipient identity is accepted for the parameter. campaign_id parameter is empty. campaign_id does not exist. campaign_id does not have a valid status. campaign_id is not ready. | { "status": "fail", "error": "Invalid Credentials", "code": 400 } |
Updated about 2 months ago