Conversational Bot Integration

The Conversational Bot Integration allows you to seamlessly extend your bot's capabilities by interfacing with external systems. By handling BotIntegrationCallRequest and providing a rich BotIntegrationCallResponse, you maintain full control over the conversation's flow, enabling personalized and context-aware user experiences.

Leverage this integration to enhance automation, deliver instant information, and create more human-like, responsive conversations—all without burdening your support team with repetitive inquiries. Integration feature allows you to enhance the bot’s capabilities by calling out to external APIs or systems during a conversation. This way, you can fetch data, perform actions, and return results dynamically without human intervention.

When the conversation flow reaches a point that requires external logic, Buzzeasy will send a HTTP POST request withBotIntegrationCallRequest body to your configured endpoint. Your service should process this request and return a BotIntegrationCallResponse with any updated workflow data and the results of the requested action.

---

This guide is separated into multiple parts:

• How can you configure the Conversational Bot Integration in the Buzzeasy Portal? Administration Guide
• How can you implement the middleware that handles the BotIntegrationCallRequest and returns the BotIntegrationCallResponse? (this document)
• How can you configure and implement external attachment processing? Attachment External Processing

The Middleware Concept

Why Use a Middleware?

The middleware sits between Buzzeasy and your external system, serving as a critical translation layer. While it might seem simpler to connect directly to your APIs, production use cases almost always require this intermediate layer for several important reasons:

1. API Complexity Management

Most external APIs have complex request schemas that are not suitable for direct LLM consumption. You might need to:

• Separate data collection into multiple steps
• Transform complex nested request structures into simpler formats
• Handle authentication and security requirements that are too complex for the bot

2. Response Processing and Filtering

External APIs often return extensive data that contains more information than needed. The middleware allows you to:

• Filter out unnecessary details
• Simplify complex response structures for the LLM
• Pre-process and format data in a way that's optimized for conversational flow

3. State Management

The middleware provides an additional layer for state management, allowing you to:

• Store conversation states and context
• Outsource decision-making to the integration rather than relying solely on the LLM
• Maintain persistent data across multiple conversation turns

4. Leverage Integration Strengths

Use integrations to create tools for tasks where LLMs are not optimal:

• Deterministic Decision-Making: Tasks that require precise, rule-based logic
• Mathematical Operations: Calculating interest rates, comparing numbers, or performing complex calculations
• Data Validation: Ensuring data integrity and business rule compliance
• External System Orchestration: Coordinating multiple API calls or complex workflows

Real-World Benefits

In production environments, this middleware approach provides:

• Reliability: Consistent, predictable responses for critical business operations
• Performance: Optimized data exchange between systems
• Security: Controlled access to sensitive external systems
• Maintainability: Centralized logic for external system interactions

How It Works

1. Triggering an Integration Call:
   During the conversation, the Conversational bot can call an integration to be able to generate answer to the customer. When the bot hits this point, Buzzeasy sends a POST request to your endpoint with the BotIntegrationCallRequest payload.

2. Processing the Request:
   Your server receives the request and uses the provided information—such as ActionCallParameters and WorkflowData—to interact with external systems. For example, it can:

   • Retrieve account information
   • Process a refund
   • Fetch order status details
   • Perform other domain-specific actions The ActionCallParameters will include the parameters what the bot collected based on your Integration definition.

3. Returning the Response:
   After completing the external action, your server responds with a BotIntegrationCallResponse. This includes any updated WorkflowData and ActionCallResponse information that the bot can use to continue the conversation logically.

Request Payload (BotIntegrationCallRequest)

The BotIntegrationCallRequest DTO represents the incoming request from Buzzeasy to your endpoint:

public class BotIntegrationCallRequest
{
    public required string ConversationId { get; set; }
    public string? CustomerIdentifier { get; set; }
    public string? CustomerId { get; set; }
    public MediaGroup MediaGroup { get; set; }
    public Dictionary<string, string> WorkflowData { get; set; } = new();
    public required JObject ActionCallParameters { get; set; }
}

Properties:

• ConversationId (required): A unique identifier for the ongoing conversation.
• CustomerIdentifier (optional): A string that may represent the customer’s identity (e.g., email, phone, account ID).
• CustomerId (optional): A unique customer ID, if available.
• MediaGroup: (required): Indicates the media channel (e.g., Chat, Email, Voice) through which the conversation is happening.
• WorkflowData: (required): A dictionary containing current workflow data key-value pairs that have accumulated so far. This can include previous steps, user inputs, or context that the bot has gathered.
• ActionCallParameters (required): A JSON object containing the parameters needed to perform the desired action. The structure and content of this object will depend on the specific action the bot is requesting based on your integration definition. The bot will collect these parameters from the user during the conversation.

Example Request JSON Schema

Below is a representative JSON schema for the request body that Buzzeasy sends to your endpoint:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "ConversationId": {
      "type": "string"
    },
    "CustomerIdentifier": {
      "type": ["string", "null"]
    },
    "CustomerId": {
      "type": ["string", "null"]
    },
    "MediaGroup": {
      "type": "string"
    },
    "WorkflowData": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "ActionCallParameters": {
      "type": "object"
    }
  },
  "required": ["ConversationId", "ActionCallParameters", "MediaGroup", "WorkflowData"]
}

Example Request Payload

{
  "ConversationId": "1234-abc",
  "CustomerIdentifier": "john.doe@example.com",
  "CustomerId": "cust-789",
  "MediaGroup": "Email",
  "WorkflowData": {
    "PriorityCustomer": "true"
  },
  "ActionCallParameters": {
    "OrderId": "4567"
  }
}

In this example, the bot is asking your service to get details about an order using the specified parameters.

Response Payload (BotIntegrationCallResponse)

Your endpoint should return a BotIntegrationCallResponse:

public class BotIntegrationCallResponse
{
    public Dictionary<string, string> WorkflowData { get; set; } = new();
    public required JObject ActionCallResponse { get; set; }
}

Properties:

• WorkflowData: (required): Any updates or new key-value pairs to be merged back into the Buzzeasy conversation workflow data. These may be new facts discovered by the external call, such as “OrderStatus”: “Shipped.”
• ActionCallResponse (required): A JSON object containing the results of the requested action. This will be used by the bot to inform the next steps in the conversation. For instance, if you fetched order details, you might return them here so the bot can share them with the customer.

Example Response JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "WorkflowData": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "ActionCallResponse": {
      "type": "object"
    }
  },
  "required": ["ActionCallResponse", "WorkflowData"]
}

Example Response Payload

{
  "WorkflowData": {
    "OrderStatus": "Shipped",
    "ShippingCarrier": "DHL"
  },
  "ActionCallResponse": {
    "OrderDetails": {
      "OrderId": "4567",
      "Items": [
        { "Name": "Wireless Mouse", "Quantity": 1 },
        { "Name": "Laptop Stand", "Quantity": 2 }
      ],
      "EstimatedDelivery": "2024-12-20"
    }
  }
}

In this example, the external system returns updated workflow data (OrderStatus, ShippingCarrier) and detailed order information (ActionCallResponse). The bot can use this data to inform the customer about the order’s shipping status and expected delivery date.

Middleware Communication Requirements

HTTP Response Standards

When implementing your middleware endpoint, follow these communication requirements:

Response Code

• Always return HTTP 200 OK for successful processing
• Return 200 even when your business logic encounters expected errors (e.g., "order not found")
• Use the ActionCallResponse payload to communicate business-level errors or results to the LLM

Design Philosophy

This integration is not RESTful by design. It is intentionally designed as a simplified, RPC-style (Remote Procedure Call) endpoint.

• Optimized for AI: Unlike traditional REST APIs that expose resources, this endpoint is optimized for consumption by an LLM. It prioritizes simplicity and a clear, single-purpose interaction.
• Focus on Action, Not Resources: The design is centered around executing a specific action described in the payload, rather than manipulating a resource via different HTTP methods.
• Clear, Structured Payloads: The goal is to provide a clear, structured request and expect a similarly structured response that the conversational AI can easily parse and act upon without needing to navigate a complex API.

Error Handling

• Use HTTP error codes (4xx, 5xx) only for genuine technical failures where you want to continue the conversation flow on the current bot node failure path in the workflow.
• For business logic errors (e.g., invalid order ID), return 200 OK with error details in ActionCallResponse

Content Type

• Always set Content-Type: application/json for responses
• Ensure your JSON response is properly formatted and valid

Example Error Responses

Business Logic Error (HTTP 200):

{
  "WorkflowData": {
    "LastError": "OrderNotFound"
  },
  "ActionCallResponse": {
    "Success": false,
    "ErrorMessage": "Order 4567 was not found in the system",
    "ErrorCode": "ORDER_NOT_FOUND"
  }
}

Handling Authentication and Security

• API Key: Buzzeasy includes an x-api-key header in the request. Validate this key to ensure the request is legitimate.
• HTTPS: Use HTTPS endpoints to secure data in transit.

Summary

The Conversational Bot Integration allows you to seamlessly extend your bot’s capabilities by interfacing with external systems. By handling BotIntegrationCallRequest and providing a rich BotIntegrationCallResponse, you maintain full control over the conversation’s flow, enabling personalized and context-aware user experiences.

Leverage this integration to enhance automation, deliver instant information, and create more human-like, responsive conversations—all without burdening your support team with repetitive inquiries.