# Interact

Send user messages to an active conversation and process streaming responses.

## Send a Message

## Interact with a conversation

> Send a new user message to the conversation. The endpoint will perform analysis and generate an agent message in response.\
> \
> A \`UserMessageAvailableEvent\` will be the first event in the response, which includes the user message if it's sent as text, or the transcribed message if it's sent as voice.\
> A series of \`CurrentAgentActionEvent\`s will follow, which indicates steps in the agent's thinking process. Then the agent message is generated sequentially in pieces, with each piece\
> being sent as a \`NewMessageEvent\` in the response. After all the pieces are sent, an \`InteractionCompleteEvent\` is sent. Depending on the \`conversation\_completed\` property in this event, the conversation will be awaiting\
> a new message from the user, or it might automatically end (for instance, because the user message indicates the user wants to end the session), while the conversation is marked as finished and the post-conversation\
> analysis asynchronously initiated. The connection will then terminate.\
> \
> Any further action on the conversation is only allowed after the connection is terminated.\
> \
> A 200 status code doesn't indicate the successful completion of this endpoint, because the status code is transmitted before the stream starts. At any point during the stream,\
> an \`ErrorEvent\` might be sent, which indicates that an error has occurred. The connection will be immediately closed after.\
> \
> This endpoint can only be called on a conversation that has started but not finished.\
> \
> \#### Permissions\
> This endpoint requires the following permissions:\
> \* \`User:UpdateUserInfo\` on the user who started the conversation.\
> \* \`Conversation:InteractWithConversation\` on the conversation.\
> \
> This endpoint may be impacted by the following permissions:\
> \* \`CurrentAgentActionEvent\`s are only emitted if the authenticated user has the \`Conversation:GetInteractionInsights\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Amigo API","version":"0.1.0"},"servers":[{"url":"https://api.amigo.ai"},{"url":"https://internal-api.amigo.ai"},{"url":"https://api-eu-central-1.amigo.ai"},{"url":"https://api-ap-southeast-2.amigo.ai"},{"url":"https://api-ca-central-1.amigo.ai"}],"security":[{"Bearer-Authorization":[],"Bearer-Authorization-Organization":[],"Basic":[]}],"components":{"securitySchemes":{"Bearer-Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint."}},"schemas":{"UserMessageAudioConfig":{"oneOf":[{"$ref":"#/components/schemas/MP3UserMessageAudioConfig"},{"$ref":"#/components/schemas/PCMUserMessageAudioConfig"}],"discriminator":{"propertyName":"type","mapping":{"mp3":"#/components/schemas/MP3UserMessageAudioConfig","pcm":"#/components/schemas/PCMUserMessageAudioConfig"}}},"MP3UserMessageAudioConfig":{"properties":{"type":{"type":"string","const":"mp3","title":"Type","default":"mp3"}},"type":"object","title":"MP3UserMessageAudioConfig"},"PCMUserMessageAudioConfig":{"properties":{"type":{"type":"string","const":"pcm","title":"Type","default":"pcm"},"frame_rate":{"type":"integer","maximum":44100,"minimum":4000,"title":"Frame Rate"},"n_channels":{"type":"integer","const":1,"title":"N Channels"},"sample_width":{"type":"integer","enum":[2,4],"title":"Sample Width"}},"type":"object","required":["frame_rate","n_channels","sample_width"],"title":"PCMUserMessageAudioConfig"},"src__app__endpoints__conversation__interact_with_conversation__Response":{"anyOf":[{"$ref":"#/components/schemas/ConversationEvent"},{"$ref":"#/components/schemas/UserMessageAvailableEvent"},{"$ref":"#/components/schemas/ErrorEvent"}]},"ConversationEvent":{"anyOf":[{"$ref":"#/components/schemas/InteractionCompleteEvent"},{"$ref":"#/components/schemas/NewMessageEvent"},{"$ref":"#/components/schemas/CurrentAgentActionEvent"}]},"InteractionCompleteEvent":{"properties":{"type":{"type":"string","const":"interaction-complete","title":"Type","default":"interaction-complete"},"message_id":{"type":"string","title":"Message Id","description":"The identifier of the agent message in this interaction."},"interaction_id":{"type":"string","title":"Interaction Id","description":"The identifier of this interaction."},"full_message":{"type":"string","title":"Full Message","description":"A structure containing either the content of the message if it's text, or the transcript of the message if it's audio."},"conversation_completed":{"type":"boolean","title":"Conversation Completed","description":"Whether the conversation is auto-completed after this interaction."}},"type":"object","required":["message_id","interaction_id","full_message","conversation_completed"],"title":"InteractionCompleteEvent","description":"Emitted when the interaction is complete and committed to database. This event is only emitted after all `NewMessageEvent`s are emitted."},"NewMessageEvent":{"properties":{"type":{"type":"string","const":"new-message","title":"Type","default":"new-message"},"message":{"type":"string","title":"Message","description":"Either the raw-text piece or a base-64 encoded string of bytes representing the piece in alternative forms. If it represents audio, the audios are in\nPCM16 format."},"transcript_alignment":{"anyOf":[{"items":{"prefixItems":[{"type":"integer"},{"type":"string"}],"type":"array","maxItems":2,"minItems":2},"type":"array"},{"type":"null"}],"title":"Transcript Alignment","description":"Transcript of the ongoing audio message and how they align with the audio, if the message is in audio format. Otherwise, it's `None`. This is an array of tuples, where each tuple contains\na character and an integer indicating the milliseconds since the audio started when the character is spoken.\n\nNote that this field might not be defined for some events that transmit audio bytes -- in that case, the alignment information for that chunk was already\nincluded in the `transcript_alignment` field in the previous event."},"stop":{"type":"boolean","title":"Stop","description":"Whether this is the last piece of the agent message."},"sequence_number":{"type":"integer","title":"Sequence Number","description":"The sequence number of this piece in the agent message."},"message_id":{"type":"string","title":"Message Id","description":"The identifier of this agent message. "}},"type":"object","required":["message","transcript_alignment","stop","sequence_number","message_id"],"title":"NewMessageEvent","description":"Emitted when a new piece of the agent message is available."},"CurrentAgentActionEvent":{"properties":{"type":{"type":"string","const":"current-agent-action","title":"Type","default":"current-agent-action"},"action":{"$ref":"#/components/schemas/src__app__amigo__service__conversation__Action","description":"The type of action the agent is performing right now."}},"type":"object","required":["action"],"title":"CurrentAgentActionEvent","description":"Emitted when an agent is about to perform an action that aids in the generation of the response. This is emitted before any\n`NewMessageEvent` is emitted."},"src__app__amigo__service__conversation__Action":{"anyOf":[{"$ref":"#/components/schemas/SelectDynamicBehaviorAgentActionEvent"},{"$ref":"#/components/schemas/CheckIfActiveMemoryNeededAgentActionEvent"},{"$ref":"#/components/schemas/ExtractActiveMemoriesAgentActionEvent"},{"$ref":"#/components/schemas/NavigateStateMachineAgentActionEvent"},{"$ref":"#/components/schemas/EngageUserAgentActionEvent"}]},"SelectDynamicBehaviorAgentActionEvent":{"oneOf":[{"$ref":"#/components/schemas/SelectDynamicBehaviorVectorGeneratedEvent"},{"$ref":"#/components/schemas/SelectDynamicBehaviorRelevanceRetrievalCompletedEvent"},{"$ref":"#/components/schemas/SelectDynamicBehaviorCompletedEvent"}],"discriminator":{"propertyName":"type","mapping":{"select-dynamic-behavior-completed":"#/components/schemas/SelectDynamicBehaviorCompletedEvent","select-dynamic-behavior-relevance-retrieval-completed":"#/components/schemas/SelectDynamicBehaviorRelevanceRetrievalCompletedEvent","select-dynamic-behavior-vector-generated":"#/components/schemas/SelectDynamicBehaviorVectorGeneratedEvent"}}},"SelectDynamicBehaviorVectorGeneratedEvent":{"properties":{"type":{"type":"string","const":"select-dynamic-behavior-vector-generated","title":"Type","default":"select-dynamic-behavior-vector-generated"}},"type":"object","title":"SelectDynamicBehaviorVectorGeneratedEvent"},"SelectDynamicBehaviorRelevanceRetrievalCompletedEvent":{"properties":{"type":{"type":"string","const":"select-dynamic-behavior-relevance-retrieval-completed","title":"Type","default":"select-dynamic-behavior-relevance-retrieval-completed"}},"type":"object","title":"SelectDynamicBehaviorRelevanceRetrievalCompletedEvent"},"SelectDynamicBehaviorCompletedEvent":{"properties":{"type":{"type":"string","const":"select-dynamic-behavior-completed","title":"Type","default":"select-dynamic-behavior-completed"},"selected_dynamic_behavior_set_version_info":{"anyOf":[{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2},{"type":"null"}],"title":"Selected Dynamic Behavior Set Version Info"},"previous_selected_dynamic_behavior_set_version_info":{"anyOf":[{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2},{"type":"null"}],"title":"Previous Selected Dynamic Behavior Set Version Info"}},"type":"object","required":["selected_dynamic_behavior_set_version_info","previous_selected_dynamic_behavior_set_version_info"],"title":"SelectDynamicBehaviorCompletedEvent"},"CheckIfActiveMemoryNeededAgentActionEvent":{"properties":{"type":{"type":"string","const":"check-if-active-memory-needed-completed","title":"Type","default":"check-if-active-memory-needed-completed"},"queries":{"items":{"type":"string"},"type":"array","title":"Queries"}},"type":"object","required":["queries"],"title":"CheckIfActiveMemoryNeededCompletedEvent"},"ExtractActiveMemoriesAgentActionEvent":{"properties":{"type":{"type":"string","const":"extract-active-memories-completed","title":"Type","default":"extract-active-memories-completed"},"queries_and_responses":{"items":{"prefixItems":[{"type":"string"},{"type":"string"}],"type":"array","maxItems":2,"minItems":2},"type":"array","title":"Queries And Responses"}},"type":"object","required":["queries_and_responses"],"title":"ExtractActiveMemoriesCompletedEvent"},"NavigateStateMachineAgentActionEvent":{"anyOf":[{"$ref":"#/components/schemas/NavigateStateMachineDynamicBehaviorOverrideEvent"},{"$ref":"#/components/schemas/NavigateStateMachineActionStateActionSelectedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineDecisionStateDecisionStartedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineExitConditionSelectedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineRecallStateDynamicQueriesGeneratedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineRecallStateStaticQueriesRetrievedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineRecallStateActiveMemoryRetrievedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineReflectionStatePromptRetrievedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineReflectionStateReflectionGeneratedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineAnnotationStateAnnotationRetrievedEvent"},{"$ref":"#/components/schemas/NavigateStateMachineStateTransitionedEvent"},{"$ref":"#/components/schemas/GenerateToolParamsEvent"},{"$ref":"#/components/schemas/NavigateStateMachineToolCallStateToolOutputAvailableEvent"},{"$ref":"#/components/schemas/ToolCallStartedEvent"},{"$ref":"#/components/schemas/ToolCallEndedEvent"},{"$ref":"#/components/schemas/ActionTooLongEvent"}]},"NavigateStateMachineDynamicBehaviorOverrideEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-dynamic-behavior-override","title":"Type","default":"navigate-state-machine-dynamic-behavior-override"},"overriding_instructions":{"type":"boolean","title":"Overriding Instructions","description":"Whether the dynamic behavior set is overriding instructions during this interaction."},"overriding_tool_candidates":{"type":"boolean","title":"Overriding Tool Candidates","description":"Whether the dynamic behavior set is overriding the tool candidates during this interaction."}},"type":"object","required":["overriding_instructions","overriding_tool_candidates"],"title":"NavigateStateMachineDynamicBehaviorOverrideEvent","description":"Indicating that the agent has merged the dynamic behavior set's instructions with the instructions from the current state."},"NavigateStateMachineActionStateActionSelectedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-action-state-action-selected","title":"Type","default":"navigate-state-machine-action-state-action-selected"},"action":{"type":"string","title":"Action"}},"type":"object","required":["action"],"title":"NavigateStateMachineActionStateActionSelectedEvent","description":"Indicating that the agent has selected an action from the current state."},"NavigateStateMachineDecisionStateDecisionStartedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-decision-state-decision-started","title":"Type","default":"navigate-state-machine-decision-state-decision-started"}},"type":"object","title":"NavigateStateMachineDecisionStateDecisionStartedEvent","description":"Indicating that the agent has started making a decision in the current decision state."},"NavigateStateMachineExitConditionSelectedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-exit-condition-selected","title":"Type","default":"navigate-state-machine-exit-condition-selected"},"exit_condition":{"type":"string","title":"Exit Condition","description":"The exit condition that the agent has selected."},"next_state_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Next State State Machine Version Info","description":"The state machine version info of the next state."},"next_state_name":{"type":"string","title":"Next State Name","description":"The name of the next state."}},"type":"object","required":["exit_condition","next_state_state_machine_version_info","next_state_name"],"title":"NavigateStateMachineExitConditionSelectedEvent","description":"Indicating that the agent has selected an exit condition from the current action or decision state."},"NavigateStateMachineRecallStateDynamicQueriesGeneratedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-recall-state-dynamic-queries-generated","title":"Type","default":"navigate-state-machine-recall-state-dynamic-queries-generated"},"dynamic_queries":{"items":{"type":"string"},"type":"array","title":"Dynamic Queries","description":"The dynamic queries that the agent has generated."},"requested_information":{"type":"string","title":"Requested Information","description":"The information that the agent needs from the queries."}},"type":"object","required":["dynamic_queries","requested_information"],"title":"NavigateStateMachineRecallStateDynamicQueriesGeneratedEvent","description":"Indicating that the agent has generated dynamic queries in the current the recall state."},"NavigateStateMachineRecallStateStaticQueriesRetrievedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-recall-state-static-queries-retrieved","title":"Type","default":"navigate-state-machine-recall-state-static-queries-retrieved"},"static_queries":{"items":{"type":"string"},"type":"array","title":"Static Queries","description":"The static queries that the agent has retrieved."}},"type":"object","required":["static_queries"],"title":"NavigateStateMachineRecallStateStaticQueriesRetrievedEvent","description":"Indicating that the agent has retrieved the static queries in the current the recall state."},"NavigateStateMachineRecallStateActiveMemoryRetrievedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-recall-state-active-memory-retrieved","title":"Type","default":"navigate-state-machine-recall-state-active-memory-retrieved"},"queries_and_responses":{"items":{"prefixItems":[{"type":"string"},{"type":"string"}],"type":"array","maxItems":2,"minItems":2},"type":"array","title":"Queries And Responses","description":"A list of tuples of queries and responses."}},"type":"object","required":["queries_and_responses"],"title":"NavigateStateMachineRecallStateActiveMemoryRetrievedEvent","description":"Indicating that the agent has retrieved the active memory in the current the recall state."},"NavigateStateMachineReflectionStatePromptRetrievedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-reflection-state-prompt-retrieved","title":"Type","default":"navigate-state-machine-reflection-state-prompt-retrieved"},"prompt":{"type":"string","title":"Prompt"}},"type":"object","required":["prompt"],"title":"NavigateStateMachineReflectionStatePromptRetrievedEvent","description":"Indicating that the agent has retrieved the prompt in the current reflection state."},"NavigateStateMachineReflectionStateReflectionGeneratedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-reflection-state-reflection-generated","title":"Type","default":"navigate-state-machine-reflection-state-reflection-generated"},"reflection":{"type":"string","title":"Reflection","description":"The reflection that the agent has generated."}},"type":"object","required":["reflection"],"title":"NavigateStateMachineReflectionStateReflectionGeneratedEvent","description":"Indicating that the agent has generated the reflection in the current reflection state."},"NavigateStateMachineAnnotationStateAnnotationRetrievedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-annotation-state-annotation-retrieved","title":"Type","default":"navigate-state-machine-annotation-state-annotation-retrieved"},"annotation":{"type":"string","title":"Annotation"}},"type":"object","required":["annotation"],"title":"NavigateStateMachineAnnotationStateAnnotationRetrievedEvent","description":"Indicating that the agent has retrieved the annotation in the current annotation state."},"NavigateStateMachineStateTransitionedEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-state-transitioned","title":"Type","default":"navigate-state-machine-state-transitioned"},"prev_state":{"type":"string","title":"Prev State","description":"The previous state."},"prev_state_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Prev State State Machine Version Info","description":"The state machine version info of the previous state."},"next_state":{"type":"string","title":"Next State","description":"The next state."},"next_state_state_machine_version_info":{"prefixItems":[{"type":"string"},{"type":"integer"}],"type":"array","maxItems":2,"minItems":2,"title":"Next State State Machine Version Info","description":"The state machine version info of the next state."}},"type":"object","required":["prev_state","prev_state_state_machine_version_info","next_state","next_state_state_machine_version_info"],"title":"NavigateStateMachineStateTransitionedEvent","description":"Indicating that the agent has transitioned to a new state."},"GenerateToolParamsEvent":{"anyOf":[{"$ref":"#/components/schemas/GenerateToolParamsDesignatedToolRetrievedEvent"},{"$ref":"#/components/schemas/GenerateToolParamsDesignatedToolCallParamsGeneratedEvent"},{"$ref":"#/components/schemas/ActionTooLongEvent"},{"$ref":"#/components/schemas/ToolCallStartedEvent"},{"$ref":"#/components/schemas/ToolCallEndedEvent"}]},"GenerateToolParamsDesignatedToolRetrievedEvent":{"properties":{"type":{"type":"string","const":"designated-tool-retrieved","title":"Type","default":"designated-tool-retrieved"},"tool_id":{"type":"string","title":"Tool Id","description":"The ID of the tool being called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool being called."}},"type":"object","required":["tool_id","tool_version"],"title":"GenerateToolParamsDesignatedToolRetrievedEvent"},"GenerateToolParamsDesignatedToolCallParamsGeneratedEvent":{"properties":{"type":{"type":"string","const":"designated-tool-call-params-generated","title":"Type","default":"designated-tool-call-params-generated"},"tool_id":{"type":"string","title":"Tool Id","description":"The ID of the tool being called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool being called."},"tool_call_params":{"additionalProperties":true,"type":"object","title":"Tool Call Params","description":"The generated tool call parameters."}},"type":"object","required":["tool_id","tool_version","tool_call_params"],"title":"GenerateToolParamsDesignatedToolCallParamsGeneratedEvent"},"ActionTooLongEvent":{"properties":{"type":{"type":"string","const":"action-too-long","title":"Type","default":"action-too-long"},"filler":{"type":"string","title":"Filler","description":"A filler that can be played while waiting for the action to complete. If the audio filler exists, this is monochannel, 16-bit PCM WAV audio (at sample rate 16kHz) encoded in base64 encoding.\nOtherwise, this is the text corresponding to the audio filler."},"previously_started_event":{"title":"Previously Started Event","description":"The previously started event that is taking too long."}},"type":"object","required":["filler","previously_started_event"],"title":"ActionTooLongEvent","description":"Indicating that a previously-started action of the agent is taking too long. This event supplies a filler text that can be displayed\nwhile waiting for the action to complete."},"ToolCallStartedEvent":{"properties":{"type":{"type":"string","const":"tool-call-started","title":"Type","default":"tool-call-started"},"tool_round_index":{"type":"integer","title":"Tool Round Index","description":"Within the current LLM interaction, the round of tool call."},"tool_id":{"type":"string","title":"Tool Id","description":"The ID of the tool being called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool being called."},"input_params":{"additionalProperties":true,"type":"object","title":"Input Params","description":"The input parameters for the tool call."}},"type":"object","required":["tool_round_index","tool_id","tool_version","input_params"],"title":"ToolCallStartedEvent","description":"Indicating that the agent has started executing a tool."},"ToolCallEndedEvent":{"properties":{"type":{"type":"string","const":"tool-call-ended","title":"Type","default":"tool-call-ended"},"tool_round_index":{"type":"integer","title":"Tool Round Index","description":"Within the current LLM interaction, the round of tool call."},"tool_id":{"type":"string","title":"Tool Id","description":"The ID of the tool being called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool being called."},"input_parameters":{"additionalProperties":true,"type":"object","title":"Input Parameters","description":"The input parameters for the tool call."},"result":{"type":"string","title":"Result","description":"The result of the tool call."},"duration":{"type":"number","title":"Duration","description":"The duration of the tool call in seconds."}},"type":"object","required":["tool_round_index","tool_id","tool_version","input_parameters","result","duration"],"title":"ToolCallEndedEvent","description":"Indicating that the agent has finished executing a tool."},"NavigateStateMachineToolCallStateToolOutputAvailableEvent":{"properties":{"type":{"type":"string","const":"navigate-state-machine-tool-call-state-tool-output-available","title":"Type","default":"navigate-state-machine-tool-call-state-tool-output-available"},"tool_id":{"type":"string","title":"Tool Id","description":"The ID of the tool being called."},"tool_version":{"type":"string","title":"Tool Version","description":"The version of the tool being called."},"tool_output":{"type":"string","title":"Tool Output","description":"The tool output."},"duration":{"type":"number","title":"Duration","description":"The duration taken to receive the tool output in seconds."},"input_arguments":{"additionalProperties":true,"type":"object","title":"Input Arguments","description":"The input arguments used for the tool call."}},"type":"object","required":["tool_id","tool_version","tool_output","duration","input_arguments"],"title":"NavigateStateMachineToolCallStateToolOutputAvailableEvent","description":"Indicating that the agent has received the tool output in the current tool call state."},"EngageUserAgentActionEvent":{"oneOf":[{"$ref":"#/components/schemas/EngageUserDynamicBehaviorOverrideEvent"},{"$ref":"#/components/schemas/EngageUserMessageFragmentGeneratedEvent"},{"$ref":"#/components/schemas/ToolCallStartedEvent"},{"$ref":"#/components/schemas/ToolCallEndedEvent"},{"$ref":"#/components/schemas/ActionTooLongEvent"}],"discriminator":{"propertyName":"type","mapping":{"action-too-long":"#/components/schemas/ActionTooLongEvent","engage-user-dynamic-behavior-override":"#/components/schemas/EngageUserDynamicBehaviorOverrideEvent","engage-user-message-fragment-generated":"#/components/schemas/EngageUserMessageFragmentGeneratedEvent","tool-call-ended":"#/components/schemas/ToolCallEndedEvent","tool-call-started":"#/components/schemas/ToolCallStartedEvent"}}},"EngageUserDynamicBehaviorOverrideEvent":{"properties":{"type":{"type":"string","const":"engage-user-dynamic-behavior-override","title":"Type","default":"engage-user-dynamic-behavior-override"},"overriding_instructions":{"type":"boolean","title":"Overriding Instructions","description":"Whether the dynamic behavior set is overriding instructions during this interaction."},"overriding_tool_candidates":{"type":"boolean","title":"Overriding Tool Candidates","description":"Whether the dynamic behavior set is overriding the tool candidates during this interaction."}},"type":"object","required":["overriding_instructions","overriding_tool_candidates"],"title":"EngageUserDynamicBehaviorOverrideEvent","description":"Indicating that the agent has merged the dynamic behavior set's instructions with the instructions from the current state."},"EngageUserMessageFragmentGeneratedEvent":{"properties":{"type":{"type":"string","const":"engage-user-message-fragment-generated","title":"Type","default":"engage-user-message-fragment-generated"},"index":{"type":"integer","title":"Index","description":"The index of the fragment in the agent response."},"fragment":{"type":"string","title":"Fragment","description":"The fragment of the agent response that has been generated."},"is_final":{"type":"boolean","title":"Is Final","description":"Whether this fragment is the final fragment of the agent response."}},"type":"object","required":["index","fragment","is_final"],"title":"EngageUserMessageFragmentGeneratedEvent","description":"Indicating that the agent has generated a fragment of the agent response."},"UserMessageAvailableEvent":{"properties":{"type":{"type":"string","const":"user-message-available","title":"Type","default":"user-message-available"},"message_id":{"type":"string","title":"Message Id","description":"The identifier of the user message."},"user_message":{"type":"string","title":"User Message","description":"The text of the user message."}},"type":"object","required":["message_id","user_message"],"title":"UserMessageAvailableEvent","description":"Emitted when the full text of the user message is available. In particular, for voice messages, this event is emitted when the transcription of the user message is complete. It's the first event in the response stream."},"ErrorEvent":{"properties":{"type":{"type":"string","const":"error","title":"Type","default":"error"},"http_error_code":{"type":"integer","title":"Http Error Code","description":"The HTTP status code of the error."},"error_description":{"type":"string","title":"Error Description","description":"A description of the error."}},"type":"object","required":["http_error_code","error_description"],"title":"ErrorEvent","description":"Emitted when there is an error during the stream. This event could be emitted even if the request returns with a 200.\nIf received before an `interaction-complete` event, the client should consider the entire interaction void and retry. If received after,\nthen the conversation has completed and an error occurred during the post-processing, so the client should consider the interaction valid and saved,\nbut manually call the `FinishConversation` endpoint to retry the post-processing."}}},"paths":{"/v1/{organization}/conversation/{conversation_id}/interact":{"post":{"tags":["Conversation"],"summary":"Interact with a conversation","description":"Send a new user message to the conversation. The endpoint will perform analysis and generate an agent message in response.\n\nA `UserMessageAvailableEvent` will be the first event in the response, which includes the user message if it's sent as text, or the transcribed message if it's sent as voice.\nA series of `CurrentAgentActionEvent`s will follow, which indicates steps in the agent's thinking process. Then the agent message is generated sequentially in pieces, with each piece\nbeing sent as a `NewMessageEvent` in the response. After all the pieces are sent, an `InteractionCompleteEvent` is sent. Depending on the `conversation_completed` property in this event, the conversation will be awaiting\na new message from the user, or it might automatically end (for instance, because the user message indicates the user wants to end the session), while the conversation is marked as finished and the post-conversation\nanalysis asynchronously initiated. The connection will then terminate.\n\nAny further action on the conversation is only allowed after the connection is terminated.\n\nA 200 status code doesn't indicate the successful completion of this endpoint, because the status code is transmitted before the stream starts. At any point during the stream,\nan `ErrorEvent` might be sent, which indicates that an error has occurred. The connection will be immediately closed after.\n\nThis endpoint can only be called on a conversation that has started but not finished.\n\n#### Permissions\nThis endpoint requires the following permissions:\n* `User:UpdateUserInfo` on the user who started the conversation.\n* `Conversation:InteractWithConversation` on the conversation.\n\nThis endpoint may be impacted by the following permissions:\n* `CurrentAgentActionEvent`s are only emitted if the authenticated user has the `Conversation:GetInteractionInsights` permission.","operationId":"interact-with-conversation","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"The identifier of the conversation to send a message to.","title":"Conversation Id"},"description":"The identifier of the conversation to send a message to."},{"name":"organization","in":"path","required":true,"schema":{"type":"string","title":"Organization"}},{"name":"request_format","in":"query","required":true,"schema":{"enum":["text","voice"],"type":"string","description":"The format in which the user message is delivered to the server.","title":"Request Format"},"description":"The format in which the user message is delivered to the server."},{"name":"response_format","in":"query","required":true,"schema":{"enum":["text","voice"],"type":"string","description":"The format of the response that will be sent to the user.","title":"Response Format"},"description":"The format of the response that will be sent to the user."},{"name":"current_agent_action_type","in":"query","required":false,"schema":{"type":"string","description":"A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance `^$`.","default":"^.*$","title":"Current Agent Action Type"},"description":"A regex for filtering the type of the current agent action to return. By default, all are returned. If you don't want to receive any events, set this to a regex that matches nothing, for instance `^$`."},{"name":"request_audio_config","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/UserMessageAudioConfig"},{"type":"null"}],"description":"Configuration for the user message audio. This is only required if `request_format` is set to `voice`.","title":"Request Audio Config"},"description":"Configuration for the user message audio. This is only required if `request_format` is set to `voice`."},{"name":"content-type","in":"header","required":true,"schema":{"type":"string","pattern":"^multipart\\/form-data; boundary=.+$","description":"The content type of the request body, which must be `multipart/form-data` followed by a boundary.","title":"Content-Type"},"description":"The content type of the request body, which must be `multipart/form-data` followed by a boundary."},{"name":"x-mongo-cluster-name","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.","title":"X-Mongo-Cluster-Name"},"description":"The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database."},{"name":"Sec-WebSocket-Protocol","in":"header","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[],"title":"Sec-Websocket-Protocol"}}],"responses":{"200":{"description":"\nSucceeded. The response will be a stream of events in JSON format separated by newlines. The server will transmit an event as soon as one is available,\nso the client should respond to the events as soon as one arrives, and keep listening until the server closes the connection.\n","content":{"application/x-ndjson":{"schema":{"type":"object","$ref":"#/components/schemas/src__app__endpoints__conversation__interact_with_conversation__Response"}}}},"400":{"description":"\nThis may occur for the following reasons:\n* The user message is empty.\n* The preferred language does not support voice transcription or response.\n* The `response_audio_format` field is not set when voice output is requested.\n* The timestamps for external event messages are not in the past.\n* The timestamps for external event messages are inconsistent with the conversation.\n* The agent does not have voice config specified."},"401":{"description":"Invalid authorization credentials."},"403":{"description":"Missing required permissions."},"404":{"description":"Specified organization or conversation is not found."},"408":{"description":"The request body stream timed out."},"409":{"description":"The specified conversation is already finished, or a related operation is in process."},"415":{"description":"The format of the supplied audio file is not supported."},"422":{"description":"Invalid request path parameter or request body failed validation."},"429":{"description":"The user has exceeded the rate limit of 15 requests per minute for this endpoint."},"503":{"description":"The service is going through temporary maintenance."}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"oneOf":[{"properties":{"initial_message_type":{"const":"external-event","title":"Initial Message Type","type":"string"},"recorded_message":{"minLength":1,"type":"string"},"external_event_message_content":{"default":[],"description":"The contents of external event messages to be inserted before the initial message, in chronological order.","items":{"minLength":1,"type":"string"},"title":"External Event Message Content","type":"array"},"external_event_message_timestamp":{"default":[],"description":"The timestamps of external event messages to be inserted before the initial message, in chronological order.","items":{"format":"date-time","type":"string"},"title":"External Event Message Timestamp","type":"array"}},"required":["initial_message_type","recorded_message"],"title":"ExternalEventClientMessageRequestBody","type":"object"},{"properties":{"initial_message_type":{"const":"user-message","title":"Initial Message Type","type":"string"},"recorded_message":{"minLength":1,"type":"string"},"external_event_message_content":{"default":[],"description":"The contents of external event messages to be inserted before the initial message, in chronological order.","items":{"minLength":1,"type":"string"},"title":"External Event Message Content","type":"array"},"external_event_message_timestamp":{"default":[],"description":"The timestamps of external event messages to be inserted before the initial message, in chronological order.","items":{"format":"date-time","type":"string"},"title":"External Event Message Timestamp","type":"array"}},"required":["initial_message_type","recorded_message"],"title":"UserMessageClientMessageRequestBody","type":"object"},{"properties":{"initial_message_type":{"const":"skip","title":"Initial Message Type","type":"string"},"recorded_message":{"description":"The body of the initial message, which must be empty.","maxLength":0,"title":"Recorded Message","type":"string"},"external_event_message_content":{"default":[],"description":"Must be empty, as external event messages cannot be sent with skips.","items":{"minLength":1,"type":"string"},"maxItems":0,"title":"External Event Message Content","type":"array"},"external_event_message_timestamp":{"default":[],"description":"Must be empty, as external event messages cannot be sent with skips.","items":{"format":"date-time","type":"string"},"maxItems":0,"title":"External Event Message Timestamp","type":"array"}},"required":["initial_message_type","recorded_message"],"title":"SkipClientMessageRequestBody","type":"object"}]}}}}}}}}
```

## Form Parameters

* `"initial_message_type"`: `"user_message"`
* `"recorded_message"`: string or Blob
  * Blob is base64-encoded PCM audio for push-to-talk audio messages
* `"external_event_message_content"`: string (optional, exclude if no external events)
* `"external_event_message_timestamp"`: string (optional, exclude if no external events). An ISO UTC timestamp, for example `"2025-09-05T17:48:04.789560+00:00"`.
  * Must have the same number of instances as `external_event_message_content`
  * Each timestamp must be greater than the last message time

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/conversation/<CONVERSATION-ID>/interact?request_format=text&response_format=text' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --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 `error` events as a rollback of the interaction. Log and retry as needed.
* 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 (dynamic behavior triggered) and evaluate metrics, see Conversations: Events → System Integration Flow ([conversations-events.md#system-integration-flow](https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations-events#system-integration-flow)). That page includes a sequence diagram and API examples for `metric/evaluate`.

## Finish the Conversation

See [Lifecycle & Finish](https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversations-lifecycle) to manually end a conversation and handle dangling sessions.