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.
Method: POST
Headers:
apiKey: Your configured API key for authenticationX-Alcmeon-Trace-Id: Trace identifier for debuggingX-Environment: Environment identifierContent-Type:application/json
Body:
| Parameter | Type | Required | Description |
|---|---|---|---|
jwt | object | Yes | JWT token object for authenticating the callback |
jwt.token | string | Yes | The JWT token string to use in callback (valid 60 seconds) |
jwt.exp | integer | Yes | Token expiration timestamp (Unix timestamp) |
jwt.remaining_api_calls | integer | Yes | Number of remaining API calls (always 1) |
query | string | Yes | The user's message content that needs an AI response |
context | string | No | Optional context set via bot variables (variable name: message_context) |
session | object | Yes | Session information |
session.id | string | Yes | Correlation identifier to scope the conversation (variable name: session_id) |
social_media_user | object | No | Information about the user who sent the message |
social_media_user.id | string | No | External user identifier (e.g., Twitter user ID, Facebook user ID) |
social_media_user.name | string | No | Display name of the user |
social_media_account | object | No | Information about the social media channel |
social_media_account.id | integer | No | Site/channel identifier in Alcméon |
social_media_account.type | string | No | Platform type (e.g., 'twitter', 'facebook', 'instagram', 'whatsapp') |
social_media_account.max_message_content_length | integer | No | Maximum character length for messages on this channel |
social_media_account.supported_message_types | array | No | List of supported message types (currently only 'text') |
social_media_account.supported_attachment_types | array | No | List of supported attachment types (currently empty) |
exits | array | Yes | Available exits for routing the scenario |
exits[].code | string | Yes | Exit code identifier |
exits[].description | string | Yes | Human-readable description |
exits[].is_custom | boolean | Yes | True if custom exit, false for standard exits |
Example request:
{
"jwt": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"exp": 1709554800,
"remaining_api_calls": 1
},
"query": "What services does Alcmeon provide?",
"context": "User is interested in customer service solutions",
"session": {
"id": "807ac633-e813-4701-b403-a2615ba0db8d"
},
"social_media_user": {
"id": "user_12345",
"name": "John Doe"
},
"social_media_account": {
"id": 42,
"type": "whatsapp",
"max_message_content_length": 4096,
"supported_message_types": ["text"],
"supported_attachment_types": []
},
"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. Process the Request Asynchronously
After acknowledging the webhook, process the AI request in the background. When your AI finished generating an answer, call the callback API within 600 seconds.
Method: POST
Endpoint: https://api.alcmeon.com/ai/v2/answer/
Headers:
| Header | Required | Description |
|---|---|---|
X-JWT | Yes | The JWT token string from jwt.token in the webhook request |
Authorization | Yes | Basic Auth with instance_id:application_secret |
Content-Type | Yes | application/json |
Body:
| Parameter | Type | Required | Description |
|---|---|---|---|
code | string | Yes | Exit code (must match one from the webhook exits list) |
message | object | No | Message to send to the user (null if no message) |
message.type | string | Yes* | Message type (currently only 'text' supported) |
message.text | string | Yes* | The AI-generated response text |
variables | object | Yes | Dictionary of variables to store in bot context |
Example response:
{
"code": "endDiscussion",
"message": {
"type": "text",
"text": "Alcmeon offers a variety of services to enhance customer engagement, including:\n\n• Omnichannel Conversations: Manage customer interactions across WhatsApp, Facebook Messenger, Instagram, and more\n• AI-Driven Customer Support: Chatbots that handle routine inquiries with instant responses\n• AI Assistant: Real-time response suggestions and translations for human advisors\n• Analytics Module: Insights into customer behavior and agent performance\n• Workflow Automation: Automate routine tasks to improve efficiency\n• Personalized Campaigns: Conversational marketing with high CTR and ROI\n• CRM Integration: Seamless integration with Salesforce and other CRMs\n\nThese services create a seamless customer experience while optimizing your service operations."
},
"variables": {
"sentiment": "positive",
"intent": "product_inquiry",
"confidence": 0.95
}
}{
"code": "escalateToHuman",
"message": null,
"variables": {
"escalation_reason": "complex_technical_question",
"sentiment": "frustrated"
}
}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 12 days ago