chat mode) and 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 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 Agent app. Blocking mode returns the full reply once it finishes; 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 WebApp.- 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_byin 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 WebApp’s site configuration, theme, and customization options.
Collect Feedback
- Submit Message Feedback: end users rate a reply as
likeordislike, 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.