About the Containers Chat API

The Containers Chat API manages conversations and messages for the Wix AI coding agent. Use this API to add the coding agent's chat experience to your app, so users can send requests, follow the agent's progress, and read its responses.

With the Containers Chat API, you can:

• Create and manage conversations for a project.
• Send user messages to the coding agent.
• Answer clarifying questions from the coding agent.
• Read a conversation's message history, including responses that are still in progress.

Conversations and messages

A conversation is a chat thread about a single project. A project can have multiple conversations. A conversation holds the thread's details, such as its status and title. The messages in a conversation are returned separately by Query Messages.

Each message has a role that shows who sent it, a status that shows its progress, and a type that shows where its content is stored.

The message lifecycle

When you call Send Message, 2 messages are created:

1. The user message, with DONE status.
2. An assistant message with WORKING status. Its inReplyToId is the ID of the user message.

While the coding agent works, the assistant message's tasks field holds a live checklist of the agent's work items. When the agent finishes, the assistant message's status changes to DONE. If the agent fails, the status changes to ERROR, and parts contains the reason for the failure.

Message types

The message's type determines which field holds its content:

Type	Sent by	Content
TEXT	User or assistant	Conversational content, in parts. This is the default type.
QUESTIONNAIRE	Assistant	Questions the agent needs answered before it continues, in questionnairePayload.
QUESTIONNAIRE_RESPONSE	User	The user's answers to a QUESTIONNAIRE message, in questionnaireResponsePayload.
CHECKPOINT	Assistant	A marker for a saved version of the project, in checkpointPayload. A checkpoint isn't a reply to a user message, so it has no inReplyToId. Show it in the conversation as a version marker.

To answer a QUESTIONNAIRE message, call Send Message with type set to QUESTIONNAIRE_RESPONSE. In questionnaireResponsePayload, specify the ID of the QUESTIONNAIRE message and the user's answers, keyed by question ID. The questionnaire's status then changes to ANSWERED.

Tracking the assistant's response

The API doesn't push updates in real time. After you call Send Message, poll Query Messages until the assistant message's status changes from WORKING to DONE or ERROR. Then check the message's type:

• TEXT: The response is in parts. Suggested next questions are in followUpQuestionOptions.
• QUESTIONNAIRE: The questions are in questionnairePayload.

Before you begin

It's important to note the following points before starting to code:

• This API is in Beta.
• Conversations belong to a project. You need the project's ID to create a conversation.
• Send Message requires an idempotencyKey. Use a unique key for each user message. The key doesn't prevent duplicates, so a retried request creates a new user message. Before you retry a failed request, call Query Messages to check whether the user message was created.
• New conversations always have ACTIVE status and the title new chat.
• A conversation's sessionId is set automatically when the coding agent starts building the project. You don't need to set it.

Use cases

• Send a message and track the assistant's response
• Answer a clarifying questionnaire

Terminology

• Conversation: A chat thread about a project. A project can have multiple conversations.
• Message: A single turn in a conversation, sent by the user or by the coding agent.
• Assistant message: A message from the coding agent. It starts with WORKING status and changes to DONE or ERROR.
• Task: A work item that the coding agent shows in a live checklist on an assistant message while it works.
• Questionnaire: A set of questions that the coding agent needs answered before it continues.
• Checkpoint: A message that marks a saved version of the project.