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 In-message.

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.