Authentication API
Developers can integrate their enduser authentication methods with the Proto AICX platform.
In order to integrate your web app's enduser authentication methods into the Proto AICX platform, you must add your enduser profiles to the Humans module. There are two ways to do this:
- Create humans manually.
- Create humans via Proto's Authentication API.
Create or edit humans
All of Proto's RESTful APIs calls must be authenticated. Instead of passing the full credentials on every REST API call, Proto uses a personal access token. The Proto AICX platform users can find their personal access token in the profile page.
Best practice
Use an Admin account that is not linked to any user's personal email address to avoid lock-out when the user is no longer employed by the company.
Create Human API
- You can use the Create Human API within your enduser creation or registration function
- This will link your web app endusers via Proto's Webchat
POST Endpoint:
https://api.proto.cx/gateway/<COMPANY_ID>/<BOT_ID>/crm/human
Path Variables | Description |
---|---|
COMPANY_ID | ID of the Company that can be found on the company icon at the bottom left of the screen. Select General Settings. |
BOT_ID | ID of the Bot that can be found in BUILD > SETTINGS > API page. |
Request Headers
Key | Value | Description |
---|---|---|
X-SINITIC-TOKEN | <PERSONAL_ACCESS_TOKEN> | Proto's platform user's personal access token that can be found on the Profile page. |
Request Body
Parameter | Required | Data Type | Parameter | Data Type | Description |
---|---|---|---|---|---|
fullname | true | string | End user's fullname | ||
email | false | string | End user's email address | ||
uid | false | string | Unique ID set for the end user that will be use in Webchat snippet to identify the user | ||
phone_number | false | string | End user's phone number | ||
profile_pic_id | false | string | End user's profile picture ID | ||
access_token | false | string | End user's access token | ||
tags | false | list | id | string | End user's list of tags ID. Can be found on Human > Settings page |
value | string | The value of the tag given to the human |
Sample Request
curl --location 'https://api.proto.cx/gateway/<COMPANY_ID>/<BOT_ID>/crm/human' \
--header 'Content-type: application/json' \
--header 'X-SINITIC-TOKEN: <PERSONAL_ACCESS_TOKEN>' \
--data-raw '{
"email": "[email protected]",
"fullname": "Test",
"phone_number": "+6123589032",
"tags": [
{
"id": "05cf87dd-c900-0008-e76f-3e1bc75b66e5",
"value": "Merchant"
}
]
}'
Sample Response
If the request is successful, you will receive a human id
from the response result.
{
"result": {
"id": "eu_KM8dKoKB5HJN"
}
}
Get Human API
- You can use the Get Human API on your web app to retrieve a human profile
GET Endpoint:
https://api.proto.cx/gateway/<COMPANY_ID>/<BOT_ID>/crm/human/<human_id>
Path Variable | Description |
---|---|
<human_id> | Human id receive from the Create Human API response. |
Sample Request
curl 'https://api.proto.cx/gateway/<COMPANY_ID>/<BOT_ID>/crm/human/eu_KM8dKoKB5HJN' \
-H 'X-SINITIC-TOKEN: <PERSONAL_ACCESS_TOKEN>'
Sample Response
{
"result": {
"access_token": null,
"created_at": "2020-10-19T03:33:30.207384+00:00",
"email": "[email protected]",
"fullname": "Test 1",
"human_id": "eu_KM8dKoKB5HJN",
"id": "eu_KM8dKoKB5HJN",
"notes": null,
"phone_number": null,
"profile_pic_id": null,
"tags": null,
"uid": "f2067462-67d1-4688-b78f-68d563665756",
"updated_at": "2020-10-19T03:33:30.207384+00:00"
}
}
Update Human API
- You can use the Update Human API on your web app to update human profile information such as the human
access_token
, which will expired based on the web app login status
PUT Endpoint:
https://api.proto.cx/gateway/<COMPANY_ID>/<BOT_ID>/crm/human/<human_id>
Request Body
Parameter | Required | Data Type |
---|---|---|
fullname | false | string |
email | false | string |
uid | false | string |
phone_number | false | string |
profile_pic_id | false | string |
access_token | false | string |
Sample Request
curl -X PUT 'https://api.proto.cx/gateway/<COMPANY_ID>/<BOT_ID>/crm/human/<human_id>' \
-H 'X-SINITIC-TOKEN: <PERSONAL_ACCESS_TOKEN>' \
--data-raw '{"uid": "very-special-unique-id"}'
Sample Response
{
"result": {
"id": "eu_KM8dKoKB5HJN"
}
}
Provide Human UID to Proto Webchat
There are two ways to tell the chatbot which web app enduser is using the chatbot:
- Setting the
humanUid
in theProto.init(options={}, callback=null)
- Use the
Proto.setHumanUid('uid')
on your web app JavaScript function
<script type="text/javascript">
window.ProtoSettings = {
gwId: '<WEBCHAT-CHANNEL-ID>',
env: '',
humanUid: 'uid',
onLoad: function() { Proto.show(); }
};
var d=document,s=d.createElement("script");
s.type="text/javascript",s.async=true,s.src="https://app.proto.cx/webchat/client.js";
var t=d.getElementsByTagName("script")[0];
t.parentNode.insertBefore(s,t);
s.addEventListener("load", function() {
var p = window.ProtoSettings; Proto.init(p, p.onLoad);
});
</script>
Note
The
uid
is the Unique ID you set for the enduser in Create Human API or Update Human API.
Updated 5 months ago