---
title: "Interact with a conversation"
method: POST
path: "/v1/{organization}/conversation/{conversation_id}/interact"
tags: ["Conversation"]
---

# 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 `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.

## Path parameters

- `conversation_id` string, required — The identifier of the conversation to send a message to.
- `organization` string, required

## Query parameters

- `request_format` 'text' | 'voice', required — The format in which the user message is delivered to the server.
- `response_format` 'text' | 'voice', required — The format of the response that will be sent to the user.
- `current_agent_action_type` string — 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 `^$`.
- `request_audio_config` union
  - MP3UserMessageAudioConfig
    - `type` 'mp3'
  - PCMUserMessageAudioConfig
    - `type` 'pcm'
    - `frame_rate` integer, required
    - `n_channels` 1, required
    - `sample_width` 2 | 4, required

## Headers

- `content-type` string, required — The content type of the request body, which must be `multipart/form-data` followed by a boundary.
- `x-mongo-cluster-name` string, nullable — 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.
- `Sec-WebSocket-Protocol` string[]

## Response `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.

## Other responses

- `400` — This may occur for the following reasons: * The user message is empty. * The preferred language does not support voice transcription or response. * The `response_audio_format` field is not set when voice output is requested. * The timestamps for external event messages are not in the past. * The timestamps for external event messages are inconsistent with the conversation. * The agent does not have voice config specified.
- `401` — Invalid authorization credentials.
- `403` — Missing required permissions.
- `404` — Specified organization or conversation is not found.
- `408` — The request body stream timed out.
- `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.

---

[API](https://skmtc.net/amigo/apis/amigo-api.md) · [All operations](https://skmtc.net/amigo/apis/amigo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/amigo/amigo-api/revisions/f0f28319e448/schema)