Create Campaign API

Overview

The Create Campaign API lets you send messages to your users. You can specify the audience for your message in two ways. The first option is to target people based on user events and properties. The second option is to target people based on their user ids.

For example, you can use this API to send a price drop alert as a push notification to users who have viewed a certain product in the past week. If you have thousands of products and hundreds of thousands of users, this API lets you create a scalable and targeted way to notify your users of price drop alerts.

Create Campaign API - Target User Events & Properties

To create a campaign, you have to specify the message, channel, and people to target by their user events and properties. For example, a user event could be a purchase event and the user property could be their location.

This endpoint is limited to 1 request per second.

Base URL - Target User Events & Properties

Here is an example base URL from the account in the India region:
https://in1.api.clevertap.com/1/targets/create.json

Region

The following table lists down your API endpoint based on the region of your account:

HTTP Method - Target User Events & Properties

POST

Headers

These headers are all required. The X-CleverTap-Account-Id and X-CleverTap-Passcode are used to authenticate the request. To view how to get their values, refer to the Authentication guide.

Header

Description

Type

Example Value

X-CleverTap-Account-Id

Your CleverTap Account ID.

string

"X-CleverTap-Account-Id: ACCOUNT_ID"

X-CleverTap-Passcode

Your CleverTap Account Passcode.

string

"X-CleverTap-Passcode: PASSCODE"

Content-Type

Request content-type is always set to application/json; charset=utf-8.

string

"Content-Type: application/json; charset=utf-8"

Body Parameters - Target User Events & Properties

Parameter

Description

Required

Type

Example Value

name

The name of your campaign that will be shown in the CleverTap dashboard.

required

string

“My Campaign”

when

When you want to send out the messages. Valid inputs are now (to send the notification right away) or YYYYMMDD HH:MM to schedule the messages for a specific date and time in the future.

required

string

“now”

content

Object that defines the content for your message.

required

string

"content": {
"subject": "Welcome",
"body": "

Your HTML content for the email
",
"sender_name": "CleverTap"
}

content.title

Title content of your push notification message & web push message which is sent to the user.

required

string

“Hi”

content.body

Body content of your push notification, web push, email and sms which is sent to the user.

required

string

“Have you seen the special offer?”

content.subject

Subject content of your email which is sent to the user.

required

string

“Subject”

content.sender_name

Sender name for your email which is sent to the user.

required

string

“Onboarding”

content.template_name

Namespace of the Whatsapp template you want to choose. This is available in settings for all our added Whatsapp templates.

required

string

"662da022_5583_406d_9c71_428d5e3164bb:ticket_update"

content.replacements

Add values that will replace the placeholders in the templates.

required

string

"replacements" : {
"1" : ,
"2" : ,
"3" :
}

content.attachments

Allows you to attach images, videos, documents, and locations to your Whatsapp message based on the attachment defined in your template.

required

string

"attachments": {
"type": "Document",
"value": "http://www.refworld.org/pdfid/4d3025492.pdf"
}"

"attachments": {
"type": "Location",
"value":{
"latitude": "19.8876",
"longitude": "86.0945"
}
}

content.header

Allows you to attach images, videos, documents, and locations in your WhatsApp message based on the attachment type defined in your interactive template.

optional

object

content.body

Dynamically replaces placeholder values in the body of interactive templates.

required

object

content.buttons

Allows you to dynamically add a suffix to CTA button with dynamic URL .

optional

object

provider_nick_name

Allows you to specify which vendor/provider to use for your campaign. For each target_mode, you can have multiple providers integrated with CleverTap, and this parameter lets you select which provider to use for the campaign. For example, let's say you select target_mode = email and you have integrated both SendGrid and Amazon SNS with CleverTap to send emails. In this scenario, you can set provider_nick_name = SendGrid to send the campaign through SendGrid.

optional

string

"Provider 1"

provider_group_nickname

Allows you to specify which provider group to use for your SMS campaign.
Please use the name as added in your account settings

optional

String

"NewTestSMSProviderGroup"

where

Allows you to filter of target base by user events and profile properties. Send an empty object ({}) to target your entire user base.

required

object

"where": {
"event_name": "Charged",
"from": 20171001,
"to": 20171220,
"common_profile_properties": {
"profile_fields": [
{
"name": "Customer Type",
"operator":"equals",
"value": "Platinum"
}
]
}
}

where.event_name

Allows you to target users based on an event they have performed.

optional

string

"Charged"

where.from

Start of date range for event needed. Value specified in format YYYYMMDD.

optional

int

20171001

where.to

End of date range for event needed. Value specified in format YYYYMMDD.

optional

int

20171220

where.profile_fields

Allows you to target users based on the values of their profile fields.

optional

string

"common_profile_properties": {
"profile_fields": [
{
"name": "Customer Type",
"operator":"equals",
"value": "Platinum"
}
]
}

respect_frequency_caps

Set to false if you want to override frequency caps and dwell time.

optional

boolean

true

estimate_only

If this parameter is set to true the request will return an estimated reach of the campaign, which is the number of users who will get the notification when you send it out. Setting this parameter to true will not create the campaign.

optional

boolean

false

async_estimate

This allows setting of the estimate_only flag in the asynchronously. If this parameter is set to true, it will return a request ID that can be passed in the subsequent API call.

optional

boolean

wzrk_cid

Platform specific key that is required to target users on devices running Android O - can be used to determine notification channel to which a given push notification must belong.

If a Notification ID is mandatory then the channel ID is expected. An error occurs if a valid channel ID is not received.

mandatory

string

wzrk_bc

Platform specific key that can be used while targeting users on devices running Android O - can be used to determine the notification count shown on the app icon

optional

int

wzrk_bi

Platform specific key that can be used while targeting users on devices running Android O - can be used to determine which icon should be used.

Accepted values
app icon
notification icon

optional

string

system_control_group_include

If the system control group is enabled from the dashboard, you can choose to use the control group for API campaigns

optional

boolean (true/false)

control_group

If the custom control group is enabled from the dashboard, you can choose to use the control group for API campaigns

optional

string

"control_group": {
"type": "custom"
"name": "name of control group"
}

control_group

You can create a campaign control group via API by specifying the % as described on the left

optional

integer

"control_group": {
"type": "campaign"
"percentage": 5
}

wzrk_acts

Android Action Buttons
"l"= Action Title, "dl" = Deep link, "id" = Action id, "ico" = icon resource identifier

optional

object

wzrk_acts: "[{"l":"Action-1","dl":"","id":"01","ico":""},
{"l":"Action-2","dl":"","id":"02","ico":""},
{"l":"Action-3","dl":"","id":"03","ico":""}]

respect_throttle

Toggle this flag to true if you want to enable throttle limits for the campaign.

optional

boolean

"respect_throttle":true

skip_estimate

Toggle this flag to true if you do not want to estimate the reach. This will lead to faster campaign delivery.

optional

boolean

"skip_estimate":true

send_to_all_devices

The flag is set to false by default. If no value is specified, then the notification is sent to the last active device. Toggle this flag to true if you wish to send notification to all active devices.

optional

boolean

false

segment

The campaign is created only if the segment is processed. You do not need to mention "where" when using segment.

optional

integer

platform_specific

The platform specific details for Web Push notification

optional

String

content.sms.template_id

Template ID (required for sending SMS to phone numbers of India

optional

String

ttl

This allows setting of time to live for push notifications for android and iOS.
The subkeys for ttl are

  • “ttl_type” - with input as “relative” [default] and ”absolute”
  • “value” -
    • For relative ttl, the input is an integer in minutes.
    • For absolute ttl, the input should be an integer in the yyyyMMddHHmm format.

More information is available here

optional

Depends on subkey
ttl_type: string
value: Long

For Absolute TTL -
"ttl" : {
"ttl_type": "absolute",
"value" : 202207200000
},
For Relative TTL -
"ttl" : {
"ttl_type": "relative",
"value" : 2880
},

Example Payloads :

{
    "name": "My Webpush API campaign",
    "estimate_only": true,
    "target_mode":"webpush",
    "where": {
        "event_name": "Charged",
        "from": 20171001,
        "to": 20171220, 
      "common_profile_properties": {
            "profile_fields": [
                {
                    "name": "Customer Type",
                    "operator":"equals",
                    "value": "Platinum"
                }
            ]
        }
    },
    "respect_frequency_caps": false,
    "content": {
        "title": "Hi!",
        "body": "How are you doing today?",
       "platform_specific": {
            "safari": {
                "deep_link": "https://www.google.com",
                "ttl":10
            },
            "chrome": {
              "image": "https://www.exampleImage.com",
              "icon":"https://www.exampleIcon.com",
              "deep_link": "http://www.example.com",
              "ttl":10,
              "require_interaction":true,
              "cta_title1":"title",
              "cta_link1":"http://www.example2.com",
              "cta_iconlink1":"https://www.exampleIcon2.com"
            },
            "firefox": {
                "icon":"https://www.exampleIcon.com",
                "deep_link": "https://www.google.com",
                "ttl":10
            }
        }
    },
    "when": "now"
}
{
    "name": "My API Campaign",
    "estimate_only": true,
    "target_mode":"push",
    "where": {
        "event_name": "App Launched",
        "from": 20150101,
        "to": 20150303,
        "common_profile_properties": {
            "profile_fields": [
                {
                    "name": "Customer Type",
                    "operator":"equals",
                    "value": "Platinum"
                }
            ]
        }
    },
    "respect_frequency_caps": false,
    "ttl": {
             "ttl_type": "absolute",
                "value" : 202207200000 },
    "content": {
        "title": "Hi!",
        "body": "How are you doing today?",
        "platform_specific": {
            "ios": {
                "mutable-content": "true", 
                "deep_link": "example.com",
                "sound_file": "example.caf",
                "category": "application category//Books",
                "badge_count": 1,
                "Key": "Value_ios"
            },
            "android": {
                "wzrk_cid": "Marketing",
                "background_image": "http://example.jpg",
                "default_sound": true,
                "deep_link": "example.com",
                "large_icon": "http://example.png",
                "Key": "Value_android",
                },
            }
        }
    },
    "devices": [
        "android",
        "ios"
    ],
    "when": "now"
}
{
    "name": "My Email API campaign",
    "estimate_only": true,
    "target_mode":"email",
    "where": {
        "event_name": "Charged",
        "from": 20171001,
        "to": 20171220, 
      "common_profile_properties": {
            "profile_fields": [
                {
                    "name": "Customer Type",
                    "operator":"equals",
                    "value": "Platinum"
                }
            ]
        }
    },
    "respect_frequency_caps": false,
    "content": {
        "subject": "Welcome",
        "body": "<div>Your HTML content for the email</div>",
        "sender_name": "CleverTap"
    },
    "when": "now"
}
{
    "name": "My Sms API campaign",
    "estimate_only": true,
    "target_mode":"sms",
    "where": {
        "event_name": "Charged",
        "from": 20171001,
        "to": 20171220, 
      "common_profile_properties": {
            "profile_fields": [
                {
                    "name": "Customer Type",
                    "operator":"equals",
                    "value": "Platinum"
                }
            ]
        }
    },
    "respect_frequency_caps": false,
    "content": {
        "body": "Sms body"
    },
    "when": "now"
}
{
    "name": "My Webhook Campaign",
    "estimate_only": true,
    "target_mode":"webhook",
    "where": {
        "event_name": "Charged",
        "from": 20190101,
        "to": 20191220
    },
    "respect_frequency_caps": false,
    "webhook_endpoint_name":"Recommendation Endpoint",
    "webhook_fields":["profile-attributes","tokens","identities"],
    "webhook_key_value" : {
        "k1":"v1",
        "k2":"v2"
    },
    "when": "now"
}
{    
    "name": "api simple test",
    "estimate_only": false,
    "target_mode":"notificationinbox",
    "where": {
        "event_name": "Charged",
        "from": 20150101,
        "to": 20150303
    },
    "respect_frequency_caps": false,
    "send_to_all_devices": true,
    "template_type":"simple", // mandatory
    "content": [
        {
            "message":{
                "text":"MessageText"
            },
            "title":{
                "text":"titleText"
            },
            "action":{    
                "url":{
                    "android":{
                        "text":"andmurl"    
                    },
                    "ios":{
                        "text":"iosmurl"    
                    }
                },
                "links":[
                    {
                        "type":"copy",
                        "text":"linkText",
                        "copyText":{
                            "text":"copyText"
                        }
                    },
                    {
                        "type":"url",
                        "text":"linkText",
                        "url":{
                            "android":{
                                "text":"andLinkurl"    
                            },
                            "ios":{
                                "text":"iosLinkurl"
                            }
                        }    
                    }
                    ]
            },
            "media":{
                "content_type":"image/jpeg",
                "url":"example.com"
            }
        }
        ],
    "time_to_live":50,    
    "tags":[
        "abc",
        "bcd"
        ],
    "devices": [
        "ios",
        "android"
    ],
    "when": "now"
}
{    
    "name": "api simple test",
    "estimate_only": false,
    "target_mode":"notificationinbox",
    "where": {
        "event_name": "Charged",
        "from": 20150101,
        "to": 20150303
    },
    "respect_frequency_caps": false,
    "send_to_all_devices": true,
    "template_type":"carousel",
    "orientation": "p",
    "content": [
        {
            "message":{
                "text":"Message1"
            },
            "title":{
                "text":"title1"
            },
            "action":{
                "url":{
                    "android":{
                        "text":"andurl1"
                    },
                    "ios":{
                        "text":"iosmurl1"    
                    }
                }
            },
            "media":{
                "content_type":"image/jpg",
                "url":"example.com"
            }
        },
        {
            "message":{
                "text":"Message2"
            },
            "title":{
                "text":"title2"
            },
            "action":{
                "url":{
                    "android":{
                        "text":"andurl2"
                    },
                    "ios":{
                        "text":"iosmurl2"    
                    }
                }
            },
            "media":{
                "content_type":"image/jpg",
                "url":"example.com"
            }
        }
        ],
    "time_to_live":8,
    "tags":[
        "abc",
        "bcd"
        ],
    "devices": [
        "ios",
        "android"
    ],
    "when": "now"
}


// media & template_type is mandatory
{    
    "name": "api simple test",
    "estimate_only": false,
    "target_mode":"notificationinbox",
    "where": {
        "event_name": "Charged",
        "from": 20150101,
        "to": 20150303
    },
    "respect_frequency_caps": false,
    "send_to_all_devices": true,
    "template_type":"carousel-image",
    "orientation": "p",
    "content": [
        {
            "action":{
                "url":{
                    "android":{
                        "text":"andurl1"
                    },
                    "ios":{
                        "text":"iosmurl1"    
                    }
                }
            },
            "media":{
                "content_type":"image/jpg",
                "url":"example.com"
            }
        },
        {
            "message":{
                "text":"Message2"
            },
            "title":{
                "text":"title2"
            },
            "action":{
                "url":{
                    "android":{
                        "text":"andurl2"
                    },
                    "ios":{
                        "text":"iosmurl2"    
                    }
                }
            },
            "media":{
                "content_type":"image/jpg",
                "url":"example.com"
            }
        }
        ],
    "time_to_live":8,
    "tags":[
        "abc",
        "bcd"
        ],
    "devices": [
        "ios",
        "android"
    ],
    "when": "now"
}


// media & template_type is mandatory
{    
    "name": "api app inbox icon",
    "estimate_only": false,
    "target_mode":"notificationinbox",
    "where": {
        "event_name": "App Launched",
        "from": 20190101,
        "to": 20190418
    },
    "respect_frequency_caps": false,
    "send_to_all_devices": true,  
    "template_type":"message-icon",
    "orientation": "p",
    "content": [
        {
            "message":{
                "text":"MessageTexticon"
            },
            "title":{
                "text":"titleTextIcon"
            },
            "action":{
                "url":{
                    "android":{
                        "text":"andmurl"
                    },
                    "ios":{
                        "text":"iosmurl"    
                    }
                },
                "links":[
                    {
                        "type":"url",
                        "text":"linktextIcon",
                        "color":"#000000",
                        "bg":"#ffff",
                        "url":{
                            "android":{
                                "text":"andlurl"
                            },
                            "ios":{
                                "text":"ioslurl"
                            }
                        }
                    }
                    ]
            },
            "media":{
                "content_type":"image/jpg",
                "url":"https://s3.amazonaws.com/ct-demo-images/landscape-2.jpg"
            },
            "icon":{
                "content_type":"image/jpg",
                "url":"https://s3.amazonaws.com/ct-demo-images/landscape-2.jpg"
            }
        }
        ],
    "time_to_live":50,    
   
    "devices": [
        "ios",
        "android"
    ],
    "when": "now"
}

// template_type is mandatory
{
    "name": "Standard Whatsapp campaign",
    "estimate_only": false,
    "target_mode": "whatsapp",
    "where": {
        "event_name": "Added To Cart",
        "from": 20200610,
        "to": 20200619,
        "common_profile_properties": {
            "profile_fields": [
                {
                    "name": "Fruit",
                    "operator":"equals",
                    "value": "Apple"
                }
            ]
        }
    },
    "respect_frequency_caps": false,
    
    "system_control_group_include": false,
    "content": {
        "template_name": "662da022_5583_406d_9c71_428d5e3164bb:ticket_update",
        "replacements": {
            "1": "buddy",
            "2":"Где ты се, Pад познакомиться."
            
        },
        "attachments": {
            "type": "Document",
            "value": "http://www.refworld.org/pdfid/4d3025492.pdf"
        }
    },
    "when": "now"
}

Following is the JSON payload for the iOS Carousel Push template:

{
    "name": "My API Campaign",
    "estimate_only": true,
    "target_mode":"push",
    "where": {
        "event_name": "App Launched",
        "from": 20150101,
        "to": 20150303,
        "common_profile_properties": {
            "profile_fields": [
                {
                    "name": "Customer Type",
                    "operator":"equals",
                    "value": "Platinum"
                }
            ]
        }
    },
    "respect_frequency_caps": false,
    "content": {
        "title": "Hi!",
        "body": "How are you doing today?",
        "platform_specific": {
            "ios": {
                "mutable-content": "true", 
                "deep_link": "example.com",
                "sound_file": "example.caf",
                "category": "CTNotification",
                "badge_count": 1,
                "ct_ContentSlider": {
        "orientation": "landscape", // landscape assumes 16:9 images, remove to display default square/portrait images
        "showsPaging": true, // optional to display UIPageControl
        "autoPlay": true, // optional to auto play the slideshow
        "autoDismiss": true, // optional to auto dismiss the notification on item actionUrl launch
        "items":[
            {
                "caption": "caption one",
                "subcaption": "subcaption one",
                "imageUrl": "https://s3.amazonaws.com/ct-demo-images/landscape-1.jpg",
                "actionUrl": "com.clevertap.ctcontent.example://item/one"
            }, 
            {
                "caption": "caption two", 
                "subcaption": "subcaption two", 
                "imageUrl": "https://s3.amazonaws.com/ct-demo-images/landscape-2.jpg",
                "actionUrl": "com.clevertap.ctcontent.example://item/two"
            }
       ]
   }
            }
        }
    },
    "devices": [
        "ios"
    ],
    "when": "now"
}

Following is the JSON payload for WhatsApp interactive message templates:

{
    "name": "Interactive Whatsapp Campaign",
    "estimate_only": false,
    "target_mode": "whatsapp",
    "where": {
        "event_name": "Added To Cart",
        "from": 20200610,
        "to": 20200619,
        "common_profile_properties": {
            "profile_fields": [
                {
                    "name": "Fruit",
                    "operator":"equals",
                    "value": "Apple"
                }
            ]
        }
    },
    "respect_frequency_caps": false,
    
    "system_control_group_include": false,
    "content": {
        "template_name": "662da022_5583_406d_9c71_428d5e3164bb:ticket_update",
        "header": {
            "type": "image",  
            "media": {
                "url": "https://googl.com/a.jpg/"
            }
        },
        "body": {
            "replacements": []
        }     
      },
    "when": "now"
}
{
    "name": "Interactive Whatsapp Campaign",
    "estimate_only": false,
    "target_mode": "whatsapp",
    "where": {
        "event_name": "Added To Cart",
        "from": 20200610,
        "to": 20200619,
        "common_profile_properties": {
            "profile_fields": [
                {
                    "name": "Fruit",
                    "operator":"equals",
                    "value": "Apple"
                }
            ]
        }
    },
    "respect_frequency_caps": false,
    
    "system_control_group_include": false,
    "content": {
        "template_name": "662da022_5583_406d_9c71_428d5e3164bb:ticket_update",
        
        "header": {
            "type": "text",
            "replacements": ["Dummy User", "22/10/2021"]
        },
        "body": {
            "replacements": ["dummy"]
        }
       
      },
    "when": "now"
}
{
    "name": "Interactive Whatsapp Campaign",
    "estimate_only": false,
    "target_mode": "whatsapp",
    "where": {
        "event_name": "Added To Cart",
        "from": 20200610,
        "to": 20200619,
        "common_profile_properties": {
            "profile_fields": [
                {
                    "name": "Fruit",
                    "operator":"equals",
                    "value": "Apple"
                }
            ]
        }
    },
    "respect_frequency_caps": false,
    
    "system_control_group_include": false,
    "content": {
        "template_name": "662da022_5583_406d_9c71_428d5e3164bb:ticket_update",
        "header": {
            "type": "document",   
            "media": {
                "url": "https://googl.com/a.pdf"
            }
        },
        "body": {
            "replacements": ["Dummy User", "22/10/2021"]
        }     
      },
    "when": "now"
}
{
    "name": "Interactive Whatsapp Campaign",
    "estimate_only": false,
    "target_mode": "whatsapp",
    "where": {
        "event_name": "Added To Cart",
        "from": 20200610,
        "to": 20200619,
        "common_profile_properties": {
            "profile_fields": [
                {
                    "name": "Fruit",
                    "operator":"equals",
                    "value": "Apple"
                }
            ]
        }
    },
    "respect_frequency_caps": false,
    
    "system_control_group_include": false,
    "content": {
        "template_name": "662da022_5583_406d_9c71_428d5e3164bb:ticket_update",
        "header": {
            "type": "video",
            "media": {
                "url": "https://googl.com/a.mp4"
            }
        },
        "body": {
            "replacements": ["Dummy User", "22/10/2021"]
        }     
      },
    "when": "now"
}
{
    "name": "Interactive Whatsapp Campaign",
    "estimate_only": false,
    "target_mode": "whatsapp",
    "where": {
        "event_name": "Added To Cart",
        "from": 20200610,
        "to": 20200619,
        "common_profile_properties": {
            "profile_fields": [
                {
                    "name": "Fruit",
                    "operator":"equals",
                    "value": "Apple"
                }
            ]
        }
    },
    "respect_frequency_caps": false,
    
    "system_control_group_include": false,
    "content": {
        "template_name": "662da022_5583_406d_9c71_428d5e3164bb:ticket_update",
        "header": {
            "type": "location",
            "media": {
                "latitiude": 32.123,
                "longitude": 123.32,
                "name": "facebook ",
                "address": "facebook "
            }
        },
        "body": {
            "replacements": ["Dummy User", "22/10/2021"]
        }     
      },
    "when": "now"
}
{
   "name":"Interactive Whatsapp Campaign",
   "estimate_only":false,
   "target_mode":"whatsapp",
   "where":{
      "event_name":"Added To Cart",
      "from":20200610,
      "to":20200619,
      "common_profile_properties":{
         "profile_fields":[
            {
               "name":"Fruit",
               "operator":"equals",
               "value":"Apple"
            }
         ]
      }
   },
   "respect_frequency_caps":false,
   "system_control_group_include":false,
   "content":{
      "template_name":"662da022_5583_406d_9c71_428d5e3164bb:ticket_update",
      "header":{
         "type":"location",
         "media":{
            "latitiude":32.123,
            "longitude":123.32,
            "name":"facebook ",
            "address":"facebook "
         }
      },
      "body":{
         "replacements":[
            "Dummy User",
            "22/10/2021"
         ]
      },
      "buttons":[
         {
            "replacements":[
             "suffix"  
            ]
         }
      ]
   },
   "when":"now"
}

Example Request - Target User Events & Properties

Here is an example cURL request to the Create Campaign API showing the headers needed to authenticate the request from the account in the India region:

curl -X POST -d ' {"name": "My Sms API campaign","estimate_only": true,"target_mode":"sms", "where":{"event_name":"Charged","from":20171001,"to":20171220,"common_profile_properties":{"profile_fields": [ {"name": "Customer Type","operator":"equals","value": "Platinum"}]}},"respect_frequency_caps": false,"content": { "body": "Sms body"},"when": "now"}' \
"https://in1.api.clevertap.com/1/targets/create.json" \
-H "X-CleverTap-Account-Id: ACCOUNT_ID" \
-H "X-CleverTap-Passcode: PASSCODE" \
-H "Content-Type: application/json"
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://in1.api.clevertap.com/1/targets/create.json ")
request = Net::HTTP::Post.new(uri)
request.content_type = "application/json"
request["X-Clevertap-Account-Id"] = "ACCOUNT_ID"
request["X-Clevertap-Passcode"] = "PASSCODE"
request.body = JSON.dump({
  "name" => "My Sms API campaign",
  "estimate_only" => true,
  "target_mode" => "sms",
  "where" => {
    "event_name" => "Charged",
    "from" => 20171001,
    "to" => 20171220,
    "common_profile_properties" => {
      "profile_fields" => [
        {
          "name" => "Customer Type",
          "operator" => "equals",
          "value" => "Platinum"
        }
      ]
    }
  },
  "respect_frequency_caps" => false,
  "content" => {
    "body" => "Sms body"
  },
  "when" => "now"
})

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'X-CleverTap-Account-Id': 'ACCOUNT_ID',
    'X-CleverTap-Passcode': 'PASSCODE',
    'Content-Type': 'application/json',
}

data = ' {"name": "My Sms API campaign","estimate_only": true,"target_mode":"sms", "where":{"event_name":"Charged","from":20171001,"to":20171220,"common_profile_properties":{"profile_fields": [ {"name": "Customer Type","operator":"equals","value": "Platinum"}]}},"respect_frequency_caps": false,"content": { "body": "Sms body"},"when": "now"}'

response = requests.post('https://in1.api.clevertap.com/1/targets/create.json', headers=headers, data=data)
<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array(
    'X-CleverTap-Account-Id' => 'ACCOUNT_ID',
    'X-CleverTap-Passcode' => 'PASSCODE',
    'Content-Type' => 'application/json'
);
$data = ' {"name": "My Sms API campaign","estimate_only": true,"target_mode":"sms", "where":{"event_name":"Charged","from":20171001,"to":20171220,"common_profile_properties":{"profile_fields": [ {"name": "Customer Type","operator":"equals","value": "Platinum"}]}},"respect_frequency_caps": false,"content": { "body": "Sms body"},"when": "now"}';
$response = Requests::post('https://in1.api.clevertap.com/1/targets/create.json', $headers, $data);
var request = require('request');

var headers = {
    'X-CleverTap-Account-Id': 'ACCOUNT_ID',
    'X-CleverTap-Passcode': 'PASSCODE',
    'Content-Type': 'application/json'
};

var dataString = ' {"name": "My Sms API campaign","estimate_only": true,"target_mode":"sms", "where":{"event_name":"Charged","from":20171001,"to":20171220,"common_profile_properties":{"profile_fields": [ {"name": "Customer Type","operator":"equals","value": "Platinum"}]}},"respect_frequency_caps": false,"content": { "body": "Sms body"},"when": "now"}';

var options = {
    url: 'https://in1.api.clevertap.com/1/targets/create.json ',
    method: 'POST',
    headers: headers,
    body: dataString
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);

Example Response - Target User Events & Properties

{
  "status": "success",
  "estimates": {
    "web": 2
  }
}

Example Request - Event Occurrence

{
    "advanced_query": {
        "did_all": [
            {
                "event_name": "App Launched",
                "from": 20200101,
                "to": 20200218,
                "operator": "greater_than_equals",
                "value": 5,
            }
        ]
    }
}

Create Campaign API - Target Users by their Identities

You can send notifications to your users based on their Facebook ID, Email ID, custom-defined identity, or CleverTap ID.

You can message 1000 users per API request.

Base URL - Target Users by their Identities

The endpoint is different based on the channel you are sending the message.

Following are some example base URLs from the account in the India region:

SMS
https://in1.api.clevertap.com/1/send/sms.json

Push
https://in1.api.clevertap.com/1/send/push.json

❗️

Note:

The push.json API currently does not support Pull Notifications.

Web Push
https://in1.api.clevertap.com/1/send/webpush.json

Email
https://in1.api.clevertap.com/1/send/email.json

📘

Region

These are some example base URLs from the account in the India region. To know the API endpoint for your account, refer to Region.

HTTP Method - Target Users by their Identities

POST

Headers - Target Users by their Identities

These headers are all required. The X-CleverTap-Account-Id and X-CleverTap-Passcode are used to authenticate the request. Please see the authentication guide to see how to get their values.

Header

Description

Type

Example Value

X-CleverTap-Account-Id

Your CleverTap Account ID.

string

"X-CleverTap-Account-Id: ACCOUNT_ID"

X-CleverTap-Passcode

Your CleverTap Account Passcode.

string

"X-CleverTap-Passcode: PASSCODE"

Content-Type

Request content-type should always set to application/json; charset=utf-8.

string

"Content-Type: application/json;charset=utf-8"

Body Parameters - Target Users by their Identities

The body is uploaded as a JSON payload.

to, name, title, body, subject, sender_name, and target_mode are required parameters.

The to parameter is an object that has the following child properties: FBID, Email, Identity, objectId, which are used as identifiers to target your users. Each request can contain a max of 1000 users across these identifiers.

Parameter

Description

Required

Type

Example Value

to

Used to define which users will receive the message.

required

object

"to": {
"FBID": [
"102029292929388",
"114342342453463"
],

    "Email": [
        "[email protected]",
        "[email protected]"
    ],
    "Identity": [
        "JohnDoe"
    ],
    "objectId": [
        "_asdnkansdjknaskdjnasjkndja",
        "-adffajjdfoaiaefiohnefwprjf"
    ]
}

to.FBID

Facebook ID for user.

required

array of strings

"to": {
"FBID": [
"102029292929388",
"114342342453463"
]
}

to.Email

Email identifier for user.

required

array of strings

{
"to": {
"Email": [
"[email protected]",
"[email protected]"
]
}

to.Identity

Custom-defined identifier for user.

required

array of strings

{
"to": {
"Identity": [
"JohnDoe"
]
}

to.objectId

CleverTap identifier for user.

required

array of strings

{
"to": {
"objectId": [
"sdnkansdjknaskdjnasjkndja", "dffajjdfoaiaefiohnefwprjf"
]
}

tag_group

Each message can be tagged into a tag group. Metrics, such as sent and viewed, will be shown against each tag group in the CleverTap dashboard. Max 500 groups. If not specified, the merics will be shown against the “Not Tagged” tag.

optional (either use tag _group or campaign_id)

string

"my tag group"

content

Object that defines the content for your message.

required

object

"content": {
"subject": "Welcome",
"body": "

Your HTML content for the email
",
"sender_name": "CleverTap"
}

content.title

Title content of your push notification message and web push message which is sent to the user.

required

string

"Hi"

content.body

Body content of your push notification, web push, email and sms which is sent to the user.

required

string

“Have you seen the special offer?”

content.subject

Subject content of your email which is sent to the user.

required

string

"Subject"

content.sender_name

Sender name for your email which is sent to the user.

required

string

“Onboarding”

provider_nick_name

Allows you to specify which vendor/provider to use for your campaign. For each target_mode, you can have multiple providers integrated with CleverTap, and this parameter lets you select which provider to use for the campaign. For example, let's say you select target_mode = email and you have integrated both SendGrid and Amazon SNS with CleverTap to send emails. In this scenario, you can set provider_nick_name = SendGrid to send the campaign through SendGrid.

optional

string

"Provider 1"

respect_frequency_caps

Set to false if you want to override frequency caps.

optional

boolean

false

wzrk_cid

Platform specific key that is required to target users on devices running Android O - can be used to determine notification channel to which a given push notification must belong.

If a Notification ID is mandatory then the channel ID is expected. An error occurs if a valid channel ID is not received.

mandatory

string

badge_id

Platform specific key that can be used while targeting users on devices running Android O - can be used to determine the notification count shown on the app icon

optional

int

badge_icon

Platform specific key that can be used while targeting users on devices running Android O - can be used to determine which icon should be used.

Accepted values
app icon
notification icon

optional

string

mutable-content

To raise Notification viewed event for Push notifications, raise the flag to "true" in the platform_specific: ios section of the request payload.

optional

boolean

platform_specific

The platform specific details for Web Push notification

optional

string

background_image

The parameter to render images in the push notification for Android.

Optional

string

ct_mediaUrl

The parameter to render images in the push notification for iOS.

Optional

string

wzrk_clr

A Platform specific key that can be used to set color for small icons in push notifications.

optional

string

#1DA1F2

Below are example payloads for web push, push, email, and SMS.

{
    "to": {
        "FBID": [
            "102029292929388",
            "114342342453463"
        ],
       
        "Email": [
            "[email protected]",
            "[email protected]"
        ],
        "Identity": [
            "JohnDoe"
        ],
        "objectId": [
            "_asdnkansdjknaskdjnasjkndja",
            "-adffajjdfoaiaefiohnefwprjf"
        ]
    },
    "tag_group": "my tag group",
        "campaign_id": 1000000043,
    "respect_frequency_caps": false,
     "content": {
        "title": "Hi!",
        "body": "How are you doing today?",
       "platform_specific": {
            "safari": {
                "deep_link": "https://www.google.com",
                "ttl":10
            },
            "chrome": {
              "image": "https://www.exampleImage.com",
              "icon":"https://www.exampleIcon.com",
              "deep_link": "http://www.example.com",
              "ttl":10,
              "require_interaction":true,
              "cta_title1":"title",
              "cta_link1":"http://www.example2.com",
              "cta_iconlink1":"https://www.exampleIcon2.com"
            },
            "firefox": {
                "icon":"https://www.exampleIcon.com",
                "deep_link": "https://www.google.com",
                "ttl":10
            }
        }
    }
}
{
    "to": {
        "FBID": [
            "102029292929388",
            "114342342453463"
        ],
        "GPID": [
            "1928288389299292"
        ],
        "Email": [
            "[email protected]",
            "[email protected]"
        ],
        "Identity": [
            "JohnDoe"
        ],
        "objectId": [
            "_asdnkansdjknaskdjnasjkndja",
            "-adffajjdfoaiaefiohnefwprjf"
        ]
    },
    "tag_group": "my tag group",
    "respect_frequency_caps": false,
    "content": {
        "title": "Welcome",
        "body": "Hello world!",
        "platform_specific": {
            "ios": {
                "deep_link": "example.com",
                "sound_file": "example.caf",
                "mutable-content": "true", 
                "ct_mediaUrl": "https://i.ibb.co/pJ8D5Z7/woman-g40aa99db5-1920.jpg",
                "category": "notification category",
                "badge_count": 1,
                "key": "value_ios"
            },
            "android": {
                "background_image": "http://example.jpg",
                "default_sound": true,
                "deep_link": "example.com",
                "large_icon": "http://example.png",
                "key": "value_android"
            }
        }
    }
}
{
    "to": {
        "FBID": [
            "102029292929388",
            "114342342453463"
        ],
        "GPID": [
            "1928288389299292"
        ],
        "Email": [
            "[email protected]",
            "[email protected]"
        ],
        "Identity": [
            "JohnDoe"
        ],
        "objectId": [
            "_asdnkansdjknaskdjnasjkndja",
            "-adffajjdfoaiaefiohnefwprjf"
        ]
    },
    "tag_group": "my tag group",
    "respect_frequency_caps": false,
    "content": {
        "subject": "Welcome",
        "body": "<div>Your HTML content for the email</div>",
        "sender_name": "CleverTap"
    }
}
{
    "to": {
        "FBID": [
            "102029292929388",
            "114342342453463"
        ],
        "GPID": [
            "1928288389299292"
        ],
        "Email": [
            "[email protected]",
            "[email protected]"
        ],
        "Identity": [
            "JohnDoe"
        ],
        "objectId": [
            "_asdnkansdjknaskdjnasjkndja",
            "-adffajjdfoaiaefiohnefwprjf"
        ]
    },
    "tag_group": "my tag group",
    "respect_frequency_caps": false,
     "content": {
        "body": "Sms body"
    }
}

Example Request - Target Users by their Identities

Here is an example cURL request to the Create Campaign API showing the headers needed to authenticate the request from the account in the India region:

curl -X POST -d '{"to":{"FBID":["102029292929388","114342342453463"],"Email":["[email protected]","[email protected]"],"Identity":["JohnDoe"],"objectId":["_asdnkansdjknaskdjnasjkndja","-adffajjdfoaiaefiohnefwprjf"]},"campaign_id":1000000043,"tag_group":"mytaggroup","respect_frequency_caps":false,"content":{"body":"Smsbody"}}' \
"https://in1.api.clevertap.com/1/send/sms.json" \
-H "X-CleverTap-Account-Id: ACCOUNT_ID" \
-H "X-CleverTap-Passcode: PASSCODE" \
-H "Content-Type: application/json"
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://in1.api.clevertap.com/1/send/sms.json")
request = Net::HTTP::Post.new(uri)
request.content_type = "application/json"
request["X-Clevertap-Account-Id"] = "ACCOUNT_ID"
request["X-Clevertap-Passcode"] = "PASSCODE"
request.body = JSON.dump({
  "to" => {
    "FBID" => [
      "102029292929388",
      "114342342453463"
    ],
   
    "Email" => [
      "[email protected]",
      "[email protected]"
    ],
    "Identity" => [
      "JohnDoe"
    ],
    "objectId" => [
      "_asdnkansdjknaskdjnasjkndja",
      "-adffajjdfoaiaefiohnefwprjf"
    ]
  },
  "tag_group" => "mytaggroup",
  "respect_frequency_caps" => false,
  "content" => {
    "body" => "Smsbody"
  }
})

req_options = {
  use_ssl: uri.scheme == "https",
}

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
import requests

headers = {
    'X-CleverTap-Account-Id': 'ACCOUNT_ID',
    'X-CleverTap-Passcode': 'PASSCODE',
    'Content-Type': 'application/json',
}

data = '{"to":{"FBID":["102029292929388","114342342453463"],"Email":["[email protected]","[email protected]"],"Identity":["JohnDoe"],"objectId":["_asdnkansdjknaskdjnasjkndja","-adffajjdfoaiaefiohnefwprjf"]},"tag_group":"mytaggroup","respect_frequency_caps":false,"content":{"body":"Smsbody"}}'

response = requests.post('https://in1.api.clevertap.com/1/send/sms.json', headers=headers, data=data)
<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array(
    'X-CleverTap-Account-Id' => 'ACCOUNT_ID',
    'X-CleverTap-Passcode' => 'PASSCODE',
    'Content-Type' => 'application/json'
);
$data = '{"to":{"FBID":["102029292929388","114342342453463"],"Email":["[email protected]","[email protected]"],"Identity":["JohnDoe"],"objectId":["_asdnkansdjknaskdjnasjkndja","-adffajjdfoaiaefiohnefwprjf"]},"tag_group":"mytaggroup","respect_frequency_caps":false,"content":{"body":"Smsbody"}}';
$response = Requests::post('https://in1.api.clevertap.com/1/send/sms.json', $headers, $data);
var request = require('request');

var headers = {
    'X-CleverTap-Account-Id': 'ACCOUNT_ID',
    'X-CleverTap-Passcode': 'PASSCODE',
    'Content-Type': 'application/json'
};

var dataString = '{"to":{"FBID":["102029292929388","114342342453463"],"GPID":["1928288389299292"],"Email":["[email protected]","[email protected]"],"Identity":["JohnDoe"],"objectId":["_asdnkansdjknaskdjnasjkndja","-adffajjdfoaiaefiohnefwprjf"]},"tag_group":"mytaggroup","respect_frequency_caps":false,"content":{"body":"Smsbody"}}';

var options = {
    url: 'https://in1.api.clevertap.com/1/send/sms.json',
    method: 'POST',
    headers: headers,
    body: dataString
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);

Example Response - Target Users by their Identities

{
    "status": "success",
    "message": "Added to queue for processing"
}

A success response implies payload validity and addition to the processing queue. Message delivery is handled by the provider (push or email) and depends on if you provided a valid recipient id.

Notes

If there are errors, you will receive a response in the format below.

{
    "status": "fail",
    "error": "<error message here>",
    "code": <error code here>
}

Here are the possible error codes.
21 – to is a mandatory field
84 – Invalid recipients”
73 – “respect_frequency_caps” must be a Boolean
78 – Invalid JSON payload
89 – Unexpected error, please try again

Unsubscribe Link for Emails

If you’re using Amazon SES or your own SMTP gateway, you’ll have to follow the steps listed on this page to enable your users to unsubscribe from your email notifications.