Authentication API

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 the Proto.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.