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:

1. Create humans manually.
2. 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

Request Headers

Request Body

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>

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

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:

1. Setting the humanUid in the Proto.init(options={}, callback=null)
2. 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.