# 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](https://docs.amigo.ai/developer-guide/classic-api/core-api/conversations/conversations-realtime) 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.