Alli Conversational AI

Alli Answer allows you to build personalized user interaction, give your users full access to your knowledge base, and transform your team's operation efficiency across web and mobile.

A guide on how to properly use our chat API can be found here.

Start Conversation

POST https://backend.alli.ai/webapi/start_conversation

Start a conversation using a Skill. Note: this endpoint is currently only compatible with Message Node, Q&A Node, and Documents Node.

Headers

Name	Type	Description
API-KEY	string	Your API key can be found in your dashboard Settings menu, under the General tab.
OWN-USER-ID	string	The user id of the user who opens the conversation.

Request Body

Name	Type	Description
placement	string	Used to match which Skill to start the conversation with.

200 You will get the result in the following JSON format. id: The unique id for the conversation just initiated. nluLanguage: The Alli project's language. edges: An array of JSON objects, each representing a message in the conversation. message: The text message the user would be shown by Alli. This is in Draftjs format. createdAt: The timestamp for when this message was sent. chatOptionsInfos: An array of JSON objects, each representing a clickable button Alli would display to the user. shortenOption, longOption : The text content of a button. shortenOption is the text after the length limitation setting is applied. style: Styling information for a button.

{
    "result": {
        "conversation": {
            "id": "CONVERSATION_ID",
            "project": {
                "nluLanguage": "LANGUAGE"
            },
            "chats": {
                "edges": [
                    {
                        "node": {
                            "id": "CHAT_ID",
                            "message": "MESSAGE",
                            "createdAt": NUMBER,
                            "chatOptionInfos": [
                                {
                                    "shortenOption": "BUTTON_TEXT",
                                    "longOption": "BUTTON_TEXT",
                                    "style": {
                                        "bgColor": "COLOR_HEX",
                                        "bold": BOOLEAN,
                                        "fontColor": "COLOR_HEX",
                                        "italic": BOOLEAN,
                                        "lineColor": "COLOR_HEX",
                                        "underline": BOOLEAN
                                    },
                                    "meta": ""
                                },
                                {
                                    "shortenOption": "BUTTON_TEXT",
                                    "longOption": "BUTTON_TEXT",
                                    "style": {
                                        "bgColor": "COLOR_HEX",
                                        "bold": BOOLEAN,
                                        "fontColor": "COLOR_HEX",
                                        "italic": BOOLEAN,
                                        "lineColor": "COLOR_HEX",
                                        "underline": BOOLEAN
                                    },
                                    "meta": ""
                                }
                            ],
                            "isDeleted": BOOLEAN
                        }
                    }
                ]
            }
        }
    },
    "errors": null
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. To get the api key, please see getting-api-key section.

curl -L -X POST 'https://backend.alli.ai/webapi/start_conversation' \
-H 'API-KEY: YOUR_API_KEY' \
-H 'OWN-USER-ID: test_userid' \
-H 'Content-Type: application/json' \
--data-raw '{"placement": "skill_A"}'

Response Example

{
    "result": {
        "conversation": {
            "id": "Q29udmVyc2F0aW9uOjYwMDZiNTM3MmRhPHAwMjZlOTFjMjllZQ==",
            "project": {
                "nluLanguage": "EN"
            },
            "chats": {
                "edges": [
                    {
                        "node": {
                            "id": "Q2hhdDo2MDQ2YjUzNzJkYWQwMDI2ZTkxYzI5ZDE=",
                            "message": "{\"blocks\": [{\"key\": \"egkjj\", \"text\": \"Please select an option\", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}], \"entityMap\": {}}",
                            "createdAt": 1615246647609.666,
                            "chatOptionInfos": [
                                {
                                    "shortenOption": "FAQ",
                                    "longOption": "FAQ",
                                    "style": {
                                        "bgColor": "#FFFFFF",
                                        "bold": false,
                                        "fontColor": "#2074ff",
                                        "italic": false,
                                        "lineColor": "#2074ff",
                                        "underline": false
                                    },
                                    "meta": ""
                                },
                                {
                                    "shortenOption": "Document",
                                    "longOption": "Document",
                                    "style": {
                                        "bgColor": "#FFFFFF",
                                        "bold": false,
                                        "fontColor": "#2074ff",
                                        "italic": false,
                                        "lineColor": "#2074ff",
                                        "underline": false
                                    },
                                    "meta": ""
                                }
                            ],
                            "isDeleted": false
                        }
                    }
                ]
            }
        }
    },
    "errors": null
}

End conversation by agent

POST https://backend.alli.ai/webapi/end_conversation_by_agent

Headers

Name	Type	Description
API-KEY*	String	Your API key can be found in your dashboard Settings menu, under the General tab.

Request Body

Name	Type	Description
*	String	Conversation Id

Request Example

curl -L -X POST 'https://backend.alli.ai/webapi/end_conversation_by_agent' \
-H 'api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{"id": "Q29udmVyc2F0aW9uOjYxYTcwMzAxMjYzZWM2NmI2MDY0NzVjOQ=="}'

Response Example

{
   "result":{
      "conversation":{
         "id":"Q29udmVyc2F0aW9uOjYxYTcwMzAxMjYzZWM2NmI2MDY0NzVjOQ==",
         "completedTime":1639093180790.565,
         "state":"END_BY_AGENT",
         "__typename":"Conversation"
      },
      "__typename":"UpdateConversationState"
   },
   "errors":null
}

Send Chat

POST https://backend.alli.ai/webapi/send_chat

Send a message as the user for an existing conversation. Note: this endpoint is currently only compatible with Message Node, Q&A Node, and Documents Node.

Headers

Name	Type	Description
API-KEY*	string	Your API key can be found in your dashboard Settings menu, under the General tab.

Request Body

Name	Type	Description
message	string	The message to send in the conversation. Cannot be null or an empty string.
conversationId	string	Unique id for the conversation you want to send a message in.

200 You will get the result in the following JSON format.

You will get the result in the following JSON format:

responses: Array of JSON objects, each representing a message. The first message object will be the Request's message.

message: The text message the user would be shown by Alli. Text messages set in nodes in the Skill builder will be in Draftjs format.

createdAt: The timestamp for when this message was created.

chatOptionInfos: An array of JSON objects, each representing a clickable button Alli would display to the user.

shortenOption, longOption: The text content of a button. shortenOption is the text after the length limitation setting is applied.

style: Styling information for a button

knowledgeBasePreview: When the message is an answer to a document search, this will include the preview URL info.

chatMrcInfos: When the message is an answer to a document search and using the carousel UI, this will have one or more knowledgeBasePreview parameters under it.

{
    "result": {
        "responses": [
            {
                "id": "CHAT_ID",
                "message": "MESSAGE",
                "createdAt": NUMBER,
                "isDeleted": BOOLEAN
            },
            {
                "id": "CHAT_ID",
                "message": "MESSAGE",
                "createdAt": NUMBER,
                "chatOptionInfos": [
                    {
                        "shortenOption": "BUTTON_TEXT",
                        "longOption": "BUTTON_TEXT",
                        "style": {
                            "bgColor": "COLOR_HEX",
                            "bold": BOOLEAN,
                            "fontColor": "COLOR_HEX",
                            "italic": BOOLEAN,
                            "lineColor": "COLOR_HEX",
                            "underline": BOOLEAN
                        },
                        "meta": ""
                    }
                ],
                "isDeleted": BOOLEAN
            }
        ],
        "state": "WAIT_USER_ANSWER_2"
    },
    "errors": null
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. To get the api key, please see getting-api-key section.

curl -L -X POST 'https://backend.alli.ai/webapi/send_chat' \
-H 'api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{"conversationId": "Q29udmVyc2F0aW9uOjYwNDZiNWNkZTZkZGQ5MGE3ZWJlMGYxZQ==", "message": "I need help!"}'

Response Example

{
    "result": {
        "responses": [
            {
                "id": "Q2hhdDo2MDQ2YjVlY2U2ZGRkOTBhN2ViZTBmNTU=",
                "message": "I need help!",
                "createdAt": 1615246828077.0,
                "isDeleted": false
            },
            {
                "id": "Q2hhdDo2MDQ2YjVlY2U2ZGRkOTBhN2ViZTBmNTc=",
                "message": "{\"blocks\": [{\"key\": \"6so0p\", \"text\": \"Please input your question\", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}], \"entityMap\": {}}",
                "createdAt": 1615246828110.0,
                "chatOptionInfos": [],
                "isDeleted": false,
                "knowledgeBasePreview": {
                  "previewUrl": "https://www.alli.ai/projects/UHJvamVjdDo1ZDUyYjY3N2NkMGI4MjU5Y2Q1MmY5N2E=/knowledgeBases/S25vd2xlZGdlQmFzZTo2MjA5MWY4M2VhM2U5NjM2NTJmZjc2YzU=/preview?page=9&highlight_indexes=null&highlights=%7B%22indexes%22%3Anull%2C%22pageIndexes%22%3A%5B%7B%22page%22%3A9%2C%22indexes%22%3A%5B7%2C8%2C9%2C10%2C12%2C13%2C14%2C15%2C16%2C17%2C18%2C19%2C20%2C21%2C23%2C24%2C25%2C26%2C27%2C28%2C29%2C30%2C32%2C33%2C35%2C36%2C7%2C8%2C9%2C10%2C12%2C13%2C14%2C15%2C16%2C17%2C18%2C19%2C20%2C21%2C23%2C24%2C25%2C26%2C27%2C28%2C29%2C30%2C32%2C33%2C35%2C36%5D%7D%5D%7D"
                  }
            }
        ],
        "state": "WAIT_USER_ANSWER_2"
    },
    "errors": null
}

Summary Analytics

GET https://backend.alli.ai/webapi/summary_analytics

Provides various summarized analytics information for your project.

Headers

Name	Type	Description
API-KEY	string	Your API key can be found in your dashboard Settings menu, under the General tab.

Request Body

Name	Type	Description
startDate	string	Start of range of dates to query in YYYY-MM-DD format.
endDate	string	End of range of dates to query in YYYY-MM-DD format.

200 You will get the result in the following JSON format. conversations: Number of conversations made within the date range. conversationsUpDown: For the queried number of days, the percentage change of number of conversations from the preceding number of days. participants: Sum of daily unique counts of users who had conversations with Alli. participantsUpDown: For the queried number of days, the percentage change of sum of users from the preceding number of days. uniqueParticipants: Unique count of users who had conversations with Alli within the date range. uniqueParticipantsUpDown: For the queried number of days, the percentage change of uniqueParticipants from the preceding number of days. queries: Total number of questions toward FAQ or MRC Documents from users. It includes questions asked from the 'Answer with FAQ' node, 'Answer with MRC' node, and the Alli dashboard. queriesUpDown: For the queried number of days, the percentage change of total queries from the preceding number of days. queriedUsers: Sum of daily unique counts of users who asked questions at least once toward FAQ or MRC Documents. queriedUsersUpDown: For the queried number of days, the percentage change of queriedUsers from the preceding number of days. uniqueQueriedUsers: Unique count of users who asked questions at least once toward FAQ or MRC Documents. uniqueQueriedUsersUpDown: For the queried number of days, the percentage change of uniqueQueriedUsers from the preceding number of days. instantResolution: The number of answers customers selected upon their questions from the Answer with FAQ node. instantResolutionUpDown: For the queried number of days, the percentage change of instantResolution from the preceding number of days. aiResponseRate: The ratio of 'Resolved by AI' over the number of questions asked from the Answer with FAQ node. aiResponseRateUpDown: For the queried number of days, the percentage change of aiResponseRate from the preceding number of days. uniqueVisitors: Unique count of visitors to the webpage where Alli SDK is integrated. This number is the 'Number of Users' for billing calculation. uniqueVisitorsUpDown: For the queried number of days, the percentage change of uniqueVisitors from the preceding number of days. totalFaqs: Number of FAQs added. totalFaqsUpDown: For the queried number of days, the percentage change of totalFaqs from the preceding number of days. totalDocuments: Number of Documents uploaded. totalDocumentsUpDown: For the queried number of days, the percentage change of totalDocuments from the preceding number of days.

{
    "result": {
        "conversations": CONVERSATIONS,
        "conversationsUpDown": CONVERSTAIONS_UPDOWN,
        "participants": PARTICIPANTS,
        "participantsUpDown": PARTICIPANTS_UPDOWN,
        "uniqueParticipants": UNIQUE_PARTICIPANTS,
        "uniqueParticipantsUpDown": UNIQUE_PARTICIPANTS_UPDOWN,
        "queries": QUERIES,
        "queriesUpDown": QUERIES_UPDOWN,
        "queriedUsers": QUERIED_USERS,
        "queriedUsersUpDown": QUERIED_USERS_UPDOWN,
        "uniqueQueriedUsers": UNIQUE_QUERIED_USERS,
        "uniqueQueriedUsersUpDown": UNIQUE_QUERIED_USERS_UPDOWN,
        "instantResolution": INSTANT_RESOLUTION,
        "instantResolutionUpDown": INSTANT_RESOLUTION_UPDOWN,
        "aiResponseRate": AI_RESPONSE_RATE,
        "aiResponseRateUpDown": AI_RESPONSE_RATE_UPDOWN,
        "uniqueVisitors": UNIQUE_VISITORS,
        "uniqueVisitorsUpDown": UNIQUE_VISITORS_UPDOWN,
        "totalFaqs": TOTAL_FAQS,
        "totalFaqsUpDown": TOTAL_FAQS_UPDOWN,
        "totalDocuments": TOTAL_DOCUMENTS,
        "totalDocumentsUpDown": TOTAL_DOCUMENTS_UPDOWN,
        "feedbacksUpDown": FEEDBACKS_UPDOWN
    },
    "errors": null
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. To get the api key, please see getting-api-key section.

curl -X GET -d '{ "startDate": "2020-11-14",
"endDate": "2020-12-14"}' \
-H 'API-KEY: YOUR_API_KEY' \
https://backend.alli.ai/webapi/summary_analytics

Response Example

{
    "result": {
        "conversations": 45,
        "conversationsUpDown": -45.78,
        "participants": 44,
        "participantsUpDown": -32.31,
        "uniqueParticipants": 43,
        "uniqueParticipantsUpDown": -31.75,
        "queries": 39,
        "queriesUpDown": -56.18,
        "queriedUsers": 35,
        "queriedUsersUpDown": -46.97,
        "uniqueQueriedUsers": 35,
        "uniqueQueriedUsersUpDown": -44.44,
        "instantResolution": 1,
        "instantResolutionUpDown": 0.0,
        "aiResponseRate": 100.0,
        "aiResponseRateUpDown": 0.0,
        "uniqueVisitors": 2077,
        "uniqueVisitorsUpDown": -1.05,
        "totalFaqs": 0,
        "totalFaqsUpDown": 0.0,
        "totalDocuments": 0,
        "totalDocumentsUpDown": 0.0,
        "feedbacksUpDown": 0.0
    },
    "errors": null
}

Daily Conversation Count

GET https://backend.alli.ai/webapi/conversation_daily_count

The total number of conversations per day for a given range.

Headers

Name	Type	Description
API-KEY	string	Your API key can be found in your dashboard Settings menu, under the General tab.

Request Body

Name	Type	Description
endDate	string	End of range of dates to query in YYYY-MM-DD format.
startDate	string	Start of range of dates to query in YYYY-MM-DD format.

200 You will get the result in the following JSON format. dailyTotalCount: List of date and activeCount pairs, where activeCount is the number of conversations on date.

{
    "result": {
        "dailyTotalCount": [
            {
                "date": "DATE",
                "activeCount": ACTIVE_COUNT
            }
        ],
        "state": "NORMAL",
        "campaignCount": 1
    },
    "errors": null
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. To get the api key, please see getting-api-key section.

curl -X GET -d '{ "startDate": "2020-11-19",
"endDate": "2020-11-24"}' \
-H 'API-KEY: YOUR_API_KEY' \
https://backend.alli.ai/webapi/conversation_daily_count

Response Example

{
    "result": {
        "dailyTotalCount": [
            {
                "date": "2020-11-19",
                "activeCount": 30
            },
            {
                "date": "2020-11-20",
                "activeCount": 49
            },
            {
                "date": "2020-11-21",
                "activeCount": 32
            },
            {
                "date": "2020-11-22",
                "activeCount": 2
            },
            {
                "date": "2020-11-23",
                "activeCount": 31
            },
            {
                "date": "2020-11-24",
                "activeCount": 16
            }
        ],
        "state": "NORMAL",
        "campaignCount": 1
    },
    "errors": null
}

Daily FAQ Count

GET https://backend.alli.ai/webapi/faq_daily_count

Daily trend of Q&A from FAQ in given date range.

Headers

Name	Type	Description
API-KEY	string	Your API key can be found in your dashboard Settings menu, under the General tab.

Request Body

Name	Type	Description
startDate	string	Start of range of dates to query in YYYY-MM-DD format.
endDate	string	End of range of dates to query in YYYY-MM-DD format.

200 You will get the result in the following JSON format: dailyTotalCount: List of date and activeCount pairs, where activeCount is the number of faqs selected on date.

{
    "result": {
        "dailyTotalCount": [
            {
                "date": "DATE",
                "activeCount": ACTIVE_COUNT
            }
        ],
        "state": "NORMAL",
        "campaignCount": 1
    },
    "errors": null
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. To get the api key, please see getting-api-key section.

curl -X GET -d '{ "startDate": "2020-11-19",
"endDate": "2020-11-24"}' \
-H 'API-KEY: YOUR_API_KEY' \
https://backend.alli.ai/webapi/faq_daily_count

Response Example

{
    "result": {
        "dailyTotalCount": [
            {
                "date": "2020-11-19",
                "count": 24
            },
            {
                "date": "2020-11-20",
                "count": 70
            },
            {
                "date": "2020-11-21",
                "count": 23
            },
            {
                "date": "2020-11-22",
                "count": 45
            },
            {
                "date": "2020-11-23",
                "count": 34
            },
            {
                "date": "2020-11-24",
                "count": 30
            }
        ]
    },
    "errors": null
}

Daily FAQ Analytics

GET https://backend.alli.ai/webapi/faq_daily_analytics

Analytics information for the most frequently asked Q&As.

Headers

Name	Type	Description
API-KEY	string	Your API key can be found in your dashboard Settings menu, under the General tab.

Request Body

Name	Type	Description
topN	number	Top N of the most frequently asked Q&A. Maximum value for N is 20. Please use 1, 5, 10, or 20 for N.
startDate	string	Start of range of dates to query in YYYY-MM-DD format.
endDate	string	End of range of dates to query in YYYY-MM-DD format.

200 You will get the result in the following JSON format: faqDailyAnalytics: List of JSON objects, each containing analytics information for one faq. totalCount: Total number of times Q&A was selected. totalShownCount: Total number of times Q&A was displayed. selectedRatio: Ratio of times Q&A was selected to times Q&A was displayed stats: List of date and selectedCount pairs where selectedCount is the number of times the faq was selected on date.

{
    "result": {
        "faqDailyAnalytics": [
            {
                "totalCount": NUMBER,
                "totalShownCount": NUMBER,
                "selectedRatio": NUMBER,
                "faq": {
                    "id": "ID_1",
                    "question": "QUESTION_1"
                },
                "stats": [
                    {
                        "date": "DATE",
                        "selectedCount": NUMBER
                    }
                ]
            }
        ]
    },
    "errors": null
}

Request Example

Please replace YOUR_API_KEY with your one in the example below. To get the api key, please see getting-api-key section.

curl -X GET -d '{ "startDate": "2020-12-02",
"endDate": "2020-12-05", "topN": 5}' \
-H 'API-KEY: YOUR_API_KEY' \
https://backend.alli.ai/webapi/faq_daily_analytics

Response Example

{
    "result": {
        "faqDailyAnalytics": [
            {
                "totalCount": 1,
                "totalShownCount": 1,
                "selectedRatio": 100.0,
                "faq": {
                    "id": "RkFROjVkZDQ4ZWFhN2E4ZGM2M2Y4OGNhZmUzOQ==",
                    "question": "What is Alli?"
                },
                "stats": [
                    {
                        "date": "2020-12-02",
                        "selectedCount": 0
                    },
                    {
                        "date": "2020-12-03",
                        "selectedCount": 0
                    },
                    {
                        "date": "2020-12-04",
                        "selectedCount": 1
                    },
                    {
                        "date": "2020-12-05",
                        "selectedCount": 0
                    }
                ]
            }
        ]
    },
    "errors": null
}

Executing a Skill

POST https://backend.alli.ai/webapi/skill

This API executes a skill and returns the final text answer as json format. Please follow the link under the 'Learn More about Variables' below for more information about the variables parameter. This API can be used for the entity extraction if the skill is designed for the entity extraction. Unlike most, this API requires the use of the SDK key instead of the API key.

Headers

Name	Type	Description
API-KEY	string	Your API KEY can be found in your Dashboard Settings menu under the general tab. Requires the use of the SDK key.

Request Body

Name	Type	Description
id	string	This is a skill id. If you click a skill in the Alli Dashboard, the URL is something like https://app.alli.ai/projects/PROJECT_ID/campaigns/SKILL_ID. Please put SKILL_ID here.
text	string	This is an input text for the skill execution.
variables	object	variables is a JSON object to set the variables in the skill.

200 You will get the result as the following json format. The final text output will be returned in result. If any error happens, the error message will be included in the errors.

{"result": "TEXT RESULT FROM SKILL", "errors": []}

Learn More about Variables

To learn more about the variables in Alli, please see this user guide.

Request Example

Please replace YOUR_API_KEY with your SDK Key in the example below. This API requires the use of the SDK key instead of the api key. Please see getting-api-key section as it is in the same location.

curl -d '{"id": "YOUR SKILL ID",
        "text": "issue date",
        "variables": {"YOUR_VARIABLE": "YOUR_VARIABLE_VALUE"}}' \
        -H 'API-KEY: YOUR_API_KEY' \
        -H 'Content-Type: application/json' https://backend.alli.ai/webapi/skill

Response Example

{"result": "TEXT RESULT FROM SKILL", "errors": []}

API Classifications

View the API classifications and mapping for billing purposes.

Download the Excel file here