***

title: End-Call Reasons
slug: end-call-reasons
description: Configure custom end-call reasons so Synthflow agents can automatically terminate conversations under defined conditions.
---------------------

For a complete page index, fetch https://docs.synthflow.ai/llms.txt. For full documentation content, fetch https://docs.synthflow.ai/llms-full.txt.

**End-Call Reasons** let you define custom conditions that trigger automatic call termination. When the AI agent detects one of these conditions during a conversation, it says a brief farewell and ends the call. This feature works with both **simple prompt** and **Flow Designer** agents.

## How it works

End-call reasons are evaluated by the AI agent on every conversational turn. The agent compares the current context of the conversation against the configured reasons and decides whether any condition has been met.

* **Simple prompt agents**: End-call reasons are registered as an [OpenAI function tool](https://platform.openai.com/docs/guides/function-calling). The agent can invoke the `end_call` tool at any point when it detects a matching condition.
* **Flow Designer agents**: An `end_call <actual reason>` command is injected into the prompt for every state type (utterance, slot collection, action, transfer, terminal). The agent can issue this command whenever a condition is met. End-call conditions are also checked via a global evaluation step before each state transition, so they work even in verbatim utterance states that skip normal LLM processing.

<Note>
  End-call reasons work alongside the built-in 

  **goodbye detection**

  , which automatically ends calls when both parties exchange farewell expressions. Custom end-call reasons give you additional control for specific scenarios beyond normal conversation endings.
</Note>

## Configuring end-call reasons

### Dashboard

In the [agent editor](/the-agent-editor), open **Global Settings** and expand the **End-Call Reasons** accordion. Add each reason as a tag by typing the condition and pressing **Enter**.

Examples of useful end-call reasons:

* "Customer is being abusive or threatening"
* "Caller is asking for something outside our scope"
* "Fraud detected"
* "Wrong number"

### API

#### Legacy format (`end_call_reasons`)

<Warning>
  The 

  `end_call_reasons`

   string array format is deprecated. Use 

  `end_call_reasons_v2`

   instead for new integrations.
</Warning>

Include `end_call_reasons` on the nested **`agent` object** when [creating](/api-reference/platform-api/agents/create-assistant) or [updating](/api-reference/platform-api/agents/update-assistant) an agent. The API only applies values from `agent.end_call_reasons`; if you send `end_call_reasons` at the top level of the request body, it is ignored and does not cause an error.

```json
{
  "type": "outbound",
  "name": "Sales Assistant",
  "agent": {
    "prompt": "You are a helpful assistant.",
    "greeting_message": "Hello!",
    "llm": "gpt-4.1-Mini",
    "language": "en-US",
    "voice_id": "eleven_turbo_v2",
    "end_call_reasons": [
      "Customer is being abusive",
      "Fraud detected",
      "Wrong number"
    ]
  }
}
```

#### V2 format (`end_call_reasons_v2`)

The v2 format provides per-reason control over the closing message behavior. When both `end_call_reasons` and `end_call_reasons_v2` are present, `end_call_reasons_v2` takes precedence.

```json
{
  "end_call_reasons_v2": [
    {
      "reason": "Customer is being abusive",
      "closing_message_mode": "static",
      "closing_message": "I'm sorry, but I need to end this call. Goodbye."
    },
    {
      "reason": "Fraud detected",
      "closing_message_mode": "prompt",
      "closing_message": "Politely inform the caller that the interaction cannot continue due to security concerns."
    },
    {
      "reason": "Wrong number",
      "closing_message_mode": "none"
    }
  ]
}
```

Each object in the array has the following fields:

| Field                  | Type   | Required | Description                                                                                               |
| ---------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------- |
| `reason`               | string | Yes      | The condition that triggers call termination.                                                             |
| `closing_message_mode` | string | No       | Controls how the farewell message is generated. One of `static`, `prompt`, or `none`. Defaults to `none`. |
| `closing_message`      | string | No       | The closing message content. Interpretation depends on `closing_message_mode`.                            |

**Closing message modes:**

* **`static`** — The `closing_message` text is spoken verbatim to the caller before hanging up. The LLM-generated farewell is overridden.
* **`prompt`** — The `closing_message` is passed as an instruction to the LLM, which generates a contextual farewell following that guidance.
* **`none`** — The LLM generates a farewell message on its own (default behavior).

### Prompt-based end-call (`#end_call`)

You can also enable the `end_call` tool by including `#end_call` in your agent's system prompt, without configuring sidebar reasons. This is useful when you want the LLM to decide when to end calls based on prompt instructions alone.

When using prompt-based end-call, the `end_call` tool is available with no enum constraint on the reason field — the LLM can use any descriptive reason string guided by your prompt instructions. The built-in `conversation_ended` reason is always available for normal goodbyes.

Example prompt excerpt:

```
If the caller becomes abusive or uses threatening language, immediately end the
call using #end_call with an appropriate reason.
```

<Note>
  Both approaches work together: if you configure sidebar 

  `end_call_reasons_v2`

   AND include 

  `#end_call`

   in your prompt, the tool is available with enum reasons from the sidebar plus any prompt-guided behavior.
</Note>

### Flow Builder

In the **Global Settings** node, expand the **End-Call Reasons** section and add reasons using the modal interface.

## Post-call data

When a call is terminated by an end-call reason, the [post-call webhook](/post-call-webhook) includes:

| Field                    | Value                                                                                    |
| ------------------------ | ---------------------------------------------------------------------------------------- |
| `end_call_reason`        | `"normal"`                                                                               |
| `custom_end_call_reason` | The specific reason that triggered the termination (e.g., `"Customer is being abusive"`) |

The `custom_end_call_reason` field is only present when the call was ended by an end-call reason.