Connecting to a custom content service

Use a custom service repository when your data is stored in an external system that is not natively supported, such as an internal database, private API, or proprietary document store. A custom service gives you complete control over how your agent retrieves data, including filtering, formatting, and access rules.

This setup also supports secure environments, such as those behind firewalls, and enables preprocessing of search results before they reach the agent.

You can host the custom service on either the server-side or the client-side, depending on your environment and security requirements.

For more information, see Set up instructions

Accessing the custom service repository

Connect your agent to the custom service repository to enable document search during runtime. This connection allows your agent to retrieve responses based on your organization’s external content, even when that content exists outside of supported systems.

You can use a custom service if your data is stored in a private environment, requires custom filters, or must pass through specific access rules or transformations before it can be displayed to users.

  1. In the Knowledge section, click Choose knowledge +.

  2. In Select source click Custom service > Next.

  3. In URL, enter the endpoint URL of the custom service repository.

  4. In Choose an authentication type, select one of three options:

    • Basic authentication: If you select Basic authentication, you must provide a username and password.
    • API Key: If you select API Key, you must provide the custom service repository API key.
    • None: If you select None, click Next.

  5. Click Next to configure the repository.

    Follow the steps to configure the Default filter and Metadata for your custom service connection:

  6. Default filter: Enter the default input value to be sent to the custom service. This can be plain text, JSON, or any other supported format.

  7. Metadata: Provide metadata in JSON format to define additional context or parameters for the service.

  8. Click Next to proceed.

  9. In the Knowledge details section,

  10. Click Save.

Managing custom service settings

To update your custom service configuration:

  1. In the Knowledge section, click Settings.
  2. Modify values in the Settings or Instance tab.
  3. Click Save to apply changes.

Deleting a custom service content repository

To delete a custom content repository:

  1. Go to the Knowledge section, click Settings.
  2. Open the Instance tab.
  3. Click Delete.

Setting up retrieval systems for a custom service

To use a custom service with your search integration, you must provide a server that returns results in a specific response schema. This ensures compatibility with the knowledge tool. If your retrieval schema matches the agent schema, you can use it directly. Otherwise, you’ll need a wrapper to map your schema to the agent schema. This wrapper can be deployed as a service or started by your chat client. Wrappers are useful when integrating non-compliant sources, libraries, or services.

Setting up a server for custom service retrieval

To set up a server for custom service retrieval, see the Setup guide. A server for custom service retrieval must implement the following API:

Query: POST <server_url>

Request

{
    "query": "<QUERY>",
    "filter": "<FILTER>", // optional
    "metadata": {
        // optional, you can fill any information here
    }
}

Response

{
    
  "search_results": [
    {
      "result_metadata": { // optional
        "score": <SCORE as a number>
      },
      "title": "<TITLE>",
      "body": "<BODY>",
      "url": "<URL>", // optional
      "highlight": { // optional, will be used instead of "body" for Conversational Search if provided
        "body": [
          "<HIGHLIGHT1>",
          "<HIGHLIGHT2>",
           ...
        ]
      }
    }
  ]

}

The metadata in the request and the entire response object must not exceed 100 KB.