Chat App API

API for Chatbot and Legacy Agent apps, covering chat messages, conversation management, file uploads, voice, and annotations

Chatbot apps (chat mode) and Legacy Agent apps (agent-chat mode) share the same endpoints to send messages, manage conversations, handle files, and retrieve app settings. Only the streamed reply differs: Chatbot apps stream the reply as message events, while Legacy Agent apps stream agent_thought and agent_message events.

Authentication, the base URL, and the user field that scopes end-user data are covered in Get Started and End User Identity.

Send Messages and Stream Replies

• Send Chat Message: send a query to your Chatbot or Legacy Agent app. Blocking mode returns the full reply once it finishes; Legacy Agent apps support streaming mode only.
• Stop Chat Message Generation: interrupt a streaming reply before it finishes.
• Get Next Suggested Questions: propose follow-up questions after a reply completes, based on the conversation so far.

Manage Conversations

Conversations created through the API stay isolated from conversations started in the app’s web app.

• List Conversations: the current user’s conversations, ordered by most recent activity.
• List Conversation Messages: one conversation’s message history, for a scrolling chat UI.
• Rename Conversation: set or auto-generate a display name.
• Delete Conversation: remove a conversation.
• List Conversation Variables: read the values the session persists across turns.
• Update Conversation Variable: change one of those values directly.

Handle Files

• Upload File: upload an image, document, audio, or video file for Send Chat Message to reference. Files are scoped to the uploading end user.
• Download File: preview or download an uploaded file, as long as it belongs to a message in your app.
• Get End User Info: look up an end user’s details from an end-user ID, such as the created_by in the Upload File response.

Transcribe and Synthesize Speech

• Convert Audio to Text: transcribe an uploaded audio file (MP3, M4A, WAV, AMR, or MPGA, up to 30 MB) so end users can speak their input instead of typing it.
• Convert Text to Audio: synthesize a reply back into speech.

Retrieve App Info and Settings

• Get App Info: the app’s name, description, tags, and mode.
• Get App Parameters: the fields your calls send in inputs (names, types, defaults) plus the app’s feature switches—the basis for building requests or a client UI.
• Get App Meta: tool icons and other configuration metadata.
• Get App WebApp Settings: the web app’s site configuration, theme, and customization options.

Collect Feedback

• Submit Message Feedback: end users rate a reply as like or dislike, with an optional text comment.
• List App Feedbacks: every feedback submitted across the app, from both end users and admins.

Manage Annotations

Annotations pair a question with a fixed answer that the app returns directly instead of generating a new response:

• Create Annotation, List Annotations, Update Annotation, Delete Annotation: manage the annotation set.
• Configure Annotation Reply: turn annotation matching on or off. The change runs asynchronously.
• Get Annotation Reply Job Status: poll with the returned job ID to confirm the change finished.