Table of Contents

Authenticated Concierge Overview

James Cain Updated by James Cain

You are able to use the Capacity Platform API to work with users, groups, directories, exchanges, and interfaces on the Capacity platform.



Commonly Used Concepts

Before we begin, let's review some commonly used concepts that will be referenced throughout this tutorial.

Concierge (aka Web Concierge)

The bot instance which appears on a web page and allows users to interact with your knowledge base

User

A user is an account that has access to interact with Capacity

Group

A group is a collection of users. Access to Capacity’s features is granted by assigning groups to directories. Note: a web concierge is also associated with a group, but a separate group from your user group.

Directory

A container used to organize and control access to content in Capacity.

Inquiry

A statement or question submitted to Capacity

For example: “24 month CD rates?” and “What are the current 24 month CD rates?” are inquiries.

Exchange

A combination of an inquiry to Capacity and Capacity’s response

Interface

An interface is any application that allows a user to communicate with Capacity. By default Capacity connects to some of the most popular chat applications such as Slack, Microsoft Teams, etc.

Variant

Inquiry Variant: Various methods of wording the same statement or question; such as “CD rate?” and “What are the current CD rates?”

A user can query Capacity with any of an exchange’s inputs, and Capacity will interpret them in the same way

Output Variant: Various methods of responding to a statement or question; such as “The current 24-month CD rate is 2.5%.” and “2.5% is the 24-month CD rate”

Response variants are stored as an exchange’s outputs. When Capacity recognizes a user’s inquiry and maps it to an exchange, Capacity picks an Output from that exchange and responds to the user.

Quickstart Guide

The full list of Capacity API endpoints are available at https://api.capacity.com/static/docs.html. You will need to obtain and use two required values in order to use the Capacity Platform API:

  • TOKEN is the API Key which provides you authenticated access to the API
  • X_CAPACITY_ID is a unique value which identifies requests as being for your organization

This section walks through the end-to-end process of creating a group, a user, a directory, and exchange. We’ll associate the user to a group and enable group access on a directory. We’ll complete the tutorial by viewing the concierge within the Copilot Console and deploying a concierge on a simple webpage to interact with Capacity. To deploy the web concierge, outside of the Copilot Console, a concierge token is required. Please contact support@capacity.com for a concierge token and JavaScript snippet.



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 are 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",
"groups":['41a2c817-9891-41df-8966-79621d252ad8']}

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

print(new_user)
# {'custom1': None,'custom2': None,'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.staging.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

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

Interacting with the newly created exchanges

There are many interfaces available to interact with the Capacity platform. The following section covers interacting with the default Copilot Web Concierge and deploying the concierge on a simple webpage.

Unauthenticated Concierge

Contains the text “You” for messages entered by unauthenticated users.

Authenticated Concierge

Will be personalized and display all authenticated user's first name. The Web Concierge is available within the Copilot Console by default.

Interacting with the default Console Concierge. The example below demonstrates submitting inquiries to the concierge based on the exchanges created in “Step 4. Add an Exchange to a Directory”

  • Deploying the concierge into a custom web page
<!doctype html>
<html lang="en">
<head>
<title>Test</title>
</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 code above will generate a page similar to the page below.

There is also an authenticated concierge which is deployed the same way as the standard concierge. 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 including the concierge script tag with the user-token populated field before the web page loads. Concierge authentication occurs when the page hosting the concierge is loaded. The request/page load must be finished before the user-token expires. The user-token expires after 120 seconds.

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

JS Script:

<script src="https://cdn.aisoftware.com/concierge/index.js" id="ais-concierge-script" concierge-token="concierge_token" user-token="user_token"></script>

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

How did we do?

Contact