What is Interakt’s Track APIs?
Here are the reference docs for connecting to our APIs. Check out our Postman Collection & Python SDK.
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.
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 have a rate limit of 40 requests per minute. For all requests after the 40th request (in that minute), the API will throw an error and thereby, ignore the request.
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 user track 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”: “[email protected]”,
“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.
<table>
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”
}
}
You can now add tags on your customers in Interakt via APIs.
Simply include a key for “tags” in the User Track API call.
Sample Payload:
{
“phoneNumber”: “9967536783”,
“countryCode”: “+91”,
“traits”: {
“name”: “Gavin Roberts”,
“email”: “[email protected]”
},
“tags”: [“new customer”, “potential lead”]
}
• You can add multiple tags.
• You can only add new tags. You cannot delete existing tags.
• Addition of tags is case insensitive i.e. if you add a tag ‘new customer’ on Customer A & a tag ‘New Customer’ already exists on Customer A, no new tag will be added on Customer A.
How is this useful specifically for clients having long user lists which don’t get filtered by custom user traits?
• If a client wants to filter his user list to send out a onetime campaign, he faces issues if he is filtering using a custom trait.
• Suppose the custom trait he is using is ‘City’ and the filter condition is ‘City’ = ‘Kolkata’
• Now instead of adding a custom trait for ‘City = Kolkata’ he can add a tag ‘Kolkata’ for the user
• Then he can filter the user list by this tag and send the campaigns
Important disclaimer: It is recommended for users not to add more than 50 tags for a customer
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: Learn More
What is Interakt’s 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.
<table>
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.
Using the APIs, trigger an Ongoing Campaign on Interakt
Learn More
Contacts Retrieval API
Postman Collection for this API.
Whenever you get a new lead on WhatsApp via Interakt, you can now make sure that details of that lead are passed on to your other CRMs / databases by using the Contacts Retrieval API. Simply add the API calls to your system’s code, or, use these API calls in connector platforms (like Integromat / Zapier) to sync Interakt with your SaaS based CRMs.
Authentication: Authentication mechanism uses HTTP Basic Auth which requires you to send your API key prepended with the ‘Basic’ string. 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.
Query Parameters: There are 2 query parameters which can be included in the URL on which the API is to be called: https://api.interakt.ai/v1/public/apis/users/?offset=0&limit=100
Limit: Default value is 100. If the API response contains more than 100 contacts, then the field ‘has_next_page’ in the API response will be true and the API would then have to be called again, keeping offset as 100.
Offset: Default value is 0.
Errors: Our API endpoint will return 200 status code for all successful requests. 4xx errors will be shown for the following cases:
• If the authorization credentials have been entered incorrectly.
• If the query parameter ‘limit’ has been set as > 100
• If ‘val’ of ‘created_at_utc’ or ‘modified_at_utc’ is not in UTC format in the API payload
• If the properties ‘op’ or ‘supr_op’ have not been entered correctly
5xx errors will be shown in case of some internal errors.
How to call the API:
For retrieving contacts which have been created on Interakt after 5 pm (IST) on 8-Sep-2021 , the following payload could be sent in the API call.
POST https://api.interakt.ai/v1/public/apis/users/?offset=0&limit=100
{
“filters”: [
{
“trait”: “created_at_utc”,
“op”: “gt”,
“val”: “2021-09-08T11:30:00.000Z”
}
]
}
For retrieving contacts which have been created on Interakt before 5 pm (IST) on 8-Sep-2021 , the following payload could be sent in the API call.
POST https://api.interakt.ai/v1/public/apis/users/?offset=0&limit=100
{
“filters”: [
{
“trait”: “created_at_utc”,
“op”: “lt”,
“val”: “2021-09-08T11:30:00.000Z”
}
]
}
For retrieving contacts which have been created on Interakt after 5 pm (IST) on 7-Sep-2021 and before 5 pm (IST) on 8-Sep-2021 , the following payload could be sent in the API call.
POST https://api.interakt.ai/v1/public/apis/users/?offset=0&limit=100
{
“filters”: [
{
“trait”: “created_at_utc”,
“op”: “gt”,
“val”: “2021-09-07T11:30:00.0000”
},
{
“trait”: “created_at_utc”,
“op”: “lt”,
“supr_op”: “and”,
“val”: “2021-09-08T11:30:00.0000”
}
]
}
For retrieving contacts which have been modified on Interakt after 5 pm (IST) on 8-Sep-2021 , the following payload could be sent in the API call.
POST https://api.interakt.ai/v1/public/apis/users/?offset=0&limit=100
{
“filters”: [
{
“trait”: “modified_at_utc”,
“op”: “gt”,
“val”: “2021-09-08T11:30:00.000Z”
}
]
}
Note: Always send the datetime value in UTC format. If only date has been sent without time (example: 2021-09-08), the time will be assumed to be 00:00 hours.
<table>
