The notification API allows you to retrieve all the queued notifications for a particular user. Please note that all notifications for this user are deleted after this API is called
All requests need to be authenticated as documented in our authenticate guide
{
"data": [
{
"type": "checkin",
"schedule": "string ex. 2023-06-30 19:26:36.566729+00:00",
"thread_name": "string"
}
]
} status code: 200
{
"data": [
{
"type": "autoping",
"schedule": "string ex. 2023-06-30 19:26:36.566729+00:00",
"thread_name": "string"
}
]
} status code: 200
{ "message": "No notification scheduled for person : person_id" } status code: 400
{ "message": "Person is not registered to : client_name" } status code: 404
{ "message": "Unknown person with id : client_name" } status code: 404
note: This API call deletes the scheduled notifications so please make sure to save them if a follow up to the person is necessary
In addition to our standard SMS and Facebook Messenger interfaces, Cass supports custom third party integrations via an embedded web page or popup.
Cass provides two different kinds of user interfaces for you to choose from:
If your people use the Cass bot anonymously, then you simply add our code snippet to your web page. Please reach out to your Cass Implementation Specialist to get the code.
If you want to know who is chatting with the Cass bot, then you must use our External Person API, which is detailed below. This API will return a unique ID, which you can add to the HTML code that your Implementation Specialist provides, to identify the person chatting. Using an API like this requires engineering resources, so please forward this document to your IT/Engineering team accordingly.
By default, the Cass web embed and popup interact with people anonymously, in order to protect peoples’ privacy. However, there are cases where you want to know the identity of the person, so we provide an optional External Person API for that purpose.
Standard web embed and popup parameters:
Cass' External Person API is used to map a person to a unique Cass Person ID. You can then use that Person ID in the Embed or Popup to identify them when they’re chatting with the Cass bot. You can call this API with an HTTP GET, POST, or PATCH.
When you call the External Person API for a specific person it will return that person’s Cass Person ID, which you then add to HTML code provided by the Cass team.
For example, if the Cass Implementation Specialist provided you with this line of HTML:
https://web-health.x2.ai/embed/1/company?auth_code=inKAWLKr85748GFYdrt0&name=Tess&color=228fb1&avatar=https://www.myfreetaxes.org/chat/images/userpic.png&intro=Welcome.I%20would%20love%20to%20get%20to%20know%20you%20more,?%27&threadId=
And if your call to the Cass External Person API returned an Cass Person ID of 10f5ddba-c63d-46aa-898a-ec478ba38f24 for Jane Doe, then the full URL for Jane Doe to chat with the Cass bot is as follows:
https://web-health.x2.ai/embed/1/company?auth_code=inKAWLKr85748GFYdrt0&name=Tess&color=228fb1&avatar=https://www.myfreetaxes.org/chat/images/userpic.png&intro=Welcome.I%20would%20love%20to%20get%20to%20know%20you%20more,&threadId=&personId=10f5ddba-c63d-46aa-898a-ec478ba38f24
All API endpoints below unless noted are authenticated using Basic Authentication by setting the HTTP Authorization header for all requests:
Authorization: Basic <client:token>
The client and token will be provided to you by your Implementation Specialist. Only HTTPS requests are supported.
note: legacy (v1) endpoints require a client and token to be sent as url parameters
After your people have begun using the Cass bot, you may want to create or update them through our API. This can be achieved by using Cass' External Person API.
{
"first_name": "Person’s first name, used by the bot when chatting to them (optional)",
"last_name": "Person’s last name, (optional)",
"initial_thread_name": "Cass Thread to begin chat with bot* (optional)",
"external_id": "The ID of this person in your company’s system (required if phone parameter is not used, otherwise optional)",
"external_username": "Person’s Username in your company (optional)",
"external_org": "Person’s Organization in your company (optional)",
"external_data_1": "Any additional information you want to pass through (optional)",
"external_data_2": "Any additional information you want to pass through (optional)",
"phone": "Person’s phone number including country code, used for SMS communication (required if protocol is sms or WHATSAPP otherwise optional)",
"ping": "Set to 1 if you want to use initial_thread_name* (optional)",
"protocol": "default is ‘sms’ if protocol is not specified, and other options are 'sandbox', 'facebook', 'WHATSAPP', and 'web' (case sensitive) (optional)",
"timezone": "(optional)"
}
note: If initial_thread_name and ping parameters are not set, then a new person will be created by the API call, but they will not receive a message.
{
"existing_person": "boolean",
"person_id": "string",
"external_id": "string",
"phone": "string",
"message": "Existing person found" or "New person created"
}
The bot will automatically reflect the person’s first name when chatting with the bot. Additionally, you can also reflect the following fields via placeholders in the Cass content:
Add External Person API Field Name
Bot Content Placeholder
Thread (internal use)
external_id
<<EXTERNAL_ID>>
STORE_EXT_ID
external_username
<<EXTERNAL_USERNAME>>
STORE_EXT_UN
external_org
<<EXTERNAL_ORG>>
STORE_EXT_ORG
external_data_1
<<ED1>>
external_data_2
<<ED2>>
external_data_3
<<ED3>>
{
"person_id": "string",
"phone": "string",
"external_id": "string",
"external_username": "string",
"external_org": "string",
"external_data_1": "string",
"external_data_2": "string",
"external_data_3": "string",
"first_name": "string",
"last_name": "string",
"protocol": "string",
"language_type": "string",
"gender": "string",
"timezone": "string"
}
{
"external_id": "string",
"first_name": "string",
"last_name": "string",
"external_username": "string",
"external_org": "string",
"phone": "string",
"external_data_1": "string",
"external_data_2": "string",
"external_data_3": "string"
}
Only person_id is mandatory. The rest are optional details about an existing person to update. Client and auth can be passed as URL parameters or set in the HTTP header.
The external_id is expected to be unique and immutable similar to the person_id we generate on our end, it acts as a reliable link between the two systems if data need to be reconciled, thus the external_id field cannot be updated.
{ "message": "No client parameter specified" } status code: 400
{ "message": "Client Not Found" } status code: 404
{ "message": "Unauthorized" } status code: 401
{ "message": "Unknown person with id : {person_id}" } status code: 404
{ "message": "Person is not registered to {client_name}" } status code: 404
{ "message": "External_id already exist" } status code: 400
{ "message": "Invalid phone number {phone}" } status code: 400
{ "data": { "person_id": "{person_id}" } } status code: 200
This is a deprecated API and you should use "/external_person" instead
When calling the Add External Person API, you must specify the following:
Additionally, you can also specify the following optional fields:
{
"first_name": "Person’s first name, used by the bot when chatting to them",
"last_name": "Person’s last name",
"initial_thread_name": "Cass Thread to begin chat with bot*",
"external_id": "The ID of this person in your company’s system",
"external_username": "Person’s Username in your company",
"external_org": "Person’s Organization in your company",
"external_data_1": "Any additional information you want to pass through",
"external_data_2": "Any additional information you want to pass through",
"external_data_3": "Any additional information you want to pass through",
"phone": "Person’s phone number including country code, used for SMS communication",
"ping": "Set to 1 if you want to use initial_thread_name*",
"protocol": "default is ‘sms’ if protocol is not specified, and other options are 'sandbox', 'facebook', 'WHATSAPP', and 'web' (case sensitive)",
"New_id": "default if the param is not passed it to return the old_id, if a 1 is sent to this param then the response message will return the new ID instead of the old ID which will become deprecated."
}
note: If initial_thread_name and ping parameters are not set, then a new person will be created by the API call, but they will not receive a message.
Missing phone number when protocol is sms
{ "phone": None, "message": "phone parameter is required" }, status_code=400
Incorrect auth code
{"auth": auth, "message": "Unauthorized" }, status_code=401
Incorrect thread name
{"thread_name": initial_thread_name, "message": "Thread name Not Found" }, status_code=400
Incorrect phone number
{"phone": phone, "message": "Invalid phone number" }, status_code=400
Note: If you call the Add External Person API with the phone number or external_id of an existing person, then it will simply return that person’s existing Cass Person ID and a 409 code. The ping functionality works regardless of whether or not the person was previously registered with Cass.
Existing person with external ID
{ "existing_person": true, "person_id": "string", "external_id": "string", "phone": "string", "message": "Existing person found already" }, status_code=409
Existing person
{ "existing_person": true, "person_id": "string", "external_id": "string", "phone": "string", "message": "Existing person found already" }, status_code=409
Created new person successfully
{ "existing_person": false, "person_id": "string", "external_id": "string", "phone": "string", "message": "New person created" }, status_code=200
After your people have begun using the Cass bot, you may want to send them to a specific thread in the conversation. This can be achieved by using Cass’ Ping Person API. The v2 Ping Person API additionally allows the use of client-defined string placeholders in the message to be pinged.
In order to send someone to a particular thread, we need to know who that person is, so you need to call the External Person API (see above) before calling the Ping Person API, for anyone that you want to manage.
When calling the Ping Person API, you must specify the following url parameters:
The required parameters for the v2 endpoint are the same as those listed above, and additionally, you may use the following parameter:
Example use of placeholders:
{
"messages": [ “<<NAME>> you have an appointment due with a <<APPOINTMENT>> on <<DATE>>" ],
"thread_name": string,
"next_thread_name": string,
"person_id": "",
"is_asynch": false,
"is_auto_next": false,
"placeholders": {
"name": "John",
"appointment": "Doctor",
"date":"June 9th"
}
}
{
"message": "Successfully pinged person",
"person_id": "string",
"thread_name": "string",
"next_thread_name": "string"
}
Here’s an example call with personId of 1234 and thread of good_thread
A private Metabase login allows you to access your bot’s data in Metabase, pull basic queries, and write SQL queries. You are also able to pull from Metabase using the Metabase API to display charts directly in your app.
With Metabase database access, you get access to both the Person Table & Transcript Table, which include the following data columns.
Person Table includes:
Transcript Table includes:
Previously, Cass provided a registration endpoint for third party integrations. That third party integration is being replaced by this new one.
Migrating from the legacy registration endpoint to this new Third Party Integration consists of the following changes:
Here is the new URL endpoint for Cass' Add External Person API:
Field names that changed:
Fields that have been dropped:
Previously, Cass provided a person ID which consisted of an integer (e.g. 1943). This ID has now been replaced by a UUID (e.g. 10f5ddba-c63d-46aa-898a-ec478ba38f24 ). In order to assist in this transition a new method /get_new_id will be temporarily available. This method is to be used by clients to update their records in case they keep a copy of our person ID.
Migrating from the legacy person ID consists of the following changes:
For an Initial period of time all of the API functions (/ping_person, /add_external_person, and the PATCH function /external_person/<person_id> ) will provide backwards compatibility with the old ID.
Here is the new URL endpoint for Cass' Get New ID API:
When calling the Get New ID API, you must specify the following:
Once you’ve made the changes above, your API call should look like this: