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: <YOUR_ACCOUNT_ID>' \
--header 'X-CleverTap-Passcode: <YOUR_PASSCODE>' \
--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: <YOUR_ACCOUNT_ID>' \
--header 'X-CleverTap-Passcode: <YOUR_PASSCODE>' \
--header 'Content-Type: application/json' \
--header 'X-CleverTap-Token: <YOUR_TOKEN>' \
--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: <YOUR_ACCOUNT_ID>' \
--header 'X-CleverTap-Passcode: <YOUR_PASSCODE>' \
--header 'Content-Type: application/json' \
--header 'X-CleverTap-Token: <YOUR_TOKEN>' \
--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	Mandatory parameter. Identity of the user to whom the campaign is to be sent. It can have any one of the following value: email identity objectID Multiple values are not allowed. For Multiple Campaign IDs targeting multiple users, it can have a maximum of 1000 identity values.	list of strings	[email protected]
campaign_id	Mandatory parameter Unique ID of the campaign. For Multiple Campaign IDs targeting one or more users, it can have a maximum of five campaign IDs.	For Single Campaign ID targeting one or more users - string For Multiple Campaign IDs targeting one or more users - list of integers	1709550110
ExternalTrigger	Mandatory parameter Includes the campaign message.	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>",
    "ExternalTrigger": {
        "<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	Version
400	Occurs when the credentials are invalid.	{ "status": "fail", "error": "Invalid Credentials", "code": 400 }	V1/V2
400	Occurs when the External Trigger feature is not enabled for your account.	{ "status": "fail", "error": "External Trigger feature is not enabled for your account.", "code": 11 }	V1/V2
400	Occurs when the Campaign ID is invalid.	{ "status": "fail", "error": "Invalid Campaign ID/IDs: All the campaign IDs listed are either not ready or are stopped or pending approval or lack type external trigger", "code": 77 }	V1/V2
400	Occurs when the Campaign ID(s) are missing in the API request.	{ "status": "fail", "error": "Campaign ID(s) are missing in the API request.", "code": 76 }	V1/V2
400	Occurs when there are more campaign IDs included in API requests than the allowed number.	{ "status": "fail", "error": "Sorry!! We don't allow more than 5 campaignIDs in one go :)", "code": 96 }	V2
400	Occurs when the payload length exceeds the permissible limit of 100KB.	{ "status": "fail", "error": "The payload length exceeds the permissible limit of 100KB, currently at {{payloadLength}} bytes.", "code": 17 }	V1/V2
400	Occurs when the `to` parameter is missing from the payload, which is a mandatory parameter.	{ "status": "fail", "error": "to is a mandatory field.", "code": 21 }	V1/V2
400	Occurs when the payload is incorrect: At least one of Identity/Email/ObjectId is required". The payload must include at least one Identity, Email, or ObjectId.",	{ "status": "fail", "error": "Incorrect payload: At least one of Identity/Email/ObjectId is required", "code": 23 }	V1/V2
400	Occurs when there are one or more invalid recipients.	{ "status": "fail", "error": "Invalid recipients.", "code": 25 }	V1/V2
400	Occurs when the number of recipients exceeds the allowed limit of 1000.	{ "status": "fail", "error": "Exceeded_max_identities: Please limit the number of identities to 1000 or fewer", "code": 24 }	V1/V2
400	Occurs when the required JSON keys [keyNames] are missing.	{ "status": "fail", "error": "Required JSON payload not present for these keys [keyNames]", "code": 77 }	V1
400	Occurs when the profile is not found :{param}.	{ "status": "fail", "error": "Profile not found: {param}", "code": 78 }	V1
400	Occurs when all the profiles are not found : [invalid_profiles].	{ "status": "fail", "error": "All Profile not found: [invalid_profiles]", "code": 78 }	V2
400	Occurs when there is some issue in the API request and unable to process it.	{ "status": "fail", "error": "Unexpected error, please try again", "code": 93 }	V1/V2
501	Occurs when there is an unexpected error.	{ "status": "fail", "error": "Unexpected error, please try again", "code": 97 }	V1/V2

External Trigger API

Overview

📘
Public Beta

Base URL

Region

HTTP Method

Headers

Body Parameters

🚧
Note:

Example Request

Sample Response

Error Codes

Overview

📘Public Beta

Base URL

Region

HTTP Method

Headers

Body Parameters

🚧Note:

Example Request

Sample Response

Error Codes

📘
Public Beta

🚧
Note: