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_ACCOUNT_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_ACCOUNT_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 values: 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>",
    "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. The External Trigger feature is not enabled for the account. `to` parameter includes multiple or no recipients. Only one recipient identity is accepted for the parameter. Invalid recipients. `campaign_id` parameter is empty. Given `campaign_id` does not exist. Given `campaign_id` does not have a valid status. Given `campaign_id` is not ready.	{ "status": "fail", "error": "Invalid Credentials", "code": 400 }

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: