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

# Dynamic configuration

## Overview

Dynamic configuration allows you to personalize the behavior of your voice agent during the ringing of a call. This feature offers complete flexibility to adapt the agent to the specifics of each interaction.

<Info>This configuration is intended for use during [pre-call workflows](/en/integrations/workflows/pre-call).</Info>

## Configuration Structure

The configuration revolves around a structured JSON object that defines all of the agent's operational parameters:

```json theme={null}
{
    "initialMessage": "Initial message",
    "prompt": "System prompt",
    "synthesizer": {...},
    "callDurationLimit": "600",
    "rag": {...},
    "extractors": [...],
    "classifiers": [...],
    "actions": [...],
    "recordAudio": false
}
```

## Configuration Detail

<ResponseField name="initialMessage" type="string">
  Greeting message that the agent will use to start the conversation with the caller.
</ResponseField>

<ResponseField name="prompt" type="string" required>
  Main instructions defining the behavior, personality, and guidelines the agent should follow during the call.
</ResponseField>

<ResponseField name="synthesizer" type="object" required children="blabla">
  Configuration for the agent's voice synthesis engine.

  <Expandable title="child attributes" defaultOpen="True">
    <ResponseField name="synthesizer.textNormalizationPatterns" type="object">
      Rules for [vocal substitutions](/en/product/agents/tts#voice-substitutions) of text before voice synthesis to improve pronunciation.

      The keys represent the terms to be normalized. The values can be:

      * A string for a simple replacement
      * An object with specific translations by locale

      ```json Example theme={null}
      {
          "kg": "kilogram",
          "cm": {
              "fr-FR": "centimeter",
              "en-US": "centimeter"
          }
      }
      ```
    </ResponseField>

    <ResponseField name="synthesizer.voice" type="object" required>
      Parameters for the synthesized voice.

      ```json Example theme={null}
      {
          "locales": ["fr-FR", "en-US"],
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "model": "eleven_multilingual_v2"
      }
      ```

      <Expandable title="child attributes" defaultOpen="True">
        <ResponseField name="synthesizer.voice.locales" type="array" required>
          List of languages supported by the agent (`ISO 639-1` codes).
        </ResponseField>

        <ResponseField name="synthesizer.voice.id" type="string" required>
          Unique identifier of the selected voice in the Volubile catalog.
        </ResponseField>

        <ResponseField name="synthesizer.voice.model" type="string">
          Identifier of the voice synthesis model to use for this voice.

          Allowed values:

          * `eleven_v3`
          * `eleven_multilingual_v2`
          * `eleven_flash_v2_5`

          <Info>This parameter is only applied for voices whose provider supports model selection. In practice, the override is applied for ElevenLabs voices and ignored for other providers.</Info>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="callDurationLimit" type="number" default="1800">
  Maximum allowed duration for the call before hanging up, expressed in seconds.
</ResponseField>

<ResponseField name="rag" type="object">
  Configuration of the RAG (Retrieval-Augmented Generation) database.

  <Expandable title="child attributes" defaultOpen="True">
    <ResponseField name="rag.datasourceIds" type="array" required>
      List of unique identifiers of the RAG databases to be used to enrich the agent's responses.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="extractors" type="array">
  List of [extractors](/en/product/calls/extractors) of information that the agent should use during the call.

  ```json Example theme={null}
  [
      {
          "name": "Client's First Name",
          "description": "Client's First Name"
      },
      {
          "name": "Client's Last Name",
          "description": "Client's Last Name"
      }
  ]
  ```

  <Expandable title="child attributes" defaultOpen="True">
    <ResponseField name="extractors[].name" type="string" required>
      Name of the information to extract.
    </ResponseField>

    <ResponseField name="extractors[].description" type="string" required>
      Detailed description of the information to extract to guide the agent.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="classifiers" type="array">
  List of [classifiers](/en/product/calls/classifiers) to automatically categorize calls.

  ```json Example theme={null}
  [
      {
          "name": "Default Classifier",
          "labels": ["Appointment Booking", "General Information", "..."],
          "description": "Detailed classification prompt..."
      },
      {
          "name": "Processing",
          "labels": ["Transfer Failed", "Call Forwarded", "..."],
          "description": "Detailed classification prompt..."
      }
  ]
  ```

  <Expandable title="child attributes" defaultOpen="True">
    <ResponseField name="classifiers[].name" type="string" required>
      Name of the classifier.
    </ResponseField>

    <ResponseField name="classifiers[].labels" type="string[]" required>
      List of available classification labels.
    </ResponseField>

    <ResponseField name="classifiers[].description" type="string" required>
      Detailed instructions in the form of a prompt defining the classification rules for each label.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="actions" type="array">
  List of actions the agent can perform during the call.

  <Expandable title="child attributes" defaultOpen="True">
    <ResponseField name="actions[].name" type="string" required>
      Name of the action.
    </ResponseField>

    <ResponseField name="actions[].type" type="string" required>
      Type of action. Possible values: `TRANSFER_CALL`.
    </ResponseField>

    <ResponseField name="actions[].description" type="string" required>
      Detailed instructions for using the action form as a prompt.
    </ResponseField>

    <ResponseField name="actions[].headers" type="object">
      Custom HTTP headers to be transmitted during the execution of the action.

      <Warning>Available only in SIP transfer</Warning>
    </ResponseField>

    <ResponseField name="actions[].ringTimeout" type="number" default="20">
      Maximum wait time during a call transfer, expressed in seconds.
    </ResponseField>

    <ResponseField name="actions[].sipOutboundConnectionId" type="string">
      Identifier for the outgoing SIP connection used for transfers.
    </ResponseField>

    <ResponseField name="actions[].availability" type="object">
      Global availability of the action by day of the week. Can be `null` if no restriction.

      ```json Example theme={null}
      {
          "MONDAY": [
              {
                  "startTime": "07:30",
                  "endTime": "12:30"
              },
              {
                  "startTime": "13:15",
                  "endTime": "18:00"
              }
          ]
      }
      ```

      <Expandable title="child attributes" defaultOpen="True">
        <ResponseField name="actions[].availability.MONDAY" type="array">
          Time slots available on Monday.

          <ResponseField name="actions[].allowedToPhones[].availability.MONDAY[].startTime" type="string">
            Start time of availability in HH:MM format.
          </ResponseField>

          <ResponseField name="actions[].allowedToPhones[].availability.MONDAY[].endTime" type="string">
            End time of availability in HH:MM format.
          </ResponseField>
        </ResponseField>

        <ResponseField name="actions[].availability.TUESDAY" type="array">
          Time slots available on Tuesday.
        </ResponseField>

        <ResponseField name="actions[].availability.WEDNESDAY" type="array">
          Time slots available on Wednesday.
        </ResponseField>

        <ResponseField name="actions[].availability.THURSDAY" type="array">
          Time slots available on Thursday.
        </ResponseField>

        <ResponseField name="actions[].availability.FRIDAY" type="array">
          Time slots available on Friday.
        </ResponseField>

        <ResponseField name="actions[].availability.SATURDAY" type="array">
          Time slots available on Saturday.
        </ResponseField>

        <ResponseField name="actions[].availability.SUNDAY" type="array">
          Time slots available on Sunday.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="actions[].allowedToPhones" type="array">
      List of authorized phone numbers or SIP identifiers for transfers.

      <Expandable title="child attributes" defaultOpen="True">
        <ResponseField name="actions[].allowedToPhones[].phone" type="string" required>
          Phone number or SIP identifier of the destination for the transfer.

          <Warning>A SIP identifier can only be used if a SIP connection (materialized by the reference provided in `actions[].sipOutboundConnectionId`) has been previously created.</Warning>
        </ResponseField>

        <ResponseField name="actions[].allowedToPhones[].description" type="string" required>
          Description of the destination and instructions to trigger the transfer.
        </ResponseField>

        <ResponseField name="actions[].allowedToPhones[].availability" type="object">
          Specific availability of this destination by day of the week. Can be `null` if no restriction.

          Structure identical to `actions[].availability` with the same days of the week.

          ```json Example theme={null}
          [
              {
                  "startTime": "07:30",
                  "endTime": "12:30"
              },
              {
                  "startTime": "13:15",
                  "endTime": "18:00"
              }
          ]
          ```

          <ResponseField name="actions[].allowedToPhones[].availability.*[].startTime" type="string">
            Start time of availability in HH:MM format.
          </ResponseField>

          <ResponseField name="actions[].allowedToPhones[].availability.*[].endTime" type="string">
            End time of availability in HH:MM format.
          </ResponseField>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="recordAudio" type="boolean">
  Enables (true) or disables (false) audio call recording.
</ResponseField>

## Concise Example: Changing Voice and Language

```json theme={null}
{
    "initialMessage": "Hello! I'm your virtual assistant. How can I help you today?",
    "synthesizer": {
        "voice": {
            "locales": ["en-US"],
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
    }
}
```

```json theme={null}
{
    "initialMessage": "Bonjour! Je suis votre assistant virtuel. Comment puis-je vous aider aujourd'hui?",
    "synthesizer": {
        "voice": {
            "locales": ["fr-FR"],
            "id": "24b1c3cc-0d44-4b50-8888-8dd25736052a"
        }
    }
}
```

## Complete Example

```json theme={null}
{
    "initialMessage": "Initial message",
    "prompt": "Prompt",
    "synthesizer": {
        "voice": {
            "locales": ["fr-FR", "en-US"],
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        },
        "textNormalizationPatterns": {
            "kg": "kilogram",
            "cm": {
            	"fr-FR": "centimeter",
            	"en-US": "centimeter"
            }
        }
    },
    "callDurationLimit": "600",
    "rag": {
        "datasourceIds": ["3c90c3cc-0d44-4b50-8888-8dd25736052a", "4c90c3cc-0d44-4b50-8888-8dd25736052a"]
    },
    "extractors": [
        {
            "name": "Client's First Name",
            "description": "Client's First Name"
        },
        {
            "name": "Client's Last Name",
            "description": "Client's Last Name"
        }
    ],
    "classifiers": [
        {
            "name": "Default Classifier",
            "labels": ["Appointment Booking", "General Information", "..."],
            "description": "Prompt: You are an expert in classifying phone calls from call transcriptions.\n\nHere are the rules to follow to assign a label to each call:\n\n- \"Appointment Booking\": ..."
        },
        {
            "name": "Processing",
            "labels": ["Transfer Failed", "Call Forwarded", "..."],
            "description": "Prompt: You are an expert in classifying phone calls from call transcriptions.\n\nHere are the rules to follow to assign a label to each call:\n\n- \"Transfer Failed\": ..."
        }
    ],
    "actions": [
        {
            "name": "Support transfer",
            "type": "TRANSFER_CALL",
            "description": "Prompt: Allows you to transfer the call to another number. Confirm once more with the interlocutor that they agree to be transferred before proceeding with the transfer.",
            "headers": {
                "Volubile-Cli": "12345"
            },
            "ringTimeout": 30,
            "sipOutboundConnectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "availability": null,
            "allowedToPhones": [
                {
                    "phone": "sip-cli",
                    "description": "Prompt to trigger transfer to a sip trunk",
                    "availability": null
                },
                {
                    "phone": "+33612345678",
                    "description": "Prompt to trigger transfer to a specific number, customer service, etc.",
                    "availability":
                    {
                        "MONDAY": [
                            {
                                "startTime": "07:30",
                                "endTime": "12:30"
                            },
                            {
                                "startTime": "13:15",
                                "endTime": "18:00"
                            }
                        ],
                        "TUESDAY": [],
                        "WEDNESDAY":  [],
                        "THURSDAY": [
                            {
                                "startTime": "07:30",
                                "endTime": "12:30"
                            },
                            {
                                "startTime": "13:15",
                                "endTime": "18:00"
                            }
                        ],
                        "FRIDAY": [],
                        "SATURDAY": [],
                        "SUNDAY":  []
                    }
                }
            ]
        }
    ],
    "recordAudio": true
}
```