Follow

Adaptive Campaign API

Adaptive Campaign API

This REST API enables you to add existing users to one of your existing Adaptive Campaigns. Kahuna adds the users to the campaign asynchronously using a background job, but immediately returns an identifier that lets you check the status of the job. By default, Kahuna starts scheduling pushes as it adds your users, but you can also provide a timestamp as part of the API call that Kahuna uses as the scheduled start time.

API Request

Request URI and Header

Request URI - HTTP POST

To target the production environment: https://tap-nexus.appspot.com/api/campaign/populate?env=p

 

To target the sandbox environment: https://tap-nexus.appspot.com/api/campaign/populate?env=s

 

Request Header

 

Content-Type: application/json

Authorization: The API uses Basic Authentication (BasicAuth), which requires credentials in the form of a username (Secret Key) and password (API Key).

The Secret Key and API Key for the namespace kahoot are:

Secret Key: Available in Settings
API Key: Available in Settings

 

Request Body

The request body is a single JSON dictionary (map) that contains configuration information for the request, a list of users you want to add, and default parameters to push to all users.

You can submit up to ten requests simultaneously. The entire request body must be smaller than 10 MB (approximately 100,000 users).

Parameters
campaign_config

Required. The dictionary of key-value pairs that specifies how to access and manage the campaign.

campaign_id

Required. The identifier, assigned by Kahuna, for the campaign to which you want to add users. This is also known as the campaign group ID. You must use an identifier for an existing adaptive campaign.

To find the identifier for your campaign
  1. From the left navigation pane of the Kahuna application, open Manage > Campaigns in the left navigation pane.
  2. In the campaign list, click the name of your Adaptive campaign to open the Campaign Details page. The identifier appears in a gray box at the top.
cred_type

Required. The Kahuna-specified field name of the user credential that you are using to identify your users. Only one value of cred_type is allowed per request. The field name must be one of the Kahuna white-listed user credentials, which are globally-unique identifiers (GUID) for a user in the Kahuna database. If the value of cred_type is not in the Kahuna white-list, the request fails.

Possible credential types

dev_id—an identifier assigned by Kahuna to the user's device.

username—a GUID representing the user's name

email—an email address for the user

fbid—the user's Facebook ID

twtr—the user's Twitter ID

lnk—the user's LinkedIn ID

user_id—a user ID that you create for the user.

token—the user's push authentication token. This value is not the same as install_token.

install_token—a token that you assign to the device when the user installs your app.

gplus_id—the user's Google Plus ID

target_global_control If this field is set to True, global control users are included. If this field is set to False, global control users are not included. For transactional campaigns, such as purchase confirmation, set this field to True. The default is set to false.
observe_rate_limiting If this field is set to true, and a target user is still in the notification cooldown period, users you add to the campaign using this API request do not receive another message. If the field is set to false, the campaign sends messages to all the added users, even if they are still in cooldown. The default is set to true.
recipient_list

Required. An array of dictionaries containing one or more Recipient Object dictionaries. Each Recipient Object identifies a user and optionally sets parameters that are sent to the user as part of the push.

k_to

Required. An array of values for the user credential you specified in cred_type. Each value specifies a different target user.

Note: The value of k_to must be specified as an array, even if you only specify a single value. All user credential values are strings.

k_send_ts The date and time at which the campaign starts for the users specified in k_to. If this field is not specified, it defaults to the value of k_send_ts specified in the default_params dictionary. The value must be specified as seconds since the POSIX epoch, 01/01/1970 00:00 GMT. Specify this value in GMT time instead of the time for your local time zone.
extra_parameter A key and value you want to send as an extra parameter in push notifications from the campaign. You can include as many extra_parameter values as you want in each recipient object. The size of a push notification and its extra parameters (values and keys) is limited to 235 characters. The extra_parameter values you specify in a recipient object override values you set for the same extra_parameter key in the default_params object.
default_params

The optional default parameters that are sent to all added users. Parameter values for an individual user override default parameter values. This dictionary also enables you to specify a default timestamp that sets the push schedule for all the users you add.

k_send_ts

Required. The date and time at which the campaign starts for all users specified in this request. This value is overriden by a value of k_send_ts specified for an individual Recipient Object.

Note: The value must be specified as seconds since the POSIX epoch, 01/01/1970 00:00 GMT. Specify it in GMT time rather than the time for your local time zone.

extra_parameter Required. One or more keys and values you want to send by default as extra parameters in push notifications to all users specified in this request. There is no limit to the number of extra_parameter pairs you specify. However, the maximum size of a push notification, including the message and extra parameters, is 235 characters. extra_parameter values you specify in a Recipient Object override the values you set for an extra_parameter in default_params.
Examples

The following JSON demonstrates the use of campaign_config and recipient_list. Because the JSON does not include default_params, and none of the recipient objects contain extra parameters, Kahuna does not add any key:value pairs to the message it sends to the specified users.

{
    "campaign_config": {
        "observe_rate_limiting" : false,
        "campaign_id": 999,
        "cred_type" : "email"
    },
    "recipient_list" : [
        {
            "k_to" : [
                "jausten@example.com"
            ]
        },
        {
            "k_to" : [
                "jverne@example.com"
            ]
        }
    ]
}

Extra Parameters

The following JSON demonstrates the use of extra parameters in default_params, as well as extra parameters in each recipient object in recipient_list.

In this example, the first recipient object in the recipient_list contains two extra parameters:

  • "company": "Excelsior Typewriter Co."
  • "department": "President"

The second recipient object only contains "department": "writing".

In addition, default_params contains the default value "company": "Acme Steam Engine, Inc."

As a result, the campaign message sent to the first user contains the following key:value pairs:

  • "company": "Excelsior Typewriter Co."
  • "department": "President"

The campaign message sent to the second user contains the following key:value pairs:

  • "company": "Acme Steam Engine, Inc."
  • "department": "writing"
{
    "campaign_config": {
        "observe_rate_limiting" : false,
        "campaign_id": 999,
        "cred_type" : "email"
    },
    "default_params": {
        "company": "Acme Steam Engine, Inc."
    },
    "recipient_list" : [
        {
            "k_to" : [
                "sclemens@example.com"
            ],
            "company": "Excelsior Typewriter Co.",
            "department" : "President"
        },
        {
            "k_to" : [
                "edickinson@example.com"
            ],
            "department" : "writing"
        }
    ]
}

Structured Parameters

The following JSON demonstrates the use of campaign_config and recipient_list. This example also demonstrates how to send structured extra parameters to Kahuna for use in a MailChimp Handlebars-format email template.

Note: The events extra parameter value is a string that MailChimp parses into key:value pairs. MailChimp expects keys and values in the form of strings, so you need to delimit them with quotes. To ensure that the request body is well-formed JSON, enclose the keys and values with escaped quotes using \" characters.

{
    "campaign_config": {
        "observe_rate_limiting" : false,
        "campaign_id": 999,
        "cred_type" : "email"
    },
    "recipient_list" : [
        {
            "k_to" : [
                "wwhitman@example.com"
            ],
            "company": "Acme Gardening Company",
            "events" : "[{\"name\":\"Marketing Kickoff\"}, {\"name\":\"Lunch 
                with Board\"}]"
        },
        {
            "k_to" : [
                "awalker@example.com"
            ],
            "company": "Mauve Associates, Inc.",
            "events" : "[{\"name\":\"Editorial Conference\"}, {\"name\":\"Go 
                To Press meeting\"}]"
        }
    ]
}

API Response

The response to an Adaptive Campaign request is an HTTP response code and a JSON response body. The response is immediate, even if the Kahuna servers are still processing the request. One of the values returned in the response to a successful request is a job identifier that lets you use the Job Status API to find out the status of your Adaptive Campaign request.

HTTP Response Codes

The servers use the following HTTP response codes.

Codes
200 Kahuna successfully parsed the request. A background job is adding users to the specified campaign. The response body contains a job identifier that you can use to track the progress of the job.
400

The servers are unable to parse the request, for one of the following reasons:

  • The HTTP verb specified in the request is not POST.
  • The request does not contain a request body JSON object.
  • The request body contains errors. For example, the value of campaign_id is not an existing campaign, or the specified user credential type is not in the list of white-listed credentials. Most errors are related to mistakes in the campaign_config dictionary.
401

One of the following errors occurred:

  • The HTTP authentication header does not specify BasicAuth.
  • There is a syntax error in the BasicAuth Username (Secret Key) or Password (API Key).
  • The BasicAuth Username is not known, or the Password is invalid for the specified Username.
  • The request URL is missing the env= parameter.
409 The BasicAuth credentials are valid, but the namespace they represent does not have authorization to use the Adaptive Campaign API.
500 The servers encountered an internal error.
Response Body

Error Response Summary

Fields  
success

If the request fails, this field is set to false. If the request succeeds, this field is not present.

error

If an error occurs, a human-readable error message is provided. If no error occurs, this field is not present.

error_code

If an error occurs, provides the HTTP response code. If no error occurs, this field is not present.

error_detail

If an error occurs, provides details about the error. If no error occurs, this field is not present.

Success Response Summary

Fields
job_id

A Kahuna-assigned identifier for the background job that is processing the users you specified. Use this value with the Job Status API to find out the status of the job.

created

The date and time that the servers created the Adaptive Campaign specified by your request in the format YYYY-MM-DDTHH:mm:ss.ssssss. The time zone is GMT.

status

Indicates the status of the background job that adds the specified users and starts the specified campaign:

  • RUNNING—the job is running.
  • PENDING—the job is waiting to start.
  • DONE—the job is complete.
  • FAILED—some part of the job failed.

The servers set this value and return a response immediately. Use the Job Status API to check the status of the campaign.

campaign_id Repeats the campaign identifier you specified in the request body in campaign_config.
cred_type Repeats the user credential type specified in the request body in campaign_config.
observe_rate_limiting Repeats the value of observe_rate_limiting that you set in the request body in campaign_config.
target_global_control Repeats the value of the target_global_control that you set in the request body in campaign_config.
total_users_requested The total number of users you specified in the recipient_list array in your request object.
total_users_scheduled The total number of users that the servers actually scheduled for the campaign.
total_users_not_found

The total number of users that the servers can not locate in the database.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments