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

# Update Inbound Number Details

> Update your inbound agent's settings, prompt and other details.

### Headers

<ParamField header="authorization" type="string" required>
  Your API key for authentication.
</ParamField>

<ParamField header="encrypted_key" type="string">
  The `encrypted_key` for the Twilio account that owns the phone number you want to modify. Not required if you are using a Bland phone number.

  Learn more about BYOT [here](/tutorials/custom-twilio).
</ParamField>

### Path Parameters

<ParamField path="phone_number" type="string">
  The inbound phone number you wish to update.

  Formatting Notes:

  * The `'+'` or `'%2B'` prefix is optional.
  * Will assume a US country code if no country code is provided.

  Valid Examples for `+13334445555`:

  * `%2B13334445555`
  * `13334445555`
  * `3334445555`
</ParamField>

### Body

<ParamField body="prompt" type="string" required>
  Provide instructions, relevant information, and examples of the ideal conversation flow.

  For inbound numbers, consider including additional context about the purpose of the call, and what types of callers to expect.

  <Accordion title="Best Practices">
    #### Out-of-the-Box Behaviors (Summarized):

    * Speech pattern: Direct, concise, casual
    * Spells out symbols, acronyms, abbreviations, percentages, etc. (\$4,000,000 -> "four million dollars")
    * Asks clarifying questions

    #### Prompting Tips:

    * Want to easily test out exactly how your agent will behave?
      * [Try out Agent Testing!](https://app.bland.ai/home?page=testing)
    * Aim for less than >2,000 characters where possible.
    * Simple, direct prompts are the most predictable and reliable.
    * Frame instructions positively:
      * `"Do this"` rather than `"Don't do this"`.
      * Ex. "Keep the conversation casual" rather than "Don't be too formal".
      * This gives concrete examples of what to do, instead of leaving expected behavior open to interpretation.
  </Accordion>
</ParamField>

<ParamField body="pathway_id" type="string">
  Set the pathway that your agent will follow. This will override the `prompt` field, so there is no need to pass the 'prompt' field if you are setting a pathway.

  Warning: Setting a pathway will set the following fields to `null` / their default value - `prompt`, `first_sentence`, `model`, `dynamic_data`, `tools`, `transfer_list`

  Set to `null` or an empty string to clear the pathway.
</ParamField>

<ParamField body="pathway_version" type="integer">
  The version number of the pathway to use for the call. Defaults to the production version.
</ParamField>

### Agent Parameters (Body)

<ParamField body="voice" type="string">
  Set your agent's voice - all available voices can be found with the [List Voices](/api-v1/get/voices) endpoint.
</ParamField>

<ParamField body="background_track" type="string">
  Select an audio track that you'd like to play in the background during the call. The audio will play continuously when the agent isn't speaking, and is incorporated into it's speech as well.

  Use this to provide a more natural, seamless, engaging experience for the conversation. We've found this creates a significantly smoother call experience by minimizing the stark differences between total silence and the agent's speech.

  Options:

  * `null` - Default, will play audible but quiet phone static.
  * `office` - Office-style soundscape. Includes faint typing, chatter, clicks, and other office sounds.
  * `cafe` - Cafe-like soundscape. Includes faint talking, clinking, and other cafe sounds.
  * `restaurant` - Similar to `cafe`, but more subtle.
  * `none` - Minimizes background noise
</ParamField>

<ParamField body="first_sentence" type="string">
  Makes your agent say a specific phrase or sentence for its first response.
</ParamField>

<ParamField body="summary_prompt" type="string">
  (Optional) Custom instructions for how the call summary should be generated after the call completes. Use this to provide specific guidance or context for the AI when writing the post-call summary. Maximum length: 2000 characters.

  Example:

  ```json theme={null}
  {
    "summary_prompt": "Summarize the call in 2-3 sentences, focusing on the customer's main concern and any next steps discussed."
  }
  ```
</ParamField>

<ParamField body="block_interruptions" type="boolean" default="false">
  When set to `true`, the AI will not respond or process interruptions from the user.
</ParamField>

<ParamField body="interruption_threshold" type="number" default="500">
  Adjusts how patient the AI is when waiting for the user to finish speaking.

  Lower values mean the AI will respond more quickly, while higher values mean the AI will wait longer before responding.

  Recommended range: 50-200

  * 50: Extremely quick, back and forth conversation
  * 100: Balanced to respond at a natural pace
  * 200: Very patient, allows for long pauses and interruptions. Ideal for collecting detailed information.

  Try to start with 100 and make small adjustments in increments of \~10 as needed for your use case.
</ParamField>

<ParamField body="model" type="string" default="base">
  Select a model to use for your call.

  Options: `base` or `turbo`.

  In nearly all cases, `base` is the best choice for now.

  <Accordion title="Model Differences">
    There are two different ways to use Bland:

    * `model: base`
      * The original, follows scripts/procedures most effectively.
      * Supports all features and capabilities.
      * Best for Custom Tools

    * `model: turbo`
      * The absolute fastest latency possible, can be verbose at times
      * Limited capabilities currently (excludes Transferring, IVR navigation, Custom Tools)
      * Extremely realistic conversation capabilities
  </Accordion>
</ParamField>

<ParamField body="request_data" type="object" default="{}">
  Request data fields are available to the AI agent during the call when referenced in the associated pathway or task. This data is accessible in variables if the call is answered.
  For example, let's say in your app you want to programmatically set the name of the person you're calling. You could set `request_data` to:

  ```json Example theme={null}
    {
      "task": "Say hello to the user, who's name is {{name}}", // also works in the prompt, tools, etc.
      "request_data": {
        "name": "John Doe"
      }
    }
  ```
</ParamField>

<ParamField body="tools" type="array">
  Interact with the real world through API calls.

  Detailed tutorial here: [Custom Tools](/tutorials/custom-tools)
</ParamField>

<ParamField body="language" type="string" default="en-US">
  Select a supported language of your choice.
  Optimizes every part of our API for that language - transcription, speech, and other inner workings.

  <Accordion title="Expand to view language options">
    The available language options are as follows:

    * `auto` - Auto Detect
    * `en` - English
      * `en-US` - English (US)
      * `en-GB` - English (UK)
      * `en-AU` - English (Australia)
      * `en-NZ` - English (New Zealand)
      * `en-IN` - English (India)
    * `zh` - Chinese (Mandarin, Simplified)
      * `zh-CN` - Chinese (Mandarin, Simplified, China)
      * `zh-Hans` - Chinese (Mandarin, Simplified, Hans)
    * `zh-TW` - Chinese (Mandarin, Traditional)
      * `zh-Hant` - Chinese (Mandarin, Traditional, Hant)
    * `es` - Spanish
      * `es-419` - Spanish (Latin America)
    * `fr` - French
      * `fr-CA` - French (Canada)
    * `de` - German
    * `el` - Greek
    * `hi` - Hindi
      * `hi-Latn` - Hindi (Latin script)
    * `ja` - Japanese
    * `ko` - Korean
      * `ko-KR` - Korean (Korea)
    * `pt` - Portuguese
      * `pt-BR` - Portuguese (Brazil)
      * `pt-PT` - Portuguese (Portugal)
    * `it` - Italian
    * `nl` - Dutch
    * `pl` - Polish
    * `ru` - Russian
    * `sv` - Swedish
      * `sv-SE` - Swedish (Sweden)
    * `da` - Danish
      * `da-DK` - Danish (Denmark)
    * `fi` - Finnish
    * `id` - Indonesian
    * `ms` - Malay
    * `tr` - Turkish
    * `uk` - Ukrainian
    * `bg` - Bulgarian
    * `cs` - Czech
    * `ro` - Romanian
    * `sk` - Slovak
    * `hu` - Hungarian
    * `no` - Norwegian
    * `vi` - Vietnamese
    * `babel` - Babel (Experimental)
  </Accordion>
</ParamField>

<ParamField body="timezone" type="string" default="America/Los_Angeles">
  Set the timezone for the call. Handled automatically for calls in the US.

  This helps significantly with use cases that rely on appointment setting, scheduling, or behaving differently based on the time of day.

  Timezone options are [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) in the TZ identifier column.
</ParamField>

<ParamField body="transfer_phone_number" type="string">
  A phone number that the agent can transfer to under specific conditions - such as being asked to speak to a human or supervisor.

  Set to `null` to remove.

  <Accordion title="Prompting Notes">
    For best results:

    * Specify conditions that the agent should transfer to a human under (examples are great!)
    * In the `task`, refer to the action solely as "transfer" or "transferring".
    * Alternate phrasing such as "swap" or "switch" can mislead the agent, causing the action to be ignored.
  </Accordion>
</ParamField>

<ParamField body="fallback_number" type="string">
  A phone number to forward inbound calls to during Bland maintenance windows.

  Configure this ahead of any announced maintenance period. Setting this field does not affect normal call routing, your agent will continue to handle calls as usual. Bland activates the redirect only during maintenance, at which point calls are immediately forwarded to this number instead of reaching the agent.

  Set to `null` or an empty string to remove the configured fallback.
</ParamField>

<ParamField body="transfer_list" type="object">
  Give your agent the ability to transfer calls to a set of phone numbers.

  Overrides `transfer_phone_number` if a `transfer_list.default` is specified.

  Will default to `transfer_list.default`, or the chosen phone number.

  Example usage to route calls to different departments:

  ```json theme={null}
  "transfer_list": {
      "default": "+12223334444",
      "sales": "+12223334444",
      "support": "+12223334444",
      "billing": "+12223334444"
  }
  ```
</ParamField>

<ParamField body="dynamic_data" type="object">
  Integrate data from external APIs into your agent's knowledge.

  Set to `null` or an empty string to clear dynamic data settings.

  Detailed usage in the [Send Call](/api-v1/post/calls#param-dynamic-data) endpoint.
</ParamField>

<ParamField body="interruption_threshold" type="number" default="500">
  Adjusts how patient the AI is when waiting for the user to finish speaking.

  Lower values mean the AI will respond more quickly, while higher values mean the AI will wait longer before responding.

  Recommended range: 50-200

  * 50: Extremely quick, back and forth conversation
  * 100: Balanced to respond at a natural pace
  * 200: Very patient, allows for long pauses and interruptions. Ideal for collecting detailed information.

  Try to start with 100 and make small adjustments in increments of \~10 as needed for your use case.
</ParamField>

<ParamField body="keywords" type="string[]" default="[]">
  These words will be boosted in the transcription engine - recommended for proper nouns or words that are frequently mis-transcribed.

  For example, if the word "Reece" is frequently transcribed as a homonym like "Reese" you could do this:

  ```json theme={null}
  {
    "keywords": ["Reece"]
  }
  ```

  For stronger keyword boosts, you can place a colon then a boost factor after the word. The default boost factor is 2.

  ```json theme={null}
  {
    "keywords": ["Reece:3"]
  }
  ```
</ParamField>

<ParamField body="noise_cancellation" type="boolean" default="false">
  Toggles noise filtering or suppression in the audio stream to filter out background noise.
</ParamField>

<ParamField body="ignore_button_press" type="boolean" default="false">
  When `true`, DTMF (digit) presses are ignored, disabling menu navigation or call transfers triggered by keypad input.
</ParamField>

### Call Settings (Body)

<ParamField body="max_duration" type="integer" default="30">
  When the call starts, a timer is set for the `max_duration` minutes. At the end of that timer, if the call is still active it will be automatically ended.

  Example Values: `20, 2`
</ParamField>

<ParamField body="webhook" type="string">
  When the call ends, we'll send the call details in a POST request to the URL you specify here.

  The request body will match the response from the [GET /v1/calls/:call\_id](/api-v1/get/calls-id) endpoint.
</ParamField>

<ParamField body="webhook_events" type="array">
  Specify which events you want to stream to the webhook, during the call.

  Options:

  * `queue`
  * `call`
  * `latency`
  * `webhook`
  * `tool`
  * `dynamic_data`
  * `citations` (Sent separately, Enterprise only)

  Example payloads:

  <CodeGroup>
    ```json queue theme={null}
    // ex 1
    {
      "message": "Call enqueued",
      "call_id": "12345678-1234-1234-1234-123456789abc",
      "category": "queue",
      "log_level": "info"
    }
    ```

    ```json call theme={null}
    // ex 1
    {
      "message": "Call connected",
      "call_id": "12345678-1234-1234-1234-123456789abc",
      "category": "call",
      "log_level": "info"
    }
    // ex 2
    {
      "message": "Sending first sentence: Hello, thank you for reaching out. I'd like to get to know you a bit better. How are you feeling today?",
      "call_id": "12345678-1234-1234-1234-123456789abc",
      "category": "call",
      "log_level": "info"
    }
    // ex 3
    {
      "message": "Agent speech: Hello, thank you for reaching out.",
      "call_id": "12345678-1234-1234-1234-123456789abc",
      "category": "call",
      "log_level": "info"
    }
    // ex 4
    {
      "message": "Handling user speech: Yeah. I'm thirty six. And I'm five foot nine.",
      "call_id": "12345678-1234-1234-1234-123456789abc",
      "category": "call",
      "log_level": "info"
    }
    // ex 5
    {
      "message": "Webhook Response: 200  | Webhook Response Data: [object Object] | Response Time: 689ms",
      "call_id": "87654321-4321-4321-4321-cba987654321",
      "category": "call",
      "log_level": "info"
    }
    ```

    ```json latency theme={null}
    // ex 1
    {
      "message": "TTS: 218ms",
      "call_id": "12345678-1234-1234-1234-123456789abc",
      "category": "latency",
      "log_level": "performance"
    }
    // ex 2
    {
      "message": "LLM: 266ms",
      "call_id": "12345678-1234-1234-1234-123456789abc",
      "category": "latency",
      "log_level": "performance"
    }
    ```

    ```json webhook theme={null}
    {
      "message": "Storing dynamic data messages: \n\n answer : \"true\"",
      "call_id": "87654321-4321-4321-4321-cba987654321",
      "category": "call",
      "log_level": "info"
    }
    ```

    ```json tool theme={null}
    {
      "message": "Executing custom tool: Test Tool 4 with input: [object Object]",
      "call_id": "abcdef12-3456-7890-abcd-ef1234567890",
      "category": "call",
      "log_level": "info"
    }
    ```

    ```json dynamic_data theme={null}
    {
      "message": "Storing dynamic data: \n\n vector_data : {\"data\":{\"results\":[{\"id\":\"fedcba98-7654-3210-fedc-ba9876543210\",\"input_text\":\"Here are details on the restaurant...\",\"similarity\":0.103339002763233,\"chunk_index\":0}]},\"errors\":null}",
      "call_id": "abcdef12-3456-7890-abcd-ef1234567890",
      "category": "call",
      "log_level": "info"
    }
    ```

    ```json citations theme={null}
    {
      "call_id": "12345678-1234-1234-1234-123456789abc",
      "user_id": "11111111-2222-3333-4444-555555555555",
      "event_type": "citations",
      "timestamp": "2025-07-03T16:41:15.231Z",
      "citations": [
        {
          "call_id": "12345678-1234-1234-1234-123456789abc",
          "variable_name": "User height",
          "variable_type": "boolean",
          "value": true,
          "cited_utterances": [
            {
              "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
              "idx": 3,
              "start_time": 24.096,
              "end_time": 27.424,
              "confidence": 0.17166666666666666,
              "channel": 1,
              "transcript": "I am 36 and I am 5'9\".",
              "speaker_id": "SPEAKER_1_0",
              "speaker_name": null,
              "speaker_description": null,
              "topics": [
                "customer_information_provided"
              ],
              "topics_meta": "{\"customer_information_provided\":\"customer providing personal details\"}",
              "utterance_type": "answer"
            }
          ],
          "schema_id": "99999999-8888-7777-6666-555555555555"
        },
        {
          "call_id": "12345678-1234-1234-1234-123456789abc",
          "variable_name": "Caller Age",
          "variable_type": "number",
          "value": 36,
          "cited_utterances": [
            {
              "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
              "idx": 3,
              "start_time": 24.096,
              "end_time": 27.424,
              "confidence": 0.17166666666666666,
              "channel": 1,
              "transcript": "I am 36 and I am 5'9\".",
              "speaker_id": "SPEAKER_1_0",
              "speaker_name": null,
              "speaker_description": null,
              "topics": [
                "customer_information_provided"
              ],
              "topics_meta": "{\"customer_information_provided\":\"customer providing personal details\"}",
              "utterance_type": "answer"
            },
            {
              "id": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
              "idx": 4,
              "start_time": 30.56,
              "end_time": 35.455,
              "confidence": 0.5672727272727273,
              "channel": 0,
              "transcript": "All right. So you're 36 years old and five foot nine. That's great. How's your day been so far? Anything exciting happened?",
              "speaker_id": "SPEAKER_0_0",
              "speaker_name": null,
              "speaker_description": null,
              "topics": [
                "day_review_inquiry"
              ],
              "topics_meta": "{\"day_review_inquiry\":\"agent inquiring about the customer's day and any exciting events\"}",
              "utterance_type": "question"
            }
          ],
          "schema_id": "99999999-8888-7777-6666-555555555555"
        },
        {
          "call_id": "12345678-1234-1234-1234-123456789abc",
          "variable_name": "Caller feeling",
          "variable_type": "string",
          "value": null,
          "cited_utterances": [],
          "schema_id": "99999999-8888-7777-6666-555555555555"
        }
      ]
    }
    ```
  </CodeGroup>
</ParamField>

<ParamField body="analysis_schema" type="object">
  Define a JSON schema for how you want to get information about the call - information like email addresses, names, appointment times or any other type of custom data.

  In the webhook response or whenever you retrieve call data later, you'll get the data you defined back under `analysis`.

  For example, if you wanted to retrieve this information from the call:

  ```json theme={null}
  "analysis_schema": {
    "email_address": "email",
    "first_name": "string",
    "last_name": "string",
    "wants_to_book_appointment": "boolean",
    "appointment_time": "YYYY-MM-DD HH:MM:SS"
  }
  ```

  You would get it filled out like this in your webhook once the call completes:

  ```json theme={null}
  "analysis": {
    "email_address": "johndoe@gmail.com",
    "first_name": "John",
    "last_name": "Doe",
    "wants_to_book_appointment": true,
    "appointment_time": "2024-01-01 12:00:00"
  }
  ```
</ParamField>

<ParamField body="metadata" type="object">
  Add any additional information you want to associate with the call. This can be useful for tracking or categorizing calls.
</ParamField>

<ParamField body="summary_prompt" type="string">
  At the end of each call, a `summary` is generated based on the transcript - you can use this field to add extra instructions and context for how it should be summarized.

  For example: `"Summarize the call in French instead of English."`
</ParamField>

<ParamField body="analysis_prompt" type="string">
  Guides the output and provides additional instructions and clarifications for the `analysis_schema`.
</ParamField>

<ParamField body="record" type="boolean" default="false">
  To record your phone call, set `record` to true. When your call completes, you can access through the `recording_url` field in the call details or your webhook.
</ParamField>

<ParamField body="citation_schema_ids" type="string[]">
  The citation schema is an incredibly powerful tool for running ***post call analysis***, including specific variable extractions, conditional logic, and more.

  You can build a citation schema [here](https://app.bland.ai/dashboard/analytics?tab=citations).

  > Note: Citation schemas are very powerful and accurate, but also are more resource intensive to run. As such, for the time being, they are an enterprise-only feature.
</ParamField>

### Response

<ResponseField name="status" type="string">
  Whether the update was successful or not - will be `success` or `error`.
</ResponseField>

<ResponseField name="message" type="string">
  A message describing the status of the update.
</ResponseField>

<ResponseField name="updates" type="object">
  An object containing the updated settings for the inbound number.
</ResponseField>

<ResponseField name="failed_updates" type="object">
  If the update was unsuccessful, this will contain the settings that failed to update. Useful to determine how your request is being interpreted on our end.
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
      "status": "success",
      "message": "Successfully updated number +18584139939.",
      "updates": {
          "prompt": "(Your prompt)",
          "voice": "maya",
          "webhook": null,
          "first_sentence": "Roberta speaking, how can I help you?",
          "record": false,
          "max_duration": 30,
          "model": "base",
          //...
      }
  }
  ```
</ResponseExample>

***

Docs for agents: [llms.txt](/llms.txt)