> ## Documentation Index
> Fetch the complete documentation index at: https://docs.volubile.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Failover workflow

> Failover workflows allow you to define a custom error management strategy before the call for your inbound agents.

Failover workflows are particularly useful for managing errors in a custom way and ensuring service continuity:

* Transfer the call to an advisor in case of infrastructure unavailability
* Play an unavailability message adapted to the context
* Intelligently route calls according to customer profile despite the error

<Info>
  The failover workflow consists of two mandatory main steps:

  1. **Failover trigger** - Initializes the workflow with the available pre-call context
  2. **Failover action return** - Defines the action to execute (call transfer or voice message)
</Info>

## Configuring the failover trigger

The failover trigger is the starting point of your workflow. It gives you access to the pre-call context to determine the best fallback strategy.

<Steps>
  <Step title="Create a data sample">
    To effectively test your workflow, you must generate a representative data sample:

    1. In the configuration interface, locate the **Generate a data sample** section
    2. Click the **Load a data sample** button
  </Step>

  <Step title="Configure the test data">
    Once the sample is loaded, you can customize the data according to your needs:

    1. Copy and paste the data into the **Test input data** area
    2. Modify the values to simulate different contexts
    3. Click **Test** to validate the configuration
  </Step>
</Steps>

<Note>
  The failover workflow receives the **pre-call context** that was available before the error, as well as **system variables** (caller number, agent concerned, etc.). It does **not receive information about the reason** that triggered the failover.
</Note>

<Warning>
  Ensure that the JSON format is valid before testing your configuration. An incorrect format will cause errors during workflow execution.
</Warning>

## Configuring the return

The last step of the workflow allows you to define the failover action that will be executed to manage the error.

<Info>
  The failover workflow can work in two ways:

  1. **Without action return**: The workflow only performs actions (API calls, notifications, etc.) and the call will be hung up at the end of the webhook execution
  2. **With action return**: The workflow ends with a **Respond to the agent** containing a failover action (voice message or call transfer)
</Info>

<Note>
  The failover action return allows you to:

  * Define the fallback behavior adapted to the context
  * Intelligently transfer the call to the right resources
  * Customize error messages according to customer profile
  * Guarantee a consistent user experience despite the technical error
</Note>

In the **Respond to the agent** step interface, you can define the response structure in JSON format using the data selector to access variables from previous steps.

<Card title="Configure failover actions" icon="bolt" href="../../product/agents/actions/failover" horizontal />

## Return structure

In the **Respond to the agent** step interface, you must return a failover action in JSON format. Two types of actions are available:

### Option 1: Call transfer

Transfers the call to a phone number or SIP destination.

**Transfer to a phone number:**

```json theme={null}
{
  "type": "FAILOVER_TRANSFER_CALL",
  "config": {
    "phone": "+33199001234",
    "ringTimeout": 30
  }
}
```

**Transfer via SIP connection:**

```json theme={null}
{
  "type": "FAILOVER_TRANSFER_CALL",
  "config": {
    "phone": "sip-destination-id",
    "sipOutboundConnectionId": "connection-id",
    "headers": {
      "X-Customer-Tier": "premium"
    },
    "standardSipHeaders": {
      "User-To-User": "custom value"
    },
    "ringTimeout": 30
  }
}
```

**Parameters:**

* `type`: Must be `"FAILOVER_TRANSFER_CALL"`
* `config.phone`:
  * **Without SIP connection**: Phone number in international format (e.g.: `+33199001234`)
  * **With SIP connection**: SIP destination identifier
* `config.ringTimeout`: Maximum ring duration in seconds before interrupting the transfer and resuming the call with the agent (default: 30)
* `config.sipOutboundConnectionId` (optional): Identifier of the outbound SIP connection to use
* `config.headers` (optional): Custom SIP headers (key-value format). Only usable if `sipOutboundConnectionId` is specified
* `config.standardSipHeaders` (optional): Standard User-To-User SIP header to customize. Only usable if `sipOutboundConnectionId` is specified. Format: `{"User-To-User": "value"}`

### Option 2: Voice message

Plays a voice message then ends the call.

```json theme={null}
{
  "type": "FAILOVER_SAY",
  "config": {
    "sentence": "Our services are temporarily unavailable. Please call back later.",
    "language": "en-US"
  }
}
```

**Parameters:**

* `type`: Must be `"FAILOVER_SAY"`
* `config.sentence`: The text to speak to the caller
* `config.language`: The language of the message (ISO format: `fr-FR`, `en-US`, etc.)

<Warning>
  The call will be automatically terminated after the message is played. Make sure your message is clear and complete.
</Warning>