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.

  1. 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 in

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

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

tag_ids

false

list

End user's list of tags

Sample Request

curl -X POST 'https://api.proto.cx/gateway/<COMPANY_ID>/<BOT_ID>/crm/human' \
  -H 'X-SINITIC-TOKEN: <PERSONAL_ACCESS_TOKEN>' \
  --data-raw ''{"email":" [email protected] ","fullname":"Test 1", "uid": "f2067462-67d1-4688-b78f-68d563665756", "phone_number":"", "access_token":""}'

Sample Response
If the request is successful, you will receive an human id from the response result.

{
  "result": {
    "id": "eu_KM8dKoKB5HJN"
  }
}

📘

Note

Please store the response result human id on your web app database. The human id will be used to retrieve the human profile in the Get Human API and Update Human API.

  1. 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"
  }
}
  1. 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:

  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" src="https://app.proto.cx/webchat/client.js"></script>
<script>
  Proto.init(
    {
      gwId: '<WEBCHAT-CHANNEL-ID>',
      env: '',
      humanUid: 'uid'
    },
    function() {
      Proto.show();
    }
  );

  // You can tell the bot the Human has changed.
  Proto.setHumanUid('anothervery-special-unique-id')
</script>

📘

Note

The uid is the Unique ID you set for the enduser in Create Human API or Update Human API.