Chat API Documentation

When would I use the Chat API?

The CopilotBuilder Chat API is a RESTful API that allows you to programmatically interact with the your deployed Copilots and Workflows. Use the Chat API when you want to integrate your Copilot or Workflow into your application, rather than using one of our UI-based deployment types.

Examples of Chat API usage scenarios:

• Integrate your Copilot or Workflow into a mobile app
• Send the Copilot or Workflow data that is only accessible from your application
• Perform actions with the result of Copilots or Workflows

How to use the Chat API

Before you begin

• Create and publish an API Deployment for your Copilot or Workflow
• Note the Deployment ID and API key for the deployment

Initialize the chat

First, you'll initialize the chat with the Copilot or Workflow with the Deployment ID. This creates a chat session that retains the history of the conversation. You will also send the API key in the X-API-KEY HTTP header.

Initialization endpoint

Example - cURL

You will receive a response in the format shown below (with your Copilot or Workflow details):

{
    "sessionId": "GUID of session",
    "expirationDate": "2024-04-20T15:44:30Z",
    "greeting": "Copilot/Workflow greeting'",
    "copilotName": "Name of Copilot/Workflow",
    "copilotDescription": "Description of Copilot/Workflow",
    "usesCustomData": true,
    "onlyUsesCustomData": true,
    "llm": "Semi-colon delimited list of the LLMs used by the Copilot or Workflow",
    "maxTokens": 1400
}

Take note of the sessionId, as you'll need it in requests to send messages the Copilot or Workflow.

The chat session has a sliding expiration of one hour. This expiration is updated every time a message is sent in the session.

Send a message to the Copilot or Workflow

Send message endpoint

Prepare the body of the request as shown below, providing the appropriate session and deployment identifiers:

{
  "sessionId": "string",
  "deploymentId": "string",
  "message": "string"
}

Example - cURL

curl --location 'https://api.copilotbuilder.ai/chat/SendMessage' \
--header 'x-api-key: {api key}' \
--header 'Content-Type: application/json' \
--data '{
    "deploymentId" : "{deployment id}",
    "sessionId": "{session id}",
    "message": "{message}"
}'

You will receive a response in the format shown below, which includes the latest result from the Copilot or Workflow, the new expiration date, and the entire history of the conversation:

{
  "expirationDate": "2024-04-20T15:16:38.920Z",
  "chatHistory": [
    {
      "modelId": "string",
      "metadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "mimeType": "string",
      "authorName": "string",
      "role": {
        "label": "string"
      },
      "items": [
        {
          "modelId": "string",
          "metadata": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          },
          "mimeType": "string"
        }
      ]
    }
  ],
  "latestMessages": [
    "string"
  ]
}