Authenticate with User APIs

Overview

The Capacity concierge allows users on a web page to interact with the Capacity bot. The authenticated version of the Capacity concierge allows for individuals to interact with the Capacity bot as themselves, interacting with their user-specific data, such as their calendar, email, and other accounts.

Unauthenticated Concierge

The unauthenticated concierge with communicating with the Capacity bot as a non-specific user, and is useful for receiving general information and policies. When the concierge is unauthenticated, it will contain the text You for any inquiries you have typed, as opposed to your name.

Authenticated Concierge

The authenticated concierge will communicate with the Capacity bot as an authenticated user, and the concierge interface will display the user's first name.

Prerequisites

  1. Install Python 3 (https://www.python.org/download/releases/3.0/)
  2. Install pip (https://pypi.org/project/pip/)
  3. Install the requests library by running the following in a command prompt: pip install requests
  4. Each request will require an Authorization and x-capacity-id header. The Authorization header value contains the API Key also known as a  TOKEN, and X_CAPACITY_ID value
  5. JavaScript tag to deploy the concierge on your webpage

Step 1. Create a Group

We’ll start by creating a group. Users are associated with groups, and access to Capacity’s features is granted by assigning groups to directories.

import requests

HOST = 'https://api.capacity.com'
ENDPOINT = f'{HOST}/v1/groups'
TOKEN = '12345'
X_CAPACITY_ID = 'ABCD'

HEADERS = {'Authorization': f'Bearer {TOKEN}','x-capacity-id': X_CAPACITY_ID}
payload = {'name': 'Example Group'}

new_group = requests.post(ENDPOINT, data=payload, headers=HEADERS)\
    .json()\
    .get('result')

print(new_group)
# {'id': '41a2c817-9891-41df-8966-79621d252ad8', 'name': 'Example Group'}

Step 2. Create a User

  • Now that a group exists in the organization, the next step is to create a user assigned to that group.
import requests

HOST = 'https://api.capacity.com'
ENDPOINT = f'{HOST}/v1/users'
TOKEN = '12345'
X_CAPACITY_ID = 'ABCD'
HEADERS = {'Authorization': f'Bearer {TOKEN}','x-capacity-id': X_CAPACITY_ID}

# Using the group id returned from the previous step
payload = { "email": "capacity_user@yourcompany.com", "first_name": "Example1", "last_name": "User", "custom1": "test string 1", "custom2": "test string 2",
    "groups":['41a2c817-9891-41df-8966-79621d252ad8']}

new_user = requests.post(ENDPOINT, data=payload, headers=HEADERS)\
    .json()\
    .get('result')

print(new_user)
# {'custom1': 'test string 1','custom2': 'test string 2','email': 'capacity_user@yourcompany.com','first_name': 'Example1','groups': [{'id': '41a2c817-9891-41df-8966-79621d252ad8','name': 'Example Group'}],'id': '13d33302-dc9e-4a98-93c1-ef14c9590d51','last_name': 'User'}

Step 3. Create a Directory

  • Next, you'll need to create a container “directory” in which you'll store knowledge “exchanges” for your organization.
import requests

HOST = 'https://api.capacity.com'
ENDPOINT = f'{HOST}/v1/directories'
TOKEN = '12345'
X_CAPACITY_ID = 'ABCD'

HEADERS = {'Authorization': f'Bearer {TOKEN}','x-capacity-id': X_CAPACITY_ID}

payload = { 'name': 'Sample Exchange Directory'}

new_directory = requests.post(ENDPOINT, data=payload, headers=HEADERS)\
    .json()\
    .get('result')

print(new_directory)
# {'id': 'e9a59f1f-d91c-4c76-84ef-8885243ec06e','name': 'Sample Exchange Directory'}

Step 4. Add an Exchange to a Directory

  • Now you will create your first exchange in that directory
import requests

HOST = 'https://api.capacity.com'
ENDPOINT = f'{HOST}/v1/exchanges'
TOKEN = '12345'
X_CAPACITY_ID = 'ABCD'
HEADERS = {'Authorization': f'Bearer {TOKEN}','x-capacity-id': X_CAPACITY_ID}

# Using the directory id returned from the previous step
payload = { 'directory_id': 'e9a59f1f-d91c-4c76-84ef-8885243ec06e', 'inputs': ['Where is the corporate summit?', 'corporate summit location'], 'outputs': ['The corporate summit is in St. Louis.', 'The corporate summit will be in St. Louis this year.']}

new_exchange = requests.post(ENDPOINT, data=payload, headers=HEADERS)\
    .json()\
    .get('result')

print(new_exchange)
# {'directory_id': 'e9a59f1f-d91c-4c76-84ef-8885243ec06e','id': '6171f1cd-bd7b-4c79-acbe-5b1ae0e42c94','inputs': [{'id': 'c2755a12-400f-49a7-960f-92ffc3669f6d','input': 'Where is the corporate summit?'},{'id': '3b96a4e8-89d3-4715-8c22-4377c396da50','input': 'corporate summit location'}],'outputs': [{'id': 'bbeb3159-f356-4567-ab51-4f07417f7d3c',    'output': 'The corporate summit is in St. Louis.'},{'id': '9a3b9e05-ee9d-4607-aaf4-e9922e240d2f','output': 'The corporate summit will be in St. Louis this year.'}]}

Step 5. Enable Group Access to the Directory

  • Give your user group access to the directory so that the user can interact with the knowledge stored in it.
import requests

HOST = 'https://api.capacity.com'

# Using the group id returned from Step 1
GROUP_ID = '41a2c817-9891-41df-8966-79621d252ad8'
ENDPOINT = f'{HOST}/v1/groups/{GROUP_ID}/directories'
TOKEN = '12345'
X_CAPACITY_ID = 'ABCD'

HEADERS = {'Authorization': f'Bearer {TOKEN}','x-capacity-id': X_CAPACITY_ID}

# Using the directory id returned from Step 3
payload = { 'directory_id': 'e9a59f1f-d91c-4c76-84ef-8885243ec06e'}

enabled_directory = requests.post(ENDPOINT, data=payload, headers=HEADERS)\
    .json()\
    .get('result')

print(enabled_directory)
# {'id': 'e9a59f1f-d91c-4c76-84ef-8885243ec06e','name': 'Sample Exchange Directory'}

Step 6. Enable the Concierge Interface for the User

  • Allow the user to interact with the Capacity bot through the authenticated concierge interface
import requests

HOST = 'https://api.capacity.com'
INTERFACE = 'concierge'

#Using the user id returned from Step 2
USER_ID = '13d33302-dc9e-4a98-93c1-ef14c9590d51'

ENDPOINT = f'{HOST}/v1/users/{USER_ID}'
TOKEN = '12345'
X_CAPACITY_ID = 'ABCD'

HEADERS = {'Authorization': f'Bearer {TOKEN}','x-capacity-id': X_CAPACITY_ID}

#enable interface
requests.post(f'{ENDPOINT}/interfaces/{INTERFACE}', data={}, headers=HEADERS)\
    .json()\
    .get('result')

#interface should now be connected
enabled_concierge = requests.get(f'{ENDPOINT}/interfaces', headers=HEADERS)\
    .json()\
    .get('result')

print(enabled_concierge)
#{'concierge': {'connected': True}}
  • Deploying the concierge into a custom web page
<html lang="en"> <head> <title>Testtitle> head> <body> <h1> Example Concierge h1> <div id="ais-concierge">div> <script src="https://cdn.aisoftware.com/concierge/index.js" id="ais-concierge-script" concierge-token="concierge_token"> script> body> html>

The authenticated concierge functions as an internal-facing concierge for organizations and allows personalized responses for users.

The customer's application which is embedding the concierge is responsible for fetching the user_token associated with the user, and inserting its value in a user-token HTML attribute in the concierge script tag before the web page loads.

Concierge authentication occurs when the page containing the concierge is loaded. The request/page load must be finished before the user-token expires (120 seconds).

Note: To have Capacity create an authenticated concierge for your organization, please contact us at support@capacity.com.

JS Script:

Here is the script format that you'll use.  Be sure to replace TOKEN HERE with your concierge token, while retaining the surrounding quotes.  Contact support@capacity.com if you need help finding your token.

<div id="ais-concierge"></div><script src="https://cdn.aisoftware.com/concierge/index.js" id="ais-concierge-script" concierge-token=“TOKEN HERE”></script>

Here is an example of an authenticated concierge below; the user’s name “Example1” is shown rather than “You”.


Was this article helpful?