Message Management | Documentation

Instill AI provides a set of methods for message management, including listing, updating, and deleting messages within conversations in your AI Assistant apps. Effective message management allows you to maintain conversation context, manage user interactions, and enhance the overall user experience.

Message management features within the Instill Console are coming soon. In the meantime, you can use the API methods described below to manage your messages programmatically. When interacting with messages in the console interface, clicking on a specific message will display its UID, which you can use with the APIs too.

#Manage Messages via API

#List Messages

This endpoint returns a list of messages associated with a specific conversation, including their content and metadata.

cURL

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

#Query Parameters (Optional)

latestK (integer): Returns the latest K messages.
pageSize (integer): The number of messages to return in the response.
pageToken (string): A token identifying a page of results the server should return.
includeSystemMessages (boolean): If set to true, system messages will be included in the response.
ifAll (boolean): If set to true, all messages will be returned, overriding other pagination parameters.
messageUid (string): If provided, only the message with the given UID will be returned.

#Example Response

A successful response will return a JSON object containing a list of messages:

{
  "messages": [
    {
      "uid": "generated-message-uid-1",
      "appUid": "your-app-uid",
      "conversationUid": "your-conversation-uid",
      "content": "Hello, what is Instill Applications / AI Assistant?",
      "role": "user",
      "type": "MESSAGE_TYPE_TEXT",
      "createTime": "2024-10-09T12:34:56Z",
      "updateTime": "2024-10-09T12:34:56Z",
      "msgSenderUid": "assistant-uid"
    },
    {
      "uid": "generated-message-uid-2",
      "appUid": "your-app-uid",
      "conversationUid": "your-conversation-uid",
      "content": "The AI Assistant integrates with the Catalog to provide natural language interactions and RAG-based responses for enhanced user experience.",
      "role": "assistant",
      "type": "MESSAGE_TYPE_TEXT",
      "createTime": "2024-10-08T12:35:10Z",
      "updateTime": "2024-10-08T12:35:10Z",
      "msgSenderUid": "your-user-uid"
    }
  ],
  "nextPageToken": "next-page-token",
  "totalSize": 2,
  "senderProfiles": [
    {
      "msgSenderUid": "assistant-uid",
      "msgSenderId": "assistant",
      "displayName": "AI Assistant",
      "avatar": "https://example.com/avatar/assistant.png"
    },
    {
      "msgSenderUid": "your-user-uid",
      "msgSenderId": "user123",
      "displayName": "John Doe",
      "avatar": "https://example.com/avatar/user123.png"
    }
  ]
}

#Update Message

This endpoint allows you to update the content of a specific message within a conversation.

cURL

export INSTILL_API_TOKEN=********
curl -X PUT 'https://api.instill.tech/v1alpha/namespaces/NAMESPACE_ID/apps/APP_ID/conversations/CONVERSATION_ID/messages/MESSAGE_UID' \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $INSTILL_API_TOKEN" \
--data '{
  "content": "Updated message content"
}'

#Body Parameters

content (string, required): The new content for the message.

#Example Response

A successful response will return the updated message details:

{
  "message": {
    "uid": "generated-message-uid",
    "appUid": "your-app-uid",
    "conversationUid": "your-conversation-uid",
    "content": "Updated message content",
    "role": "user",
    "type": "MESSAGE_TYPE_TEXT",
    "createTime": "2024-10-08T12:35:10Z",
    "updateTime": "2024-10-09T08:22:10Z",
    "msgSenderUid": "your-user-uid"
  }
}

#Delete Message

This endpoint allows you to delete a specific message from a conversation.

WARNING

Please note that once a message is deleted, it will be permanently removed and cannot be recovered.

cURL

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

A successful response will return an empty JSON object, indicating that the message has been deleted.

The NAMESPACE_ID, APP_ID, CONVERSATION_ID, and MESSAGE_UID path parameters must be replaced with the app owner's ID, the app ID, the conversation ID and the message UID respectively.