Lifecycle & Finish

Understand conversation states and how to finish or resume sessions.

REST vs WebSocket

Amigo provides two ways to interact with conversations:

• REST API (documented here): HTTP POST requests with NDJSON streaming responses - best for server-to-server integrations

• WebSocket API: Real-time bidirectional communication with support for voice activity detection (VAD) - best for interactive client applications. See Conversations: Realtime for WebSocket details.

Conversation Management Lifecycle

The typical lifecycle uses HTTP requests with NDJSON event streams for both creation and each interaction.

API Endpoints

Create a conversation

post

Create a new conversation and start it. The user must not have any unfinished conversations that belong to the same service.

Permissions

This endpoint requires the following permissions:

• Conversation.CreateConversation for the new conversation.

This endpoint may be impacted by the following permissions:

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

Authorizations

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

Path parameters

organizationstringRequired

Query parameters

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

audio_formatany ofOptional

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

string · enumOptionalPossible values:

or

nullOptional

Header parameters

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

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

application/json

service_idstringRequired

The identifier of the service to create a conversation in.

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

service_version_set_namestringOptional

The version set of the service to use. If not provided, the release version set is used.

Default: release

initial_messageany ofOptional

The initial user or agent inner thought message to send to the service. If not provided, the conversation will start with an agent message.

string · min: 1Optional

or

nullOptional

initial_message_typeany ofOptional

The type of the initial_message. Can only be specified if initial_message is provided.

string · enumOptionalPossible values:

or

nullOptional

Responses

201

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

Responseone of

or

or

or

or

400

Attempting to start a conversation when other unfinished conversations exist, or the preferred language does not support voice response, or the audio_format field is not set when voice output is requested.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization, service, or version set is not found.

409

A related operation is in progress.

422

Invalid request path parameter or request body failed validation.

429

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

503

The service is going through temporary maintenance.

post

HTTPcURLJavaScriptPython

POST /v1/{organization}/conversation/?response_format=text HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 121

{
  "service_id": "text",
  "service_version_set_name": "release",
  "initial_message": "text",
  "initial_message_type": "user-message"
}

{
  "type": "conversation-created",
  "conversation_id": "text"
}

Interact with a conversation

post

Send a new user message to the conversation. The endpoint will perform analysis and generate an agent message in response.

If request_format is text, the request body must follow multipart/form-data with precise one form field called recorded_message that corresponds to UTF-8 encoded bytes of the text message. If request_format is voice, the entire request body must be the bytes of the voice recording in audio/wav or audio/mpeg (MP3) format. The body can be sent as a stream, and the endpoint will start processing chunks as they're received, which will reduce latency.

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

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

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

or

or

nullOptional

audio_formatany ofOptional

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

string · enumOptionalPossible values:

or

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

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

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

or

or

or

or

or

400

The user message is empty, or the preferred language does not support voice transcription or response, or the 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 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

HTTPcURLJavaScriptPython

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
Accept: */*

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

Finish a conversation

post

Conclude a conversation and asynchronously initiate post-conversation analysis.

This endpoint should only be called on a started, non-finished conversation. It can only be called when the previous Start a conversation and Interact with a conversation calls have finished.

If the conversation has no messages, the conversation is deleted.

It's possible for some conversations to automatically finish during an Interact with a conversation call (for instance, if the user explicitly sends a message indicating that they're done with the conversation). In that case, this endpoint shouldn't be called, as the Interact with a conversation endpoint automatically wraps up the conversation.

Permissions

This endpoint requires the following permissions:

• User:UpdateUserInfo on the user who started the conversation.
• Conversation:InteractWithConversation on the conversation.

Authorizations

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

Path parameters

conversation_idstringRequired

The identifier of the conversation to finish.

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

organizationstringRequired

Header parameters

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

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

204

Succeeded.

No content

400

The conversation has no interactions.

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.

422

Invalid request path parameter failed validation.

429

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

503

The service is going through temporary maintenance.

post

HTTPcURLJavaScriptPython

POST /v1/{organization}/conversation/{conversation_id}/finish/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

No content

States

• Started: active and can receive interactions

• Finished: ended and cannot receive further interactions

Automatic vs Manual Finish

Conversations may finish automatically based on service logic, or manually via the finish API (e.g., timeout or user action).

Finish a Conversation

cURL

curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/conversation/<CONVERSATION-ID>/finish/' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{}'

Python SDK

from amigo_sdk import AmigoClient

with AmigoClient() as client:
    client.conversation.finish_conversation(conversation_id)

TypeScript SDK

import { AmigoClient } from "@amigo-ai/sdk";

const client = new AmigoClient({ /* config */ });
await client.conversations.finishConversation(conversationId);

Finish a conversation

post

Conclude a conversation and asynchronously initiate post-conversation analysis.

This endpoint should only be called on a started, non-finished conversation. It can only be called when the previous Start a conversation and Interact with a conversation calls have finished.

If the conversation has no messages, the conversation is deleted.

It's possible for some conversations to automatically finish during an Interact with a conversation call (for instance, if the user explicitly sends a message indicating that they're done with the conversation). In that case, this endpoint shouldn't be called, as the Interact with a conversation endpoint automatically wraps up the conversation.

Permissions

This endpoint requires the following permissions:

• User:UpdateUserInfo on the user who started the conversation.
• Conversation:InteractWithConversation on the conversation.

Authorizations

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

Path parameters

conversation_idstringRequired

The identifier of the conversation to finish.

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

organizationstringRequired

Header parameters

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

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

204

Succeeded.

No content

400

The conversation has no interactions.

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.

422

Invalid request path parameter failed validation.

429

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

503

The service is going through temporary maintenance.

post

HTTPcURLJavaScriptPython

POST /v1/{organization}/conversation/{conversation_id}/finish/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

No content

Managing Inactive ("Dangling") Conversations

Conversations do not time out automatically. Common patterns:

• Timeout: Track last interaction and call finish after a period (may end active sessions unexpectedly).

• Resume (recommended): Offer resume or start new; finishing the existing conversation if needed.

• On conflict when creating a new conversation: prompt the user to resume or end the existing one.

When a conversation finishes, post-conversation analysis (memories, user model updates, metrics) runs asynchronously.