Context Chat

Added in version 32.0.0.

Nextcloud offers a Context Chat API which allows apps to submit data to the Nextcloud Assistant Context Chat, thereby enabling Nextcloud Assistant to answer questions and provide insights based on the submitted data.

Implementing a content provider for Context Chat

The IContentProvider interface

A content provider for Context Chat needs to implement the \OCP\ContextChat\IContentProvider interface:

/**
 * This interface defines methods to implement a content provider
 * @since 32.0.0
 */
interface IContentProvider {
    /**
     * The ID of the provider
     *
     * @return string
     * @since 32.0.0
     */
    public function getId(): string;

    /**
     * The ID of the app making the provider available
     *
     * @return string
     * @since 32.0.0
     */
    public function getAppId(): string;

    /**
     * The absolute URL to the content item
     *
     * @param string $id
     * @return string
     * @since 32.0.0
     */
    public function getItemUrl(string $id): string;

    /**
     * Starts the initial import of content items into context chat
     *
     * @return void
     * @since 32.0.0
     */
    public function triggerInitialImport(): void;
}

The triggerInitialImport method is called when Context Chat is first set up and allows your app to import all existing content into Context Chat in one bulk. Any other items that are created afterwards will need to be added on demand.

Using the IContentManager service

To add content and register your provider implementation you will need to use the \OCP\ContextChat\IContentManager service.

The IContentManager class has the following methods:

registerContentProvider(string $providerClass)

submitContent(string $appId, array $items): Providers can use this to submit content for indexing in Context Chat.

updateAccess(string $appId, string $providerId, string $itemId, string $op, array $userIds): Update the access rights for a content item. Use \OCP\ContextChat\Type\UpdateAccessOp constants for the $op value.

updateAccessProvider(string $appId, string $providerId, string $op, array $userIds): Update the access rights for all content items from a provider. Use \OCP\ContextChat\Type\UpdateAccessOp constants for the $op value.

updateAccessDeclarative(string $appId, string $providerId, string $itemId, array $userIds): Update the access rights for a content item. This method is declarative and will replace the current access rights with the provided ones.

deleteProvider(string $appId, string $providerId): Remove all content items of a provider from the knowledge base of Context Chat.

deleteContent(string $appId, string $providerId, array $itemIds): Remove specific content items from the knowledge base of Context Chat.

Implementing the ContentProviderRegisterEvent event

To register your content provider, your app needs to listen to the OCP\ContextChat\Events\ContentProviderRegisterEvent event and call the registerContentProvider method in the event for every provider you want to register.

Some partial implementations of Application.php and a ContentProvider for reference:

use OCA\MyApp\ContextChat\ContentProvider;
use OCP\ContextChat\Events\ContentProviderRegisterEvent;
// ...
$context->registerEventListener(ContentProviderRegisterEvent::class, ContentProvider::class);

class ContentProvider implements IContentProvider {
// ...
public function handle(Event $event): void {
    if (!$event instanceof ContentProviderRegisterEvent) {
        return;
    }
    $event->registerContentProvider('***appId***', '***providerId***', ContentProvider::class);
}

Any interaction with the content manager using the ContentManager’s methods or listing the providers in the Assistant should automatically register the provider.

You may call the registerContentProvider method explicitly if you want to trigger an initial import of content items.

Submitting ContentItem data

To submit content, wrap it in an \OCP\ContextChat\ContentItem object:

new ContentItem(
        string $itemId,
        string $providerId,
        string $title,
        string $content,
        string $documentType,
        \DateTime $lastModified,
        array $users,
    )

Note

Ensure that item IDs are unique across all users for a given provider.
The app ID and provider ID both cannot contain double underscores, spaces, or colons.
The documentType is a natural language term for your document type in English, e.g. E-Mail or Bookmark.