> ## Documentation Index > Fetch the complete documentation index at: https://docs.convocore.ai/llms.txt > Use this file to discover all available pages before exploring further. # Interact channel > Single bi-directional channel used to drive one agent turn. The client sends exactly one `InteractObject`; the server streams back chunked responses until it closes the connection (code `1000`). ## AsyncAPI ````yaml api-reference/asyncapi/interact.yaml interact id: interact title: Interact channel description: | Single bi-directional channel used to drive one agent turn. The client sends exactly one `InteractObject`; the server streams back chunked responses until it closes the connection (code `1000`). servers: - id: euProduction protocol: wss host: eu-gcp-api.vg-stuff.com bindings: [] variables: [] - id: naProduction protocol: wss host: na-gcp-api.vg-stuff.com bindings: [] variables: [] address: /interact parameters: [] bindings: - protocol: ws version: 0.1.0 value: method: GET schemaProperties: - name: method type: string description: GET required: false operations: - &ref_8 id: sendInteract title: Start an agent turn description: Open a session and send a single InteractObject to drive one agent turn. type: receive messages: - &ref_10 id: interactObject contentType: application/json payload: - name: Interact request description: The single payload the client sends after opening the socket. type: object properties: - name: agentId type: string description: The ID of the agent to interact with. examples: &ref_0 - agt_01HZX2K9ABC required: true - name: convoId type: string description: | The conversation ID. Reuse the same `convoId` across turns to keep history; use a fresh one to start a new conversation. examples: &ref_1 - conv_01HZX2K9XYZ required: true - name: bucket type: string description: > Region bucket. Use `voiceglow-eu` for EU and `(default)` for NA. enumValues: - voiceglow-eu - (default) required: true - name: prompt type: string description: | User message to send to the agent. Special values: - `"start"` — trigger the agent's initial greeting. - `"@cancel:"` — cancel the in-flight turn. - `"@rewind:"` — rewind a node-based conversation to a specific node. examples: &ref_2 - Hello, how can you help me? - start required: false - name: sessionId type: string description: Optional session id; defaults to `convoId` if omitted. required: false - name: messageType type: string description: > Type of input. Use `visual` together with `visualPayload` to send images. enumValues: - text - visual required: false - name: visualPayload type: object description: 'Image/visual content for `messageType: visual` turns.' required: false properties: - name: image type: string description: Primary image URL. required: false - name: images type: array description: Additional image URLs. required: false properties: - name: item type: string required: false - name: message type: string description: Optional caption / accompanying user message. required: false - name: imageCount type: integer required: false - name: replyTo type: object description: Reply context when the user is replying to a previous message. required: false properties: - name: messageId type: string required: false - name: messageContent type: string required: false - name: messageFrom type: string enumValues: - human - bot required: false - name: messageIndex type: integer required: false - name: turnIndex type: integer required: false - name: actionMetadata type: object required: false properties: - name: mid type: string description: Client-supplied message id (used for de-duplication). required: false - name: agentData type: object description: > Optional agent override. When provided with at least an `ID`, the server skips loading the agent doc from Firestore and uses this object instead. Mirrors `ChatRuntime`. required: false properties: - name: ID type: string required: false - name: ownerID type: string required: false - name: title type: string required: false - name: workspaceData type: object description: Optional workspace override (mirrors `WorkspaceModel`). required: false properties: - name: uid type: string required: false - name: email type: string required: false - name: turnsHistory type: array description: > Optional override of the conversation turns. When provided, the server uses this instead of fetching from Firestore. required: false properties: - name: from type: string enumValues: - bot - human required: false - name: ts type: number description: Unix timestamp (seconds). required: false - name: modelId type: string description: Model id that produced this turn (bot turns only). required: false - name: messages type: array required: false properties: - name: from type: string enumValues: - bot - human required: false - name: type type: string description: > Message type. Common values include `text`, `visual`, `cardV2`, `carousel`, `ui_engine_form`, `ui_engine_input`, `debug:tell`, `debug:error`, `debug:success`, `context:form_submission`. required: false - name: ts type: number required: false - name: mid type: string required: false - name: item type: object description: > Type-specific payload. Shape depends on `type`. For UI-engine agents, this is one of the `UiEngineMessage` shapes (text / choice / visual / cardV2 / carousel / iFrame / form / input). required: false properties: - name: type type: string description: > Message kind. `form` and `input` are only emitted on web channels (`web-chat` / `text`) when the agent has forms enabled. enumValues: - text - choice - visual - cardV2 - carousel - iFrame - form - input required: true - name: payload type: object description: Type-specific payload. See per-type schemas below. required: true properties: - name: message type: string description: Message content. Supports Markdown. required: false - name: buttons type: array required: true properties: - name: name type: string description: Visible label of the button. required: true - name: request type: object description: > What happens when the user clicks the button. Either opens a URL or sends a user message back into the conversation. required: true properties: - name: type type: string enumValues: - open_url - text required: true - name: payload type: object required: true properties: - name: url type: string description: > URL to open when the button is clicked. Must be a real URL pulled from the KB / tool output. required: true - name: message type: string description: User message that will be sent on click. required: true - name: image type: string description: > URL of the image. Must end with a valid image extension (`.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, ...). required: true - name: imageUrl type: string description: > Optional image URL. Must end with a valid image extension. required: false - name: title type: string description: Card title (supports Markdown). required: true - name: description type: object required: false properties: - name: text type: string description: Card description (supports Markdown). required: false - name: buttons type: array description: Optional call-to-action buttons. required: false properties: - name: name type: string description: Visible label of the button. required: true - name: request type: object description: > What happens when the user clicks the button. Either opens a URL or sends a user message back into the conversation. required: true properties: - name: type type: string enumValues: - open_url - text required: true - name: payload type: object required: true properties: - name: url type: string description: > URL to open when the button is clicked. Must be a real URL pulled from the KB / tool output. required: true - name: message type: string description: User message that will be sent on click. required: true - name: cards type: array required: true properties: - name: imageUrl type: string description: > Optional image URL. Must end with a valid image extension. required: false - name: title type: string description: Card title (supports Markdown). required: true - name: description type: object required: false properties: - name: text type: string description: Card description (supports Markdown). required: false - name: buttons type: array description: Optional call-to-action buttons. required: false properties: - name: name type: string description: Visible label of the button. required: true - name: request type: object description: > What happens when the user clicks the button. Either opens a URL or sends a user message back into the conversation. required: true properties: - name: type type: string enumValues: - open_url - text required: true - name: payload type: object required: true properties: - name: url type: string description: > URL to open when the button is clicked. Must be a real URL pulled from the KB / tool output. required: true - name: message type: string description: User message that will be sent on click. required: true - name: layout type: string description: > `vertical` for video embeds (YouTube etc.), `horizontal` for general web embeds. enumValues: - vertical - horizontal required: true - name: url type: string description: > Either a plain URL, or the full `