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 message
  • context - Optional context string
  • session.id - Session identifier
  • user.external_id - User identifier
  • user.site_id - Site identifier
  • agent_id - Your AI agent ID
  • exits - 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 request
  • Authorization: Basic Auth with instance_id:application_secret

Request body:

  • code (required) - Exit code (endDiscussion, continueDiscussion, escalateToHuman, error, or custom)
  • message (optional) - Text to send to user (can be null)
  • 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 CodeDescriptionTypical Next Step
endDiscussionAI answered definitivelySend message, ask for satisfaction
continueDiscussionAI needs more user inputLoop back to capture message content, return to AI box
escalateToHumanHuman advisor neededTransfer to advisor (no message sent)
errorError, timeout, or unknown exit codeTransfer to advisor
Custom exitsAI identified specific intentRoute 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