# End conversation tool

Configure `end_conversation` to let an Assistant hang up when the caller is done. You can set a closing message and instructions for when to use the tool.

## What is the end conversation tool?

The `end_conversation` System Tool ends the current call.

When configured, the Assistant can decide when to end the conversation based on context, such as when the user explicitly asks to hang up or when the conversation reaches a natural conclusion.

Use `descriptionOverride` to tell the Assistant when to end the call and `closingMessage` to set what it says before disconnecting.

## When the Assistant ends calls

The Assistant can use `end_conversation` when:

* The caller asks to hang up or says goodbye.
* All questions have been answered.
* The call's task is complete.
* The caller confirms they need no further help.

The exact triggering behaviour depends on your Assistant's system prompt and instructions.

## Setting up the end conversation tool

The API paths below are relative to `https://newprd.reecall.io/data_next`.

### Step 1: fetch the tool definition

Retrieve the `end_conversation` Tool Definition ID:

```http
GET /ai/toolDefinitions?where={"name":"end_conversation"}
```

Use the `id` from the response as `definitionId` when creating the Tool:

```json
[
  {
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "name": "end_conversation",
    "description": "End the conversation and disconnect...",
    "configuration": {},
    "createdAt": "2025-12-15T08:58:49.942Z",
    "updatedAt": "2025-12-15T08:58:49.942Z"
  } 
]
```

### Step 2: create the tool

Create a Tool instance with your configuration and link it to an Assistant with `assistantId`:

```http
POST /ai/tools
Content-Type: application/json
Authorization: Bearer <your-api-token>

{
  "assistantId": "your-assistant-id",
  "definitionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "descriptionOverride": "End the call when the customer confirms they have no more questions.",
  "configuration": {
    "closingMessage": "Thank you for calling. Have a great day!"
  }
}
```

***

## Configuration reference

### Tool fields

| Field                 | Type   | Required | Description                                                 |
| --------------------- | ------ | -------- | ----------------------------------------------------------- |
| `descriptionOverride` | string | No       | Custom description shown to the LLM, overriding the default |

Use `descriptionOverride` to specify the conditions under which the Assistant should end the call.

### Configuration object

| Field            | Type   | Required | Description                                         |
| ---------------- | ------ | -------- | --------------------------------------------------- |
| `closingMessage` | string | No       | Message the Assistant speaks before ending the call |

:::info{title="Note"}

If `closingMessage` is omitted, the tool ends the call without speaking a closing message.

:::

***

## Behaviour

The Channel determines how the call disconnects.

### SIP Channel

For SIP connections, the Assistant shuts down its session and deletes the LiveKit room. LiveKit tears down the SIP participant and the associated phone call.

<Mermaid chart={`sequenceDiagram
    participant Caller
    participant Assistant
    participant LiveKit as LiveKit Server

    Note over Assistant: LLM decides to end call
    alt closingMessage configured
        Assistant->>Caller: Says closingMessage (RTP audio)
        Note over Assistant: Waits for audio playout
    end
    Assistant->>LiveKit: Close session and delete room
    Note over LiveKit: SIP call terminated
    Note over Assistant: Conversation terminated`} />

| Step | Action                                                              |
| ---- | ------------------------------------------------------------------- |
| 1    | If `closingMessage` is configured, Assistant speaks it via RTP      |
| 2    | If message was spoken, system waits for the audio to finish playing |
| 3    | Assistant shuts down the session and deletes the room                         |
| 4    | LiveKit disconnects the SIP participant and ends the call                |

### WebRTC Channel

For WebRTC connections, the Assistant notifies your client via RPC before ending the conversation. The Assistant waits up to 5 seconds for the RPC response, then shuts down the session even if the notification fails or the client does not acknowledge it. Handle `EndCall` to perform your application cleanup.

<Mermaid chart={`sequenceDiagram
    participant Caller
    participant Assistant
    participant Client as Your WebRTC Client

    Note over Assistant: LLM decides to end call
    alt closingMessage configured
        Assistant->>Caller: Says closingMessage
        Note over Assistant: Waits for audio playout
    end
    Assistant->>Client: EndCall RPC
    opt Client responds within 5 seconds
        Client-->>Assistant: acknowledgement
    end
    Note over Assistant: Conversation terminated`} />

| Step | Action                                                              |
| ---- | ------------------------------------------------------------------- |
| 1    | If `closingMessage` is configured, Assistant speaks it              |
| 2    | If message was spoken, system waits for the audio to finish playing |
| 3    | Assistant sends `EndCall` RPC request to your WebRTC client         |
| 4    | Conversation terminates after the response, timeout, or RPC failure           |
