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 authentication
  • X-Alcmeon-Trace-Id: Trace identifier for debugging
  • X-Environment: Environment identifier
  • Content-Type: application/json

Body:

ParameterTypeRequiredDescription
jwtobjectYesJWT token object for authenticating the callback
jwt.tokenstringYesThe JWT token string to use in callback (valid 60 seconds)
jwt.expintegerYesToken expiration timestamp (Unix timestamp)
jwt.remaining_api_callsintegerYesNumber of remaining API calls (always 1)
querystringYesThe user's message content that needs an AI response
contextstringNoOptional context set via bot variables (variable name: message_context)
sessionobjectYesSession information
session.idstringYesCorrelation identifier to scope the conversation (variable name: session_id)
social_media_userobjectNoInformation about the user who sent the message
social_media_user.idstringNoExternal user identifier (e.g., Twitter user ID, Facebook user ID)
social_media_user.namestringNoDisplay name of the user
social_media_accountobjectNoInformation about the social media channel
social_media_account.idintegerNoSite/channel identifier in Alcméon
social_media_account.typestringNoPlatform type (e.g., 'twitter', 'facebook', 'instagram', 'whatsapp')
social_media_account.max_message_content_lengthintegerNoMaximum character length for messages on this channel
social_media_account.supported_message_typesarrayNoList of supported message types (currently only 'text')
social_media_account.supported_attachment_typesarrayNoList of supported attachment types (currently empty)
exitsarrayYesAvailable exits for routing the scenario
exits[].codestringYesExit code identifier
exits[].descriptionstringYesHuman-readable description
exits[].is_custombooleanYesTrue 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:

HeaderRequiredDescription
X-JWTYesThe JWT token string from jwt.token in the webhook request
AuthorizationYesBasic Auth with instance_id:application_secret
Content-TypeYesapplication/json

Body:

ParameterTypeRequiredDescription
codestringYesExit code (must match one from the webhook exits list)
messageobjectNoMessage to send to the user (null if no message)
message.typestringYes*Message type (currently only 'text' supported)
message.textstringYes*The AI-generated response text
variablesobjectYesDictionary 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 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