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:

  1. 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.
  2. 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 nameDescriptionEventGuidelines
Exit failureThe connector had a technical issueAI Event: Failure exitTransfer to an advisor
AI computed an answerThe AI has responds a valid answer that has been sent to the customerAI Event: AI computed an answerSend the AI message and ask for satisfaction
Neither agents nor AI can asnwer to this topicIrrelevant message (topic outside of your topic, problematic messages…)AI Event: AI has no answer for youTransfer to an advisor in a dedicated team
AI response can be sent and the conversation should continue with an agentthe AI bot has an answer but indicates that an advisor would have more info on the topicAI Event: AI computed an answer but should hand over to an advisor nowSend AI message + Transfer to an advisor
AI response should not be sent: the conversation should continue wit an agentThe AI does not responds a answer relevant enough to be sent to the customerAI Event: AI computed an answer NOT sent, handover to an advisorTransfer to an advisor
Invalid format of message returned by AIThe response from the AI has an invalid format (picture if not supported, too many characters)AI Event: Invalid format of message turned by AITransfer to an advisor
The user sent another message before the AI could answerAs of today, we do not support several messages sent by the customer before the AI could answer to the first oneAI Event: The user sent another message before the AI could answerTransfer to an advisor
AI API errorYour 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 errorTransfer to an advisor

What’s Next

See the sample code at https://github.com/alcmeon/gaia-x