> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversations-lifecycle.md).

# Lifecycle & Finish

Understand conversation states and how to finish or resume sessions.

{% hint style="info" %}
**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](/developer-guide/classic-api/core-api/conversations/conversations-realtime.md) for WebSocket details.
  {% endhint %}

## Conversation Management Lifecycle

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

{% @mermaid/diagram content="%%{init: {"theme": "base", "themeVariables": {"actorBkg": "#083241", "actorTextColor": "#FFFFFF", "actorBorder": "#083241", "signalColor": "#575452", "signalTextColor": "#100F0F", "labelBoxBkgColor": "#F1EAE7", "labelBoxBorderColor": "#D7D2D0", "labelTextColor": "#100F0F", "loopTextColor": "#100F0F", "noteBkgColor": "#F1EAE7", "noteBorderColor": "#D7D2D0", "noteTextColor": "#100F0F", "activationBkgColor": "#E8E2EB", "activationBorderColor": "#083241", "altSectionBkgColor": "#F1EAE7", "altSectionColor": "#100F0F"}}}%%
sequenceDiagram
autonumber
participant C as Customer System
participant A as Amigo REST API

Note over C,A: Start a new conversation
C->>A: POST /v1/{org\_id}/conversation
Note over C,A: Body:<br/>service\_id, service\_version\_set\_name
A-->>C: 200 OK (headers start NDJSON stream)
Note over C,A: Stream emits NDJSON events
A-->>C: event: conversation-created { conversation\_id }
A-->>C: event: new-message (chunks)...
A-->>C: event: interaction-complete { interaction\_id }

Note over C,A: Send a user turn (text or voice)
C->>A: POST /v1/{org\_id}/conversation/<br/>{conversation\_id}/interact
Note over C,A: Body: text | recorded\_message
A-->>C: 200 OK (NDJSON stream)
A-->>C: event: user-message-available { user\_message }
A-->>C: event: new-message (chunks)...
A-->>C: event: interaction-complete { interaction\_id }
opt current agent action (optional)
A-->>C: event: current-agent-action { ... }
end

Note over C,A: End the session when appropriate
C->>A: POST /v1/{org\_id}/conversation/<br/>{conversation\_id}/finish
A-->>C: 204 No Content" %}

## API Endpoints

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/conversation/" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/conversation/{conversation\_id}/interact" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/conversation/{conversation\_id}/finish/" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## States

* **Started**: active and can receive interactions.
* **Finished**: ended and cannot receive further interactions.

{% @mermaid/diagram content="%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#D4E2E7", "primaryTextColor": "#100F0F", "primaryBorderColor": "#083241", "lineColor": "#575452", "textColor": "#100F0F"}}}%%
stateDiagram-v2
direction TB
\[*] --> Started
Started --> Finished: finish API or auto finish
Finished --> \[*]
note right of Started
active; can receive interactions
end note
note right of Finished
ended; cannot receive interactions
end note" %}

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

{% @mermaid/diagram content="%%{init: {"theme": "base", "themeVariables": {"actorBkg": "#083241", "actorTextColor": "#FFFFFF", "actorBorder": "#083241", "signalColor": "#575452", "signalTextColor": "#100F0F", "labelBoxBkgColor": "#F1EAE7", "labelBoxBorderColor": "#D7D2D0", "labelTextColor": "#100F0F", "loopTextColor": "#100F0F", "noteBkgColor": "#F1EAE7", "noteBorderColor": "#D7D2D0", "noteTextColor": "#100F0F", "activationBkgColor": "#E8E2EB", "activationBorderColor": "#083241", "altSectionBkgColor": "#F1EAE7", "altSectionColor": "#100F0F"}}}%%
sequenceDiagram
autonumber
participant C as Customer System
participant A as Amigo REST API

alt Manual finish
C->>A: POST /v1/{org\_id}/conversation/<br/>{conversation\_id}/finish
A-->>C: 204 No Content
else Automatic finish
A-->>C: event: interaction-complete { conversation\_completed: true }
end" %}

## Finish a Conversation

{% tabs %}
{% tab title="cURL" %}

```bash
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 '{}'
```

{% endtab %}

{% tab title="Python SDK" %}

```python
from amigo_sdk import AmigoClient

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

{% endtab %}

{% tab title="TypeScript SDK" %}

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

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

{% endtab %}
{% endtabs %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/conversation/{conversation\_id}/finish/" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversations-lifecycle.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.