Custom AI

Open in the app: AI Assistants (opens in a new tab)

Introduction

Custom AI lets you connect Bread Crumbs Bot to your own AI endpoint. When a message is processed by an AI with type: custom, Bot sends a request to your endpoint and uses your response text as the assistant reply.

Communication model

AI assistant integration uses request/response.

• Bread Crumbs sends a request with the conversation context/input
• Your AI endpoint processes it
• Your AI returns a response payload directly

This model is synchronous from Bread Crumbs point of view: one request in, one AI response back.

AI type

Use custom in AI creation operation.

Integration properties

Special keywords

In case the agent returns a response containing one of the following keywords, Bot will handle them specially:

• #HANDOVER#: Handover the conversation to an agent.
• #END#: End the conversation.

You can also control this behavior with a structured command field in your custom AI response:

• command: "HANDOVER"
• command: "END"

How it works

When a message is processed by an AI with type: custom, Bot sends a request to your endpoint and uses your response text as the assistant reply. So it will wait for your endpoint to process the message with AI and return the response. In case your endpoint returns a response with special keywords (or returns a command), Bot will handle them specially as described in the Special keywords section and will remove markers from the response text. So you can return something like this:

{
  "text": "I will forward this conversation to a live agent. Please wait a while...",
  "command": "HANDOVER"
}

Request payload example

Bot sends the message to your custom AI endpoint as POST <integrationProperties.endpoint> with the following JSON payload example:

{
  "externalClientId": "905301749170",
  "clientId": "6728c77dbba874b293e60000",
  "conversationId": "6728c86bf893860f458e0000",
  "workspaceId": 12,
  "integrationId": "6743884f784839ad14770000",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    },
    {
      "role": "assistant",
      "content": "Hello John! How can I help you today?"
    },
    {
      "role": "user",
      "content": "I want help in my account"
    },
  ]
}

Authorization header

We are using the API key to authorize the request to your endpoint. And to prevent unauthorized access to your endpoint if someone else tries to use it. The bot will send the API key as x-api-key header, you will need to validate it in your endpoint to ensure that the request is coming from the bot.

x-api-key: <integrationProperties.apiKey>

Expected response from your endpoint

Your endpoint should return JSON containing text at least. command is optional and currently supports END and HANDOVER.

{
  "text": "Hello! How can I help you today?",
  "command": "END",
  "usage": {
    "inputTokens": 42,
    "outputTokens": 18,
    "totalTokens": 60,
    "reasoningTokens": 0,
    "cachedInputTokens": 0
  },
  "traceId": "trace_123",
  "runId": "run_123",
  "finishReason": "stop"
}

Create custom AI (GraphQL)

mutation createAi($input: AICreateInput!) {
  createAi(input: $input) {
    id
    workspaceId
    name
    type
    integrationProperties
    createdAt
  }
}
 
input AICreateInput {
  workspaceId: Int!
  integrationProperties: JSON!
  name: String!
  type: AIType!
}

Next is an example of the input for the createAi mutation in JSON format:

{
  "input": {
    "workspaceId": 12,
    "name": "My Custom AI",
    "type": "custom",
    "integrationProperties": {
      "endpoint": "https://your-ai.example.com/generate",
      "apiKey": "your-custom-ai-key"
    }
  }
}

Related pages in the app

• AI Assistants (opens in a new tab)
• Channels (opens in a new tab)