Lifecycle & Finish
Understand conversation states and how to finish or resume sessions.
Conversation Management Lifecycle
The typical lifecycle uses HTTP requests with NDJSON event streams for both creation and each interaction.
API Endpoints
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.CreateConversationfor the new conversation.
This endpoint may be impacted by the following permissions:
CurrentAgentActionEvents are only emitted if the authenticated user has theConversation:GetInteractionInsightspermission.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The format of the response that will be sent to the user.
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 ^$.
^.*$The format of the audio response, if response_format is set to voice.
The format of the audio response, if response_format is set to voice.
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.
[]The identifier of the service to create a conversation in.
^[a-f0-9]{24}$The version set of the service to use. If not provided, the release version set is used.
releaseThe initial user or agent inner thought message to send to the service. If not provided, the conversation will start with an agent message.
The type of the initial_message. Can only be specified if initial_message is provided.
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.
Attempting to start a conversation when other unfinished conversations exist, or the preferred language does not support voice response, or the response_audio_format field is not set when voice output is requested.
Invalid authorization credentials.
Missing required permissions.
Specified organization, service, or version set is not found.
A related operation is in progress.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 5 requests per minute for this endpoint.
The service is going through temporary maintenance.
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"
}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:UpdateUserInfoon the user who started the conversation.Conversation:InteractWithConversationon the conversation.
This endpoint may be impacted by the following permissions:
CurrentAgentActionEvents are only emitted if the authenticated user has theConversation:GetInteractionInsightspermission.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The identifier of the conversation to send a message to.
^[a-f0-9]{24}$The format in which the user message is delivered to the server.
The format of the response that will be sent to the user.
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 ^$.
^.*$Configuration for the user message audio. This is only required if request_format is set to voice.
The format of the audio response, if response_format is set to voice.
The format of the audio response, if response_format is set to voice.
The content type of the request body, which must be multipart/form-data followed by a boundary.
^multipart\/form-data; boundary=.+$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.
[]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.
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.
Invalid authorization credentials.
Missing required permissions.
Specified organization or conversation is not found.
The specified conversation is already finished, or a related operation is in process.
The format of the supplied audio file is not supported.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 15 requests per minute for this endpoint.
The service is going through temporary maintenance.
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-03T05:33:26.601Z']"{
"type": "interaction-complete",
"message_id": "text",
"interaction_id": "text",
"full_message": "text",
"conversation_completed": true
}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:UpdateUserInfoon the user who started the conversation.Conversation:InteractWithConversationon the conversation.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The identifier of the conversation to finish.
^[a-f0-9]{24}$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.
[]Succeeded.
The conversation has no interactions.
Invalid authorization credentials.
Missing required permissions.
Specified organization or conversation is not found.
The specified conversation is already finished, or a related operation is in process.
Invalid request path parameter failed validation.
The user has exceeded the rate limit of 5 requests per minute for this endpoint.
The service is going through temporary maintenance.
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 --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 '{}'from amigo_sdk import AmigoClient
with AmigoClient() as client:
client.conversation.finish_conversation(conversation_id)import { AmigoClient } from "@amigo-ai/sdk";
const client = new AmigoClient({ /* config */ });
await client.conversations.finishConversation(conversationId);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:UpdateUserInfoon the user who started the conversation.Conversation:InteractWithConversationon the conversation.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The identifier of the conversation to finish.
^[a-f0-9]{24}$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.
[]Succeeded.
The conversation has no interactions.
Invalid authorization credentials.
Missing required permissions.
Specified organization or conversation is not found.
The specified conversation is already finished, or a related operation is in process.
Invalid request path parameter failed validation.
The user has exceeded the rate limit of 5 requests per minute for this endpoint.
The service is going through temporary maintenance.
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.
Last updated
Was this helpful?