API Docs
OVERVIEW
In addition to our standard SMS and Facebook Messenger interfaces, X2 supports custom third party integrations via an embedded web page or popup.
Goals
- User Interfaces: A web embed and a popup
- Ease of Use: You can embed our UI with a single line of code
- Identity: You can optionally identify people by using our Add External Person API
User Interfaces
X2 provides two different kinds of user interfaces, for you to choose from:
- A web page, which you embed in your smartphone application or on your website
- A popup, that you can integrate into pages on your website
Ease of Use
If your people are using the X2 bot anonymously, then you simply add one line of HTML to your web page. Please reach out to your X2 Health Team member to get your one liner.
Identity
If you want to know who is chatting with the X2 bot, then you must use our Add External Person API, which is detailed below. This API will return a unique ID, which you can add to the one liner that your Health Team member provides (see above), to identify the person chatting. Using an API like this requires engineering resources, so please forward this document to your IT/Engineering team, if you need to identify your people.
ADD EXTERNAL PERSON API
Background
By default, the X2 web embed and popup interact with people anonymously, in order to protect peoples’ privacy, etc.. However, there are cases where you want to know the identity of the person, so we provide an optional Add External Person API for that purpose.
Standard web embed and popup parameters:
- intro: A short intro text, e.g. "Hi! How can I help you?"
- avatar: A URL link to a custom avatar. If not provided we default to our X2 Tess avatar
- threadId: An Id to an initial thread selected from the threads selector (Not used often)
- is_rounded: Toggles the round corners; default is True
- color: A preferred color code in hex e.g for white FFFFFF without the #
- show_header: Toggles the embed chat header; default is True
Overview
X2’s Add External Person API is used to map a person to a unique X2 Person ID. You can then use that Person ID in the Embed or Popup to identify them when they’re chatting with the X2 bot. You can call this API with an HTTP GET or an HTTP POST.
Identifying the Person
When you call the Add External Person API for a specific person it will return that person’s X2 Person ID, which you then add to HTML one liner that the X2 Health Team provided.
For example, if the X2 Health Team provided you with this line of HTML:
https://web-x2.netlify.app/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 X2 Add External Person API returned an X2 Person ID of 10f5ddba-c63d-46aa-898a-ec478ba38f24 for Jane Doe, then the full blown URL for Jane Doe to chat with the X2 bot is as follows:
https://web-x2.netlify.app/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
API Call
Here's the Add External Person API endpoint:
https://prod.x2.ai:8888/add_external_person
When calling the Add External Person API, you must specify the following:
- client: The X2 name of your company (provided by X2 Health Team)
- auth: Authentication code for your company (provided by X2 Health Team)
- At least one of these unique IDs:
- phone: Person’s phone number including country code, used for SMS communication (e.g. 15551234567)
- external_id: The ID of this person in your company’s system; must be unique
- If the external_id parameter is used without the phone parameter, then the protocol parameter must be specified as ‘web’
HTTP Method: GET or POST
Content-Type: application/json
Person Parameters
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: X2 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: Can be used to store any additional information you want to pass through, e.g. email address, partner’s name, city, etc.
- external_data_2: Can be used to store any additional information you want to pass through, e.g. email address, partner’s name, city, etc.
- external_data_3: Can be used to store any additional information you want to pass through, e.g. email address, partner’s name, city, etc.
- 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.
* 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.
Response Payload
Missing phone number when protocol is sms
res={
'phone': None,
'message': "phone parameter is required"
},
status_code=400
Incorrect auth code
res={
'auth': auth,
'message': "Unauthorized"
},
status_code=401
Incorrect thread name
res={
'thread_name': initial_thread_name,
'message': "Thread name Not Found"
},
status_code=400
Incorrect phone number
res={
'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 X2 Person ID and a 409 code. The ping functionality works regardless of whether or not the person was previously registered with X2.
Existing person with external ID
res={
'existing_person': True,
'person_id': str(person.id_hash) if new_id else str(person.id),
'external_id': str(external_id),
'phone': str(person.phone_number),
'message': "Existing person found already"
},
status_code=409
Existing person
res={
'existing_person': True,
'person_id': str(person.id_hash) if new_id else str(person.id),
'external_id': str(external_id),
'phone': str(person.phone_number),
'message': "Existing person found already"
},
status_code=409
Created new person successfully
res={
'existing_person': False,
'person_id': str(person.id_hash) if new_id else str(person.id),
'external_id': str(external_id),
'phone': str(person.phone_number),
'message': "New person created"
},
status_code=200
HTTP Status Codes
- 200: Success
- 400: Invalid arguments
- 401: Invalid auth_code
- 404: Invalid Client or Thread ID
- 409: Person already exists
Using Person Info in Bot Content
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 X2 content:
Add External Person API Field NameBot Content PlaceholderThread (internal use)external_id<<EXTERNAL_ID>>STORE_EXT_IDexternal_username<<EXTERNAL_USERNAME>>STORE_EXT_UNexternal_org<<EXTERNAL_ORG>>
STORE_EXT_ORGexternal_data_1<<ED1>>
external_data_2<<ED2>>
external_data_3<<ED3>>
MIGRATING FROM LEGACY REGISTRATION
Background
Previously, X2AI provided a registration endpoint for third party integrations. That third party integration is being replaced by this new one.
Overview
Migrating from the legacy registration endpoint to this new Third Party Integration consists of the following changes:
- New endpoint URL
- Field name changes
- Fields dropped
Details
Here is the new URL endpoint for X2’s Add Add External Person API:
Field names that changed:
- externalid → externalId
- instance → client
- initial_state → initial_thread_name
Fields that have been dropped:
- Date_of_birth
MIGRATING FROM LEGACY PERSON ID
Background
Previously, X2AI 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.
Overview
Migrating from the legacy person ID consists of the following changes:
- Change ID from an Int to a string
- Update current ID to use the new UUID for each person
- Use the new UUID when making requests to endpoint URL
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.
- For /ping_person and /external_person/<person_id> you can keep using them as normal, they will accept both old and new ID.
- For the /add_external_person it will default return an old id unless a parm new_id with value 1 is passed to it. In this case it will return the new ID.
Details
Here is the new URL endpoint for X2’s Get New ID API:
When calling the Get New ID API, you must specify the following:
- client: The X2 name of your company (provided by X2 Health Team)
- auth: Authentication code for your company (provided by X2 Health Team)
- At least one of these unique IDs:
- old_id: Person’s old ID which has been used in the past. (e.g. 1284)
- If this parameter is used without the external_id parameter, then the protocol parameter defaults to use the external_id
- external_id: The ID of this person in your company’s system; must be unique
- If this parameter is used without the old_id parameter, then the protocol parameter defaults to use the external_id
Validation
Once you’ve made the changes above, your API call should look like this:
HTTP Status Codes
- 200: Success
- 400: Invalid arguments
- 401: Invalid auth_code
- 404: Invalid External_Id or Old_ID
GET PERSON API
Background
The client name and auth code are not passed as a param, but rather are encrypted and passed in the API request header as the value of Authorization.
REQUEST HEADER: Required Authentication Header Structure : Authorization=Basic base64Encode(username:password)
Example : Authorization=Basic HFKJOlFTVlo0VzZyu0E3eDU3MGRaejNz
Generates a base64Encode Using client name as the username and auth code as the password. A tool like this can be used to generate base64Encode code: https://www.blitter.se/utils/basic-authentication-header-generator/
API Call
Post Person API
Background
The client name and auth code are not passed as a param, but rather are encrypted and passed in the API request header as the value of Authorization.
REQUEST HEADER: Required Authentication Header Structure : Authorization=Basic base64Encode(username:password)
Example : Authorization=Basic HFKJOlFTVlo0VzZyu0E3eDU3MGRaejNz
Generates a base64Encode Using client name as the username and auth code as the password. A tool like this can be used to generate base64Encode code: https://www.blitter.se/utils/basic-authentication-header-generator/
API Call
Ping Person API
Background
After your people have begun using the X2 bot, you may want to send them to a specific thread in the conversation. This can be achieved by using X2’s Ping Person API. The v2 Ping Person API additionally allows the use of client-defined string placeholders in the message to be pinged.
Prerequisite
In order to send someone to a particular thread, we need to know who that person is, so you need to call the Add External Person API (see above) before calling the Ping Person API, for anyone that you want to manage.
API Call
Here’s the Ping Person API URL endpoint:
When calling the Ping Person API, you must specify the following parameters:
- client: The X2 name of your company (provided by X2 Health Team)
- auth: Authentication code for your company (provided by X2 Health Team)
- personId: Value returned by your call to Add External Person API
- thread: The name of the X2 Thread to begin chat with bot
v2 Ping Person API endpoint:
The required parameters for the v2 endpoint are the same as those listed above, and additionally, you may use the following parameter:
- placeholders: an object containing client-defined properties consisting of key-value pairs
HTTP Method: GET or POST
Content-Type: application/json
REQUEST HEADER:
Required Authentication Header Structure: Authorization=Basic base64Encode(username:password)
Example: Authorization=Basic HFKJOlFTVlo0VzZyu0E3eDU3MGRaejNz
Generates a base64Encode Using client name as the username and auth code as the password
Sample external tool to generate base64Encode code: https://www.blitter.se/utils/basic-authentication-header-generator/
REQUEST example use of placeholders:
{
"messages": [
“<<NAME>> you have an appointment due with a <<APPOINTMENT>> on <<DATE>>"
],
"thread_name": "",
"next_thread_name": "",
"person_id": "",
"is_asynch": false,
"is_auto_next": false,
"placeholders": {
"name": "John",
"appointment": "Doctor",
"date":"June 9th"
}
}
Response Payload:
{
"message": "Successfully pinged person",
"person_id": "",
"thread_name": "",
"next_thread_name": ""
}
HTTP Status Codes
HTTP STATUS: 200
- 200: Success
- 400: Invalid arguments
- 401: Invalid auth_code
- 404: Invalid Client or Thread ID
Example API Call
Here’s an example call with personId of 1234 and thread of good_thread
EXTERNAL PERSON API
Background
After your people have begun using the X2 bot, you may want to update their information in our system. This can be achieved by using X2’s External Person API.
Prerequisite
In order to update a person’s information, we need to know who that person is, so you need to call the Add External Person API (see above) before calling the External Person API, for anyone that you want to manage.
API Call
Here’s the External Person API URL endpoint:
https://prod.x2.ai:8888/external_person/{person_id}
HTTP Method: PATCH
Content-Type: application/json
Request Payload:
{
client: string,
auth: 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 client, auth, person_id are mandatory, and the rest are optional details about an existing person to update.
The external_id is expected to be unique and immutable similar to the person_id we generate on our end, it act as a reliable link between the two systems if data need to be reconciled, thus the external_id field cannot be updated.
Response Payload
{
'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
HTTP Status Codes
- 200: Success
- 400: Invalid arguments
- 401: Invalid auth_code
- 404: Invalid Client or Thread ID
Database API Access
Background
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.
Data Access
With Metabase database access, you get access to both the Person Table & Transcript Table, which include the following data columns.
Person Table includes:
- created_at date
- human_id
- protocol
- external_Id
- external_org
- external_username
- phone_number
- id_hash
Transcript Table includes:
- created_at
- human_id
- thread name
- string input (unexposed except for assessments (GAD, PHQ, WOS) to_ai & from_ai, crisis from_ai, and custom content)
- Protocol (SMS, web, or facebook)
- transcript_id
- Id_hash (hashed form of human_id)
Tess is our our mental health chatbot providing self-help chats.
