Lifecycle & Finish

Manage conversation states, finish sessions manually or automatically, and handle dangling conversations.

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

The create and interact endpoints have dedicated pages; the finish endpoint is documented in Finish a Conversation below.

CreateInteract

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 through the finish API (for example, on a 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'

Python SDK

TypeScript SDK

Finish a conversation

post

https://api.amigo.aihttps://internal-api.amigo.aihttps://api-eu-central-1.amigo.aihttps://api-ap-southeast-2.amigo.aihttps://api-ca-central-1.amigo.ai

/v1/{organization}/conversation/{conversation_id}/finish/

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:FinishConversation on the conversation.

Authorizations

Basic & Bearer-Authorization & Bearer-Authorization-Organization

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

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 finish.

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

organizationstringRequired

Header parameters

x-mongo-cluster-namestring · nullableOptional

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-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/v1/{organization}/conversation/{conversation_id}/finish/

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 the last interaction and call finish after a period. This 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.