Interact

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

Send a Message

Interact with a conversation

post

/v1/{organization}/conversation/{conversation_id}/interact

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 CurrentAgentActionEvents 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. The response might end here, or, if the conversation automatically ends (for instance, because the user message indicates the user wants to end the session), an EndSessionEvent would be emitted, 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:

CurrentAgentActionEvents are only emitted if the authenticated user has the Conversation:GetInteractionInsights permission.

Authorizations

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.

Path parameters

conversation_idstringRequired

The identifier of the conversation to send a message to.

Pattern: ^[a-f0-9]{24}$

organizationstringRequired

Query parameters

request_formatstring · enumRequired

The format in which the user message is delivered to the server.

Possible values:

response_formatstring · enumRequired

The format of the response that will be sent to the user.

Possible values:

current_agent_action_typestringOptional

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: ^.*$

request_audio_configany ofOptional

Configuration for the user message audio. This is only required if request_format is set to voice.

one ofOptional

nullOptional

audio_formatany ofOptional

The format of the audio response, if response_format is set to voice.

string · enumOptionalPossible values:

nullOptional

response_audio_formatany ofOptional

The format of the audio response, if response_format is set to voice.

one ofOptional

nullOptional

Header parameters

content-typestringRequired

The content type of the request body, which must be multipart/form-data followed by a boundary.

Pattern: ^multipart\/form-data; boundary=.+$

x-mongo-cluster-nameany ofOptional

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.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

one ofOptional

Responses

200

Succeeded. 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, so the client should respond to the events as soon as one arrives, and keep listening until the server closes the connection.

application/x-ndjson

Responseany of

400

The user message is empty, or the preferred language does not support voice transcription or response, or the response_audio_format field is not set when voice output is requested, or the timestamps for external event messages are not in the past, or the timestamps for external event messages are inconsistent with the conversation.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or conversation is not found.

409

The specified conversation is already finished, or a related operation is in process.

415

The format of the supplied audio file is not supported.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 15 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

/v1/{organization}/conversation/{conversation_id}/interact

POST /v1/{organization}/conversation/{conversation_id}/interact?request_format=text&response_format=text HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
content-type: text
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 165

"initial_message_type='text'&recorded_message='text'&external_event_message_contents=['text']&external_event_message_timestamps=['2025-12-02T19:27:44.021Z']"

{
  "type": "interaction-complete",
  "message_id": "text",
  "interaction_id": "text",
  "full_message": "text",
  "conversation_completed": true
}

Form Parameters

"initial_message_type": "user_message"
"recorded_message": string | 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) (ISO UTC timestamp, e.g. "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

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'

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

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;
  }
}

Best Practices

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/abort controllers to bound request duration
Keep track of returned IDs for diagnostics

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)

That page includes a sequence diagram and API examples for metric/evaluate.

Finish the Conversation

See Lifecycle & Finish to manually end a conversation and handle dangling sessions.

PreviousCreate NextEvents

Last updated 17 days ago

Was this helpful?

Good evening

Send a Message

Interact with a conversation

Form Parameters

Best Practices

Dynamic Behavior → Metric Evaluation

Finish the Conversation