interakt Track APIs

Here are the reference docs for connecting to our APIs.
Check out our Postman Collection & Python SDK.


Intro to interakt APIs

User Track API
- How to add / update User Details on interakt via User track APIs
- Seeing the added Users in your interakt dashboard
- Setting Campaigns (from interakt dashboard) for the added Users - based on conditions on User Traits

Event Track API
- How to add Event Details for a user on interakt via Event track APIs
- Seeing the added Events in your interakt dashboard
- Setting Campaigns (from interakt dashboard) - based on conditions on Event Properties

Intro to interakt APIs

The interakt Track API endpoints allow you to trigger specific data to interakt. These API endpoints can be used to add users and their events to your interakt account, which can then be available to:

Build more context when chatting with your customers, and
Set up personalized and relevant notifications at scale. 

You can call these APIs as soon as a new user is created on your website or app or even later as you deem fit. There are two APIs available:

• User track APIs: to create a new user and insert their traits to your interakt dashboard and
Event track APIs: to record any events for that user in your interakt dashboard

There’s a difference between a ‘trait’ sent to the user endpoint, compared to a ‘trait’ sent to the event endpoint:

User endpoint: For the same trait, if you send a new value, it’ll replace the current value.
Event endpoint: Same events sent at different points in time are represented on a timeline and don't replace each other.

Illustrations

1. Suppose you send an event named ‘New Order’ for your user with traits ‘Order Number’ & ‘Order Amount’, whenever the user places an order on your website. Every time the event ‘New Order’ is received on our Event Track endpoint, it is recorded in the events timeline for the user as shown below.

2. On the other hand, say you want to record the ‘total order amount’ till date for a user. For that, you can send the trait ‘amount’ to the User Track endpoint, which then gets displayed in the Personal Details card, as shown below. Unlike the events endpoint, the old values of traits sent to the users endpoint will get replaced by the new value. Here, the trait ‘amount’ shows the value 2000 at first. Upon sending 7000 as the new value, the old value is replaced, as shown below.

Headers


Authentication:

You can authenticate with interakt Track APIs by sending the API Key along with the request data. Authentication mechanism uses HTTP Basic Auth which requires you to send a base64 encoded ‘username:password’ prepended with the ‘Basic’ string.

API Key = base64 encoded ‘username:password’ 

This value is passed in the header under ‘Authorization’ and the header key-pair will look like 'Authorization: Basic <API Key>'.

Please note: You can find the API key in your dashboard. Go to Settings > Developer Setting > Secret Key.

Content-Type:

You must set the content-type header to 'application/json' to be able to send data to our HTTP API endpoint.

Errors:

Our API endpoints will return 200 status code for all successful requests. If the request is large, you may get a 400 status code.

Note: In case a trait contains any of the following, the API call will return 400 status code:
‘Newline / Tab / More than 2 consecutive spaces’

Rate Limits:

We don’t have a hard limit on the number of requests per second. However, if you are planning to send requests at a higher rate, please reach out to us before you do it.

Max Request Size:

The maximum request size is 32KB per request. If this rate is exceeded, the API responds with 400 Bad Request.

User Track API

How to add / update User Details on interakt via User track APIs

The user track API allows customers to record the attributes specific to the user. They can record specific user properties (attributes) such as user id, email id, phone number, name etc. Customers can call the usertrack API when a new user account is created on their website/app/CRM. For example:

 
For adding a new user to your interakt dashboard, the following payload could be sent in the API call:

POST https://api.interakt.ai/v1/public/track/users/

{

“userId”: “0123abc45d”,
“phoneNumber”: “9967536783”,
“countryCode”: “+91”,
“traits”: {
         “name”: “Gavin Roberts”,
          “email”: “gavinroberts01@outlook.com”,
          “dob”: “1996-12-01”,
         "Sample trait a":"value y"

    }

}

The different user attributes (traits) can be of the following data types: String, Numbers, Boolean, Datetime, List. Check out the different filter options available in interakt, for different trait types - link.

Note**: Specifying either the user Id or phoneNumber (with countryCode) is Mandatory

The above API call records the “userId” or “phoneNumber” (with “countryCode”) as a unique identifier for the user and also adds attributes such as name, email, dob.

Event Property Type Status Description
userId String Optional** The userId can take any string value that you specify. This will henceforth be used as a unique identifier for the user.
phoneNumber String Optional** phone number of the user without the country code (we recommend that you send the Whatsapp phone number of the user, so that you can send messages to that user via interakt, else the messages won’t get sent)
countryCode String Optional** Country code of the phone number. The default value is “+91”.
traits Object Optional User attributes such as name, email id etc.
createdAt Date Optional Timestamp of the event in ISO-8601 format date string. If you have not passed the “createdAt” property, we will automatically use the current utc server time as the value of “createdAt”


To update attributes for the above user, the following payload could be sent in the API call: (suppose the “dob” attribute needs to be changed to “1997-12-01”).

POST https://api.interakt.ai/v1/public/track/users/

{
          “userId”: “0123abc45d”,
          “phoneNumber”: “9967536783”,
          “countryCode”: “+91”,
          “traits”: {
                   “dob”: “1997-12-01”
         }
}

To add a new attribute for the above user, the following payload could be sent in the API call: (suppose the “pin code” attribute needs to be added).

POST https://api.interakt.ai/v1/public/track/users/

{

          “userId”: “0123abc45d”,
          “phoneNumber”: “9967536783”,
          “countryCode”: “+91”,
          “traits”: {
                   “Pin code”: “400001”
          }
}

Note:

1. In case, the above user had originally been added via the interakt dashboard (and not by calling the User Track API), then, no userId would exist for that user. In that case, you could either:
Call the User Track API without specifying a “userId” (and only specifying the “phoneNumber” & “countryCode”), or,  
Include a userId in the API call, which will then get added for that user, and you could use that userId to reference that user in future API calls.*

2. Currently, we don’t provide the option for deleting any user / user attribute. 
 
*Please make sure the added userId doesn’t belong to an already existing user in your interakt account, else the API will throw an error. 

Where can you see the added Users in your interakt dashboard?

Upon creation of a user by calling the User Track API, the user (along with the traits) would then be visible in the following sections of the interakt dashboard:

The new user will be listed in the ‘Users’ page:


The user traits would be visible in the ‘Personal Details’ card - this card is visible in 2 places: 1) In the inbox chat with the particular user; 2) in the user details section (upon clicking on a user entry).


Moreover, you will now be able to filter your user list with these traits (the filter option is available in the Users page & in the Notifications page, when you create a New Campaign) - you can further find here different filter options, corresponding to data types of traits.

Setting Campaigns for the added Users based on conditions on User Traits:

• One time Campaign: This campaign can be used for a one-time broadcast message that you want to send out to your users.

- Use case: Suppose you have been sending the user trait ‘Company Type’ for your users via our user track API. Say, you want to send a broadcast message to all your existing users for whom the recorded ‘Company Type’ contains the term ‘grocery’.

- To do this, you would need to select a ‘one time’ campaign and set the following filter condition in the Campaign Creation page: ‘Company Type’ contains ‘grocery’. (In the below example, the number of users qualifying this criteria is 38.) 

- Once you set the campaign live from the Campaign Creation page, all those 38 users will be sent the notification on the scheduled date.

Click here to check out the detailed steps for setting a Campaign live.


• Ongoing Campaign: These are campaigns that are sent to users regularly based on certain trigger occurrences. 

- Use case: Suppose you want to send automatic notifications to a new user as soon as the user is added, given that the user trait ‘Company Type’ contains the term ‘grocery’ for that user.

- To do this, you would need to set up an ‘ongoing’ campaign and select the same filter condition i.e. ‘Company Type’ contains ‘grocery’. 

- However, by doing that, the existing 38 users won't be sent the notification. Instead, the notification will get sent:

As soon as a user, for whom the trait ‘Company Type’ containing the term ‘grocery’ in it, is added to your interakt account (either via APIs or via bulk csv upload), or,

As soon as an existing user’s ‘Company Type’ is updated such that it contains the term ‘grocery’. 

This ongoing campaign can be set with a custom end date, or, you could even choose to let it continue perpetually in future. You will have the option to pause it anytime in future.

Click here to check out the detailed steps for setting a Campaign live.

Event Track API

How to add Event Details for a user on interakt via Event track APIs

The event track API allows customers to record user actions. Each user action (such as a new order created, new user sign up, and so on) will trigger an event to the endpoint. For example:

For adding a new event for a particular user, the following payload could be sent in the API call:

POST https://api.interakt.ai/v1/public/track/events/
{

          “userId”: “0123abc45d”,
          “event”: “OrderPlaced”,
          “traits”: {
                   “orderCreatedBy”: “Gavin Roberts”,
                   “orderCreatedDate”: “2020-11-01T012:10:26.122Z”,
                   “orderNumber”: “CUS001”,
                   “orderValue”: “50.00”
        }
}

The above API call triggers an OrderPlaced event when your user makes an order on your website/app. The API call passes the event properties orderCreatedBy, orderCreatedDate, orderNumber and orderValue to the API endpoint.

Please note: In case userId doesn't exist for a user, "phoneNumber" & "countryCode" would need to be specified in the above Event Track API Call.

Event Property Type Status Description
userId String Optional Unique identifier for the user.
event String Optional The action that the user has performed. It’s important to give meaningful names for your events. Example: OrderCreated, NewSignUp, OrderExecuted, etc.
traits Object Optional Properties are additional bits of information corresponding to the user action that is performed. They provide detailed information about user actions.
createdAt Date Optional Timestamp of the event in ISO-8601 format date string. If you have not passed the “createdAt” property, we will automatically use the current utc server time as the value of “createdAt”

Where can you see the added Events in your interakt dashboard

The event details show up in the ‘Events’ card - this card is visible in 2 places: 

1. In the inbox chat with the particular user
2. In the user details section (upon clicking a user entry)


Moreover, you will now be able to filter your user list with these traits (the filter option is available in the Users page & in the Notifications page, when you create a New Campaign) - you can further find here different filter options, corresponding to data types of traits.

Setting Campaigns based on conditions on Event Properties

• Onetime: This campaign can be used for a one-time broadcast message that you want to send out to your users.

Suppose you have been sending the event named ‘Sign Up Completed’ with the event trait ‘Sign Up Date’ via our APIs for all users who sign up on your website/app:

- Use case: Suppose you want to send a broadcast message to all users who have signed up on your website/app in the past, i.e. for whom the event named ‘Sign Up Completed’ has been received in the past with the event trait ‘Sign Up Date’ having had any value.

- To do this, you would need to set up a ‘one time’ campaign and select the filter condition: Sign Up Completed Sign Up Date has any value. In the below example, the number of users qualifying this criteria as on date is 318.

- Once you set the campaign live from the Campaign Creation page, all those 318 users will be sent the notification on the scheduled date.

Click here to check out the detailed steps for setting a Campaign live.


• Ongoing: These are campaigns that are sent to users regularly based on certain trigger occurrences. 

- Use case: Suppose you want to send automatic notifications to a user immediately after he/she signs up on your website / app i.e. for whom the event named ‘Sign Up Completed’ will be received in the future with the event trait ‘Sign Up Date’ having any value.

- To do this, you would need to set an ongoing campaign with the filter condition Sign Up Completed Sign Up Date has any value.

When you do that, the existing 318 users won't be sent the notification. Instead, the notification will get sent:

As soon as the event 'Sign Up Completed' (with event property 'Sign Up Date' having any value) is received for a user via the Event API endpoint (
only those events will be considered which are received AFTER the ongoing campaign has been set up)

Click here to check out the detailed steps for setting a Campaign live.

(Note: Event properties can be of following types: string, number, boolean, datetime, list - the example above shows a specific condition that can be applied on an event property with ‘datetime’ type.)

Was this helpful? Yes No

Start your business growth with WhatsApp today!

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
Find Us On
interakt.ai is a Haptik product.
Haptik is a WhatsApp Business Solution Provider