AI Bot Connector
Build a bot using AI to answer customer questions
The AI Bot Connector API is in alpha state and signature may change before release.
Overview
The AI Bot Connector API allows you to integrate your own AI bot into the Alcmeon bot builder. An AI bot connector is a box which will allow to interrogate an AI through to generate an anwser to a customer.
The AI Bot API is asynchronous so that the AI bot can take time to build the response.
To implement an AI Bot you need to:
- Implement the AI bot connector webhook. When customer ask for a quesiton, the question and the context is sent with a jwt token. In the webhook, send back a 200 answer as soon you receive the question, before starting to compute the answer.
- When the answer is generated, call the callback API with the answer, and id, a code and the jwt token of the question.
How to configure your Alcméon platform
You need to connect with a administrator account on your Alcméon platform. You need to know which url connect to your server.
Get your instance_id
Your instance_id (or company_id) can be found in the Alcméon url: https://alcmeon.com/c/v3/#/{instance_id}/...
Create an application
Go to Settings, then Applications.
Create an application with the permission AI Connector. You can give it any name you want.
Then note the secret:
How to handle request
You must implement the AI bot connector webhook.
The url used to invoke your webhook can be anything, you will have to use this url in the box configuration.
Your webhook will receive the following parameters in the request body:
- query: The last message the user sent
- context: A simple string your AI can use to define the context of the answer. You can define this context using scripted bot before invoking the AI Bot in your scenario.
- jwt: A token used to send back the answer once its computed
First you must answer with a status
(should be acknoledged). The answer must be computed after the answer, and the answer will be send using the callback API.
This way Alcmeon platform will not have to wait for your AI to generate the answer.
How to protect your API
You can protect access to your webhooks by checking the header apiKey.
The value sent inapiKey is defined in the box you will create in your scenario. You are free to define the key the way you want. This key should only be used to protect your API, and should not be the key to access another API, for exemple your LLM provider.
How to send back answer
When you have an answer available, you need to send it using the callback API.
You will need to send the jwt
token as a header (X-JWT) so you should keep it during your processing. You also will send a json message object that contains:
- An Id (can be anything)
- A content that will be displayed to the user
- A code that describe how the message should be traited:
- suggestContactEscalation if the generated answer can be sent but it's suggested to transfer the conversation afterwards to a support agent
- mustContactEscalation if the generated answer should not be sent and the conversation afterwards should be transferred to a support agent
- EndConversation if the scope of the conversation can neither be handled by the AI nor by a support agent
An error object can also be sent, but it will only be logged and not sent to the user.
Please note that this API is protected and you need to use authentication via HTTP Basic Auth with :
- username: your instance_id
- password: your application secret
How to use the bot in a scenario
Before the AI Connector
Before the AI connector, please use the "Capture message content" subbot so that the use message will be captured in the message_content variable
You can also use a Action to set the message_context before the AI connector. This should be done after a menu so that the context depends of the user choice.
Adding the AI Connector box
The box is available in scenario for Whatsapp, Messager and AlcmeonChat.
You shoud configure your box with the following parameters:
- The maximum number of characters: If a response from the AI is longer, the message will be split in 2 more or less equal parts. The connector will always be able to send 2 messages.
- String that will prefix all AI answers: Clients could want to inform their customers that they are speaking with an AI and not an advisor. The prefix is good way to do so.
- AI API url : The url of you service.
- AI API key : The key that protect your webhook
Exiting the AI Bot
You have several exits from an AI bot
Here are all the exists, their description, the custom event sent when it happens, and a guideline to handle this exit.
Exit name | Description | Event | Guidelines |
---|---|---|---|
Exit failure | The connector had a technical issue | AI Event: Failure exit | Transfer to an advisor |
AI computed an answer | The AI has responds a valid answer that has been sent to the customer | AI Event: AI computed an answer | Send the AI message and ask for satisfaction |
Neither agents nor AI can asnwer to this topic | Irrelevant message (topic outside of your topic, problematic messages…) | AI Event: AI has no answer for you | Transfer to an advisor in a dedicated team |
AI response can be sent and the conversation should continue with an agent | the AI bot has an answer but indicates that an advisor would have more info on the topic | AI Event: AI computed an answer but should hand over to an advisor now | Send AI message + Transfer to an advisor |
AI response should not be sent: the conversation should continue wit an agent | The AI does not responds a answer relevant enough to be sent to the customer | AI Event: AI computed an answer NOT sent, handover to an advisor | Transfer to an advisor |
Invalid format of message returned by AI | The response from the AI has an invalid format (picture if not supported, too many characters) | AI Event: Invalid format of message turned by AI | Transfer to an advisor |
The user sent another message before the AI could answer | As of today, we do not support several messages sent by the customer before the AI could answer to the first one | AI Event: The user sent another message before the AI could answer | Transfer to an advisor |
AI API error | Your AI returns a technical error. It’s also the exit we take in case of a lack of answer from your AI. | AI Event: AI API error | Transfer to an advisor |
Updated 14 days ago