NewsPricingSystem StatusBook DemoFree Trial

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:

  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

Path VariablesDescription
COMPANY_IDID of the Company that can be found on the company icon at the bottom left of the screen. Select General Settings.
BOT_IDID of the Bot that can be found in BUILD > SETTINGS > API page.

Request Headers

KeyValueDescription
X-SINITIC-TOKEN<PERSONAL_ACCESS_TOKEN>Proto's platform user's personal access token that can be found on the Profile page.

Request Body

ParameterRequiredData TypeParameterData TypeDescription
fullnametruestringEnd user's fullname
emailfalsestringEnd user's email address
uidfalsestringUnique ID set for the end user that will be use in Webchat snippet to identify the user
phone_numberfalsestringEnd user's phone number
profile_pic_idfalsestringEnd user's profile picture ID
access_tokenfalsestringEnd user's access token
tagsfalselistidstringEnd user's list of tags ID. Can be found on Human > Settings page
valuestringThe 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 VariableDescription
<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

ParameterRequiredData Type
fullnamefalsestring
emailfalsestring
uidfalsestring
phone_numberfalsestring
profile_pic_idfalsestring
access_tokenfalsestring

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"
  }
}

Add / Update Human Tags API

You can use the Add / Update Human Tags API on your web app to update the tags on their profile.

POST Endpoint:
https://api.proto.cx/gateway/<COMPANY_ID>/<BOT_ID>/crm/assign_tags

Request Body

ParameterRequiredData TypeParameterRequiredData TypeDescription
human_idstruelistHuman id (s) receive from the Create Human API response.
tagstruelistidtruestringTag ID. Can be found on Human > Settings page
valuetruestringThe value of the tag given to the human

Sample Request

curl POST --location 'https://api.proto.cx/gateway/<COMPANY_ID>/<BOT_ID>/crm/assign_tags' \
--header 'X-SINITIC-TOKEN: <PERSONAL_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "human_ids": [
        "eu_KM8dKoKB5HJN"
    ],
    "tags": [
        {
            "id": "05e71a58-fc00-00b8-e298-13af516240451",
            "value": "Agree"
        }
    ]
}'

Sample Response

{
  "success": True
}

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.

Updated 5 months ago

What’s Next