AI Bot Connector (V2)
Build a bot using AI to answer customer questions with custom exit paths
Overview
The AI Bot Connector V2 API allows you to integrate your own AI bot into the Alcmeon bot builder with enhanced support for custom exit paths and variable handling.
The AI Bot API is asynchronous, allowing the AI bot time to build the response without blocking the bot scenario execution.
How to setup your Alcmeon platform for the AI Connector v2
1. Find your instance ID
Your instance_id (or company_id) can be found in the Alcméon URL: https://alcmeon.com/c/v3/#{instance_id}/...
2. Create an application with AI Connector permission
Go to Settings > Applications and create an application with the AI Connector permission.
Note the application secret - you'll need it for API authentication.
3. Setup an AI agent with exits
Go to Settings > AI and configure your AI Agent:
4. Build a scenario with the AI V2 box
Add the AI Connector V2 box to your bot scenario.
Optionally set message_context before the AI box using an Action box to provide additional context.
Connect exits to appropriate next steps in your scenario:
How to use the AI Connector v2 in your code
1. Implement the webhook
Implement the AI bot connector webhook at your chosen URL endpoint.
Request body parameters:
jwt- Token to use for callback (valid 600 seconds)query- User's messagecontext- Optional context stringsession.id- Session identifieruser.external_id- User identifieruser.site_id- Site identifieragent_id- Your AI agent IDexits- Array of available exits (standard + custom)
Example request:
{
"jwt": "sample-jwt",
"query": "What services does Alcmeon provide ?",
"context": "something optional set via an Action Box in Alcmeon's scenario",
"session": {
"id": "807ac633-e813-4701-b403-a2615ba0db8d"
},
"user": {
"external_id": "sample-user-external-id",
"site_id": 1
},
"agent_id": null,
"exits": [
{
"code": "endDiscussion",
"description": "AI answered in a definitive way. The bot scenario will typically continue with a Satisfaction question.",
"is_custom": false
},
{
"code": "continueDiscussion",
"description": "AI typically sent a question to the client and needs to receive his next message to continue answering. The bot scenario will typically continue with a loop to a capture message content and back to the AI Bot box.",
"is_custom": false
},
{
"code": "escalateToHuman",
"description": "AI detects that a human advisor will be better at answering for various reasons: client asked for it explicitly, or AI did not find an answer, or the question is out of the AI scope, etc. AI typically does not send an answer at all in this case.",
"is_custom": false
},
{
"code": "error",
"description": "The AI or Alcmeon raised an error or a timeout. Or an unknown Exit Code (for API) was sent.",
"is_custom": false
},
{
"code": "gdpr",
"description": "Use this exit if user has questions regarding their GDPR rights.",
"is_custom": true
}
]
}Response: Return HTTP 200 immediately, before processing the answer.
Security: Validate the apiKey header matches your configured key.
2. Implement the async job that calls back Alcméon API
When your AI generates an answer, call the callback API within 600 seconds.
Endpoint: POST https://api.alcmeon.com/ai/answer/v2
Headers:
X-JWT: The JWT token from the webhook requestAuthorization: Basic Auth withinstance_id:application_secret
Request body:
code(required) - Exit code (endDiscussion,continueDiscussion,escalateToHuman,error, or custom)message(optional) - Text to send to user (can benull)variables(optional) - Dictionary of variables to store in bot context
Example response:
{
"code": "endDiscussion",
"message": "Alcmeon offers a variety of services to enhance customer engagement, including:\n\nOmnichannel Conversations: Alcmeon allows businesses to manage customer interactions across multiple channels such as WhatsApp, Facebook Messenger, Instagram, and more, ensuring consistent and timely communication.\n\nAI-Driven Customer Support: The platform features AI-driven chatbots that can handle routine inquiries and provide instant responses, improving customer service efficiency and satisfaction.\n\nAI Assistant: Alcmeon's AI Assistant aids human service advisors by offering real-time response suggestions, language translations, and conversation summaries, boosting advisor productivity by up to 50%.\n\nAnalytics Module: This tool provides businesses with insights into customer behavior, agent performance, and overall service efficiency, enabling informed decision-making and strategy refinement.\n\nWorkflow Automation: The platform automates routine tasks, allowing customer service agents to focus on more complex issues, which improves efficiency and reduces response times.\n\nPersonalized Campaigns: Alcmeon enables personalized conversational marketing campaigns that can significantly increase click-through rates (CTR) and return on investment (ROI).\n\nCRM Integration: The platform integrates with popular CRM systems like Salesforce, providing a holistic view of customer data and enabling personalized interactions.\n\nThese services collectively aim to create a seamless and engaging experience for customers while empowering businesses to optimize their customer service operations.",
"variables": {"sentiment": "neutral"}
}Response: Return HTTP 200 immediately, before processing the answer.
Security: Validate the apiKey header matches your configured key.
Exit Routing Guide
| Exit Code | Description | Typical Next Step |
|---|---|---|
endDiscussion | AI answered definitively | Send message, ask for satisfaction |
continueDiscussion | AI needs more user input | Loop back to capture message content, return to AI box |
escalateToHuman | Human advisor needed | Transfer to advisor (no message sent) |
error | Error, timeout, or unknown exit code | Transfer to advisor |
| Custom exits | AI identified specific intent | Route to custom scenario logic, use variables |
Important Notes
Timeout Handling:
If your AI doesn't respond within 600 seconds, the scenario automatically takes the error exit.
Unexpected Messages:
If a user sends another message before the AI responds, the scenario routes to the continueDiscussion exit to prevent conflicts.
API Reference
- Webhook specification: https://developers.alcmeon.com/reference/post_ai-v2-bot
- Callback specification: https://developers.alcmeon.com/reference/post_ai-v2-answer
Updated 7 days ago