> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversations-interact.md). # Interact Send user messages to an active conversation and process streaming responses. ## Send a Message {% openapi src="" path="/v1/{organization}/conversation/{conversation\_id}/interact" method="post" %} {% endopenapi %} ## Form Parameters The request body is `multipart/form-data`. The external-event fields are repeatable: include one `--form` line per event. | Field | Type | Required | Repeatable | Description | | ---------------------------------- | -------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `initial_message_type` | string | Yes | No | The type of message being sent: `user-message` for user turns, `external-event` for external events, or `skip` to prompt the agent without a user message (with `skip`, `recorded_message` must be empty and no external-event fields may be sent). | | `recorded_message` | string or Blob | Yes | No | The user's message. Send plain text, or an audio clip when `request_format=voice` (MP3 or raw PCM, matching the `request_audio_config` query parameter). | | `external_event_message_content` | string | No | Yes | External event text to attach to this interaction. Omit if there are no external events. | | `external_event_message_timestamp` | string | No | Yes | ISO UTC timestamp, for example `2025-09-05T17:48:04.789560+00:00`. Provide exactly one timestamp per `external_event_message_content` entry, in chronological order. Each timestamp must be in the past and consistent with the conversation's existing message times, or the request fails with 400. | {% tabs %} {% tab title="cURL" %} ```bash curl --request POST \ --url 'https://api.amigo.ai/v1//conversation//interact?request_format=text&response_format=text' \ --header 'Authorization: Bearer ' \ --header 'Accept: application/x-ndjson' \ --header 'Content-Type: multipart/form-data' \ --form 'initial_message_type=user-message' \ --form 'recorded_message=Hello! Please tell me a fun fact.' \ --form 'external_event_message_content=The rain started.' \ --form 'external_event_message_timestamp=2025-09-05T17:48:04.789560+00:00' ``` {% endtab %} {% tab title="Python SDK" %} ```python from amigo_sdk import AmigoClient from amigo_sdk.models import InteractWithConversationParametersQuery full_response = "" with AmigoClient() as client: events = client.conversation.interact_with_conversation( conversation_id, InteractWithConversationParametersQuery( request_format="text", response_format="text", ), text_message="Hello! Please tell me a fun fact." ) for event in events: data = event.model_dump(mode="json") if data.get("type") == "new-message": chunk = data.get("message", "") full_response += chunk elif data.get("type") == "interaction-complete": break ``` {% endtab %} {% tab title="TypeScript SDK" %} ```typescript import { AmigoClient } from "@amigo-ai/sdk"; const client = new AmigoClient({ /* config */ }); let full = ""; const events = await client.conversations.interactWithConversation( conversationId, "Hello! Please tell me a fun fact.", { request_format: "text", response_format: "text" } ); for await (const evt of events) { if (evt.type === "new-message" && typeof evt.message === "string") { full += evt.message; } else if (evt.type === "interaction-complete") { break; } } ``` {% endtab %} {% endtabs %} ## Best Practices {% hint style="success" %} **Streaming Best Practices** * Always iterate the stream until `interaction-complete`. * Treat an `error` event received before `interaction-complete` as a rollback of the interaction; log and retry. If it arrives after `interaction-complete`, the interaction is saved -- call the Finish endpoint to retry the post-processing. * Use timeouts or abort controllers to bound request duration. * Keep track of returned IDs for diagnostics. {% endhint %} ## Dynamic Behavior → Metric Evaluation For how to react to `current-agent-action` events (`select-dynamic-behavior-completed`) and evaluate metrics, see Events → System Integration Flow ([conversations-events.md#system-integration-flow](/developer-guide/classic-api/core-api/conversations/conversations-events.md#system-integration-flow)). That page includes a sequence diagram and API examples for `metric/evaluate`. ## Finish the Conversation See [Lifecycle & Finish](/developer-guide/classic-api/core-api/conversations/conversations-lifecycle.md) to manually end a conversation and handle dangling sessions. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversations-interact.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.