KAI API Guide & Info

Add new lead

JSON setup

URL : https://ultranoah.com/kai/new_leads.php
Method : POST
Return : flat JSON of {“status”:”<status>”,”message”:”<status message>”}

Status & Message :
– success = New lead has been successfully added to the system
– message = Lead Added
– alert = Duplicated lead, no new lead added
– message = Duplicated lead, Frequency increased
– error = Duplicated lead detected, increased the lead frequency only
– message = Error Insert into DB | Error Insert into DB

7 Required Parameters :

api_key
Your API key. This will be given when you created an account with KAI. You can find your API key in the SETTING

leads_id
Is unique identifier of each user. Recommended to use User ID given by the chatbot platform as the leads_id. For example on Activechat is $_id

first_name
User facebook first name taken from the bot. For example on Activechat is $_fist_name

last_name
user Facebook last name taken from the bot. For example on Activechat is $_last_name

bot_name
The chatbot unique identifier. You can use the chatbot name you created or simply use the chatbot platform given chatbot ID. For example on Activechat is $_agentid. We recommend you to use the name you created for the chatbot for easy tracking. For example Jambul, Maya or Eva.

leads_channel
The name of your chatbot platform. If your chatbot is using Activechat then your leads_channel is set as activechat, if you are using Chatfuel, then your leads_channel is chatfuel

leads_campaign
The name of your marketing or sale or product or service. It can be anything you set from your campaign name to your Facebook Ads ref value. We recommend using a simple name for the campaign for easy tracking. For example, the leads_campaign value for a Buy 1 free 1 sale campaign is <product name> buy 1 free 1. You can also use your product or service name as your campaign name

The lead status of each new leads added to KAI using this API will be set as NEW. This is system generate status. you can change the status using the next API call

If the system detect a duplicated lead, it will not create another entry of the same lead, instead, it will increase the lead frequency to show how many time the lead return without ordering or closed

Update lead status

JSON setup

URL : https://ultranoah.com/kai/update_status.php
Method : POST
Return : Falt JSON of {“status”:”<status>”,”message”:”<status message>”}

Status & Message :
– success = Lead status has been updated
– message = Lead status <lead status>
– alert = Can’t update lead status to ordered or closed using this API call | Can’t update status lower than ordered or closed
– message = Please use new order or new payment API for ordered or closed status | Lead status remains as <lead status>
– error = Lead not found | User not found | DB error
– message = Lead not found | User not found | Error updating lead status, <db error message>

4 Required Parameters :

api_key
Your API key. This will be given when you created an account with KAI. You can find your API key in the SETTING

leads_id
Is unique identifier of each user. Recommended to use User ID given by the chatbot platform as the leads_id. For example on Activechat is $_id

leads_status
The status you want to set to your lead. Please read below available status and the usage guide (except ordered and closed)

new – Auto set by SYSTEM when you add new lead using the Add new lead API call. This status will show that the lead is new and just enter the system
qualified – Use this status to show that your lead is qualified or the kind of lead that you want to nurture and you think have a higher chances to convert into sales
follow up – Use this status for leads that is under the follow up flow or sequences
disqualified – Set this status to your leads that you think does not fit into your target or you think have the lowest chance for sales conversion
kiv – set a lead into this status so that you can re visit the lead when ever you want
ordered – System control ! Use the new order API call to set this status once your lead has placed an order
closed – System control ! This the status the we want the most. When lead a made a purchase or successfully made a payment for your products or services, use the new payment API call to set the status to closed showing that the lead has been converted into customer
removed – ALERT ! Only use this status to remove any lead from your data or list. Once the status has been set to removed, it will not be tracked and counted in the analytics. You will also lost access and view to the lead. It is as good as DELETE. Only use when you are very sure to DELETE the lead from you data / list

Optional Parameters :

fullname
Mostly used when you are getting the user full name (instead of their facebook first name and last name). Usually when the user make an order or payment or completing a survey

email
User email

phone
User phone number

address
User phone number

item
Product / service / package name that the user has ordered

quantity
How many in pcs or can also be in weight or volume. For example 1 (as 1 pcs) or 2.4 (as 2.4 kg). Please input numbers ONLY

amount
Total amount based on the product / service price x quantity ordered by the user. For example, your product price is 69.90 per pcs and your user has ordered 2 pcs of it, then your amount should be 139.80.

If your current lead status is ordered or closed, the system will reject any status update. So, rest assure that, once your lead status is ordered or closed, it will not be change back to other status using the API call. You can always change the status manually from the dashboard

Update Leads Type

This is not an API call. It’s an automatically set by the system AI. There are several condition involve and will keep on evolve with more data in the future. Below are the lead type and it explanation.

Lead Type :

cold
When your lead is added to the system, it will be set as cold lead. Any lead with this type is considered as top of the funnel lead

warm
This lead type is basically anything in between cold and hot. The system will set a lead to this type based on it’s status and few other conditions. For example, a leads that enter the same chatbot / campaign more than 2 time will be considered as this type

hot
When a leads make an order, the system will set the lead as hot. Any lead fall under this type, is a must follow up and % for sales conversion is high

customer
Lead will be set as this type once they complete payment for an order

Update Action

JSON setup

URL : https://ultranoah.com/kai/update_act.php
Method : POST
Return : flat JSON of {“status”:”<status message>”}
Status message :
– User not found = API key is invalid or wrong
– Lead act updated = Lead action has been successfully updated
– API key <various value> = API key is not active or expired or has other issue mentioned in <various value>

5 Required Parameters :

api_key
Your API key. This will be given when you created an account with KAI. You can find your API key in the SETTING

leads_id
Is unique identifier of each user. Recommended to use User ID given by the chatbot platform as the leads_id. For example on Activechat is $_id

last_btn_pressed
The name or label of the last button that user click or press. For example in Activechat, you can use the $_last_btn_press attributes to get the value

last_user_input
The last reply or text that user send / enter. For example in Activechat, you can use the $_last_user_input attributes to get the value

New Order

JSON setup

URL : https://ultranoah.com/kai/new_orders.php
Method : POST
Return : Falt JSON of {“status”:”<status>”,”message”:”<status message>”} if status = success will get orderID in return

Status & Message :
– success = Order has been successfully created or updated
– message = Lead Updated and Order Added | Lead and Order Updated | New Lead and Order Added | Direct Order Added
– error = User not found | DB error
– message = User not found | Error Insert into DB, <db error message>

10 Required Parameters :

api_key
Your API key. This will be given when you created an account with KAI. You can find your API key in the SETTING

leads_id
Is unique identifier of each user. Recommended to use User ID given by the chatbot platform as the leads_id. For example on Activechat is $_id

fullname
Mostly used when you are getting the user full name (instead of their facebook first name and last name). Usually when the user make an order or payment or completing a survey

email
User email

phone
User phone number

address
User phone number

item
Product / service / package name that the user has ordered

quantity
How many in pcs or can also be in weight or volume. For example 1 (as 1 pcs) or 2.4 (as 2.4 kg). Please input numbers ONLY

The API will only create a new order if, there are current leads with status of below order or closed. It will update the leads status to ordered. If there are no leads found, the system will create a new order tagged as direct order with no lead created. If the system found a duplicated order it will update the order using the given info in the JSON parameters

New Payment

JSON setup

URL : https://ultranoah.com/kai/new_payments.php
Method : POST
Return : Falt JSON of {“status”:”<status>”,”message”:”<status message>”}

Status & Message :
– success = Payment has been successfully added
– message = Payment added, customer created | Payment added, customer upgraded
– error = User or lead not found
– message = User not found | Leads not found

4 Required Parameters :

api_key
Your API key. This will be given when you created an account with KAI. You can find your API key in the SETTING

leads_id
Is unique identifier of each user. Recommended to use User ID given by the chatbot platform as the leads_id. For example on Activechat is $_id

method
How the user make the payment. You can use you own value. No system value is being used. For example, if the user pay using Stripe, then, your method should be ‘stripe’. Another example, if the user pay using bank transfer, then you method should be ‘bank transfer’

Optional Parameters :

invoice
Invoice number if available

receipt
Receipt number if available

The system will successfully add a payment if there are leads with ordered status and order with pending payment status. The system will also check for existing customer to upgrade the customer. For example, if a payment is made for an order by an existing customer, the system will upgrade the customer to the next level. If the are no existing customer found, the system will create a new customer.