Instill AI provides a set of methods for conversation management, including listing, updating, and deleting conversations within your AI Assistant apps. Effective conversation management allows you to maintain context, manage user interactions, and enhance the overall user experience.
Conversation management features within Instill Console are coming soon. In the meantime, you can use the API methods described below to manage your conversations programmatically.
#Manage Conversations via API
#List Conversations
This endpoint returns a list of conversations associated with a specific AI Assistant app, including their metadata.
#Query Parameters (Optional)
pageSize
(integer): The number of conversations to return in the response.pageToken
(string): A token identifying a page of results the server should return.conversationUid
(string): If provided, only the conversation with the given UID will be returned.conversationId
(string): If provided, only the conversation with the given ID will be returned.ifAll
(boolean): If set totrue
, all conversations will be returned, overriding other pagination parameters.
#Example Response
A successful response will return a JSON object containing a list of your conversations:
{ "conversations": [ { "uid": "generated-conversation-uid-1", "namespaceId": "your-namespace-id", "appId": "your-app-id", "id": "conversation-id-1", "lastUsedCatalogUid": "catalog-uid-1", "lastUsedTopK": 5, "createTime": "2024-10-07T12:34:56Z", "updateTime": "2024-10-07T12:34:56Z" }, { "uid": "generated-conversation-uid-2", "namespaceId": "your-namespace-id", "appId": "your-app-id", "id": "conversation-id-2", "lastUsedCatalogUid": "catalog-uid-2", "lastUsedTopK": 3, "createTime": "2024-10-08T09:21:34Z", "updateTime": "2024-10-08T09:21:34Z" } ], "nextPageToken": "next-page-token", "totalSize": 2}
#Update Conversation
This endpoint allows you to update a conversation's details, such as its ID, last used Catalog UID, and last used top K value.
Note:
- Replace
NAMESPACE_ID
with your namespace ID. - Replace
APP_ID
with the ID of the app containing the conversation. - Replace
CONVERSATION_ID
with the ID of the conversation you want to update.
#Body Parameters
newConversationId
(string, optional): The new ID for the conversation. Must be in kebab-case format.lastUsedCatalogUid
(string, optional): The UID of the last used Catalog.lastUsedTopK
(integer, optional): The last used top K value for searches.
#Example Response
A successful response will return the updated conversation details:
{ "conversation": { "uid": "generated-conversation-uid", "namespaceId": "your-namespace-id", "appId": "your-app-id", "id": "updated-conversation-id", "lastUsedCatalogUid": "updated-catalog-uid", "lastUsedTopK": 10, "createTime": "2024-10-07T12:34:56Z", "updateTime": "2024-10-09T08:22:10Z" }}
#Delete Conversation
This endpoint allows you to delete a conversation from your AI Assistant app.
Please note that once a conversation is deleted, all related messages and history will be permanently removed.
A successful response will return an empty JSON object, indicating that the conversation has been deleted.
The NAMESPACE_ID
, APP_ID
, and CONVERSATION_ID
path parameters must be replaced with the app
owner's ID, the app ID, and the conversation ID respectively.