API Integration

API integration can be achieved in two ways: frontend and backend. The frontend approach directly calls the js API provided by the Copilot SDK, while the backend approach uses HTTP interfaces.

JS SDK API

1. Integrating via JS

The Copilot SDK provides a headless mode, which means you can interact with the backend through HTTP interfaces by simply calling the JS API without requiring a UI. This allows you to integrate the Copilot SDK into your existing frontend projects (e.g., your own AI assistant) by invoking the JS API wherever needed.

To enable headless mode, pass headless: true in the CopilotConfig. In this mode, the Copilot UI will not render on the page, and you can use the JS API to control Copilot's behavior.

Similar to the UI mode, the copilot instance returned after new Copilot provides the following Copilot states, data, and functions:

{
  api: {...},
  // Copilot state
  isLoading: false,
  // Current conversation list, data format reference:
  // https://api.hengshi.com/conversation.html#conversation
  conversations: [],
  setConversations: () => {},
  currentConversationId: null,
  setCurrentConversationId: () => {},
  runningChatUid: null,
  setRunningChatUid: () => {},
  setChat: (id, chatUid, chat) => {},
  // Fetch historical conversation list
  onFetchConversations: (offset = 0, limit = 10) => {},
  // Create a conversation
  onCreateConversation: prompt => {},
  onFetchConversation: id => {},
  onClearConversations: () => {},
  onFetchPreviousConversations: () => {},
  // Create Q&A
  onCreateChat: body => {},
  onDeleteChat: (id, chatUid) => {},
  onFetchSuggestions: refresh => {},
  onFetchFavorites: () => {},
  onCancelChatFavorite: (id, chatUid) => {},
  // Render chart
  renderChart: (container, { id, chart, chartTheme }) => {},
}

2. Calling HTTP API via JS

In the copilot example above, the api object provides all the methods for calling HTTP APIs. You can use these methods to interact with the backend, as shown below:

// 1. Create a conversation
const { body: { data: conversation }} = await copilot.api.requestCreateConversation({
  body: {
    title: 'This is the title of the conversation',
  },
}).value;
/**
conversation = {
  "id": 135,
  "title": "This is the title of the conversation",
  "createdBy": 268,
  "createdAt": "2024-09-14 15:47:23",
  "updatedBy": 268,
  "updatedAt": "2024-09-14 15:47:23"
}
*/
// 2. Create a Q&A
const { body: { data: chat }} = await copilot.api.requestCreateChat({
  id: conversation.id,
  body: {
    prompt: 'Which director has the highest-grossing movies?', // This is the user's question
    userConfig: { // Refer to the userConfig in the copilotConfig above
      dataAppId: 129150,
      datasetId: 1,
    }
  },
  qs: {
    sync: true, // Whether to execute synchronously
    timeout: 1000 * 60, // Timeout in milliseconds
  },
}).value;
/**
chat = {
    "conversationId": 135,
    "prompt": "Which director has the highest-grossing movies?",
    "answer": "Christopher Nolan has the highest-grossing movies.",
    "model": "gpt-4o",
    "uid": "08ff93ca-1972-4916-b884-35fab6f91c64",
    "temperature": 0,
    "createdBy": 268,
    "createdAt": "2024-09-14 15:47:23",
    "updatedBy": 268,
    "updatedAt": "2024-09-14 15:47:23",
    "responseAt": "2024-09-14 15:47:30",
    "isDelete": false,
    "isContextEnd": false,
    "suggestQuestions": [],
    "statusList": [
        "PENDING",
        "ANALYZE_REQUEST",
        "HQL_SELECT_FIELDS",
        "HQL_SELECT_FUNCTIONS",
        "GENERATE_HQL_QUERY",
        "DOING_HQL_QUERY",
        "DOING_SUMMARY",
        "DOING_QUESTION_SUGGESTING",
        "DONE"
    ],
    "userConfig": {
        "datasetId": 1,
        "dataAppId": 129150
    },
    "autoConfig": {
        "agentType": "HQL_AGENT"
    },
    "isCurrent": true,
    "usage": [
        {
            "completion_tokens": 24,
            "prompt_tokens": 4063,
            "total_tokens": 4087
        },
        {
            "completion_tokens": 5,
            "prompt_tokens": 1424,
            "total_tokens": 1429
        },
        {
            "completion_tokens": 49,
            "prompt_tokens": 3906,
            "total_tokens": 3955
        },
        {
            "completion_tokens": 16,
            "prompt_tokens": 299,
            "total_tokens": 315
        }
    ],
    "chartCreatedAt": "2024-09-14 15:47:30",
    "refineQuestion": "Which director has the highest-grossing movies?",
    "favorite": false,
    "charts": [
        {
            "appId": 129150,
            "datasetId": 1,
            "options": {
                "axes": [
                    {
                        "op": "{{1}}.{director}",
                        "uid": "uid1",
                        "fieldName": "director",
                        "kind": "formula",
                        "datasetId": 1,
                        "labelOrigin": "director",
                        "label": "director",
                        "isAggregate": false,
                        "value": "{{coffe_Products}}.{director}",
                        "dataset": 1,
                        "fieldType": "string"
                    },
                    {
                        "op": "max({{1}}.{votes})",
                        "uid": "uid2",
                        "fieldName": "votes",
                        "kind": "formula",
                        "datasetId": 1,
                        "labelOrigin": "votes",
                        "label": "votes",
                        "isAggregate": true,
                        "value": "max({{coffe_Products}}.{votes})",
                        "dataset": 1,
                        "fieldType": "number"
                    }
                ],
                "name": "Bar",
                "limit": 1,
                "sort": [
                    {
                        "op": "uid2",
                        "kind": "reference",
                        "direction": "desc"
                    },
                    {
                        "op": "uid1",
                        "kind": "reference",
                        "direction": "asc"
                    }
                ]
            },
            "dataAppId": 129150,
            "datasetIds": [
                1
            ]
        }
    ]
}
*/

Backend HTTP API Integration

For backend HTTP API integration, please refer to the API documentation: Complete API Call Example from User Query to Data Retrieval