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 TypeBase URL
Single Campaign ID targeting one or more usershttps://in1.api.clevertap.com/1/send/externaltrigger.json
Multiple Campaigns IDs targeting one or more usershttps://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"
                    }
                ]
            }
        ]
    }
}'
ParameterDescriptionTypeExample 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 CodeDetailsSample 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
    }