Conversation Management

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.

cURL

export INSTILL_API_TOKEN=********
curl -X GET 'https://api.instill.tech/v1alpha/namespaces/NAMESPACE_ID/apps/APP_ID/conversations' \
--header "Authorization: Bearer $INSTILL_API_TOKEN"

#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 to true, 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.

cURL

export INSTILL_API_TOKEN=********
curl -X PUT 'https://api.instill.tech/v1alpha/namespaces/NAMESPACE_ID/apps/APP_ID/conversations/CONVERSATION_ID' \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $INSTILL_API_TOKEN" \
--data '{
"newConversationId": "updated-conversation-id",
"lastUsedCatalogUid": "updated-catalog-uid",
"lastUsedTopK": 10
}'

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.

WARNING

Please note that once a conversation is deleted, all related messages and history will be permanently removed.

cURL

export INSTILL_API_TOKEN=********
curl -X DELETE 'https://api.instill.tech/v1alpha/namespaces/NAMESPACE_ID/apps/APP_ID/conversations/CONVERSATION_ID' \
--header "Authorization: Bearer $INSTILL_API_TOKEN"

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.