Conversational Bot Integration

The Buzzeasy Conversational Bot 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 two main 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 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.

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.