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

# Create a Web Agent

> Configure all of the settings for a new web agent.

### Headers

**authorization** `string` *required*

Your API key for authentication.

Example web call usage (client side):

```javascript theme={null}
import { BlandWebClient } from 'bland-client-js-sdk';

const agentId = 'YOUR-AGENT-ID';
const sessionToken = 'YOUR-SESSION-TOKEN';


document.addEventListener('DOMContentLoaded', async () => {
    document.getElementById('btn').addEventListener('click', async () => {
        const blandClient = new BlandWebClient(
            agentId,
            sessionToken
        );
        await blandClient.initConversation({
            sampleRate: 44100,
        });
    });
});
```

### Body

**prompt** `string` *required*

Provide instructions, relevant information, and examples of the ideal conversation flow.

> [accordion] 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
> * Ends call when objective is complete or voicemail is detected
>
> #### 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.

**voice** `string`

Set your agent's voice - all available voices can be found with the [List Voices](https://docs.bland.ai/api-v1/get/voices.md) endpoint.

**webhook** `string`

Set a webhook URL to receive call data after the web call completes.

**metadata** `object`

Add any additional information you want to associate with the call. This can be useful for tracking or categorizing calls.

**pathway\_id** `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`, `dynamic_data`, `tools`, `transfer_list`

Set to `null` or an empty string to clear the pathway.

**language** `string` (default: ENG)

Select a supported language of your choice.
Optimizes every part of our API for that language - transcription, speech, and other inner workings.

Supported Languages and their codes can be found [here](https://docs.bland.ai/api-v1/post/calls.md#param-language).

**first\_sentence** `string`

A phrase that your call will start with instead of a generating one on the fly. This works both with and without `wait_for_greeting`. Can be more than one sentence, but must be less than 200 characters.

To remove, set to `null` or an empty string.

**tools** `array`

Interact with the real world through API calls.

Detailed tutorial here: [Custom Tools](https://docs.bland.ai/tutorials/custom-tools)

**dynamic\_data** `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](https://docs.bland.ai/api-v1/post/calls.md) endpoint.

**interruption\_threshold** `number` (default: 500)

Legacy. Sets a fixed wait, in milliseconds, after the caller stops speaking before the AI responds. We recommend leaving this unset: response timing adapts to each caller automatically (see [Agent Speech](https://docs.bland.ai/tutorials/agent-speech.md)).

To control how readily the AI stops when the caller talks over it, use `interruptibility`.

**interruptibility** `integer` (default: 2)

Controls how readily the AI stops speaking when the caller talks over it. A higher value yields more easily; a lower value holds the turn through more of the caller's speech.

* `0`: Block. The AI ignores interruptions and finishes speaking (same as `block_interruptions: true`).
* `1`: Difficult. Harder to interrupt.
* `2`: Balanced (default).
* `3`: Easy. The AI stops quickly when the caller begins speaking.
* `4`: Always interrupt. Any caller speech stops the AI, including brief acknowledgments like "uh-huh".

See [Agent Speech](https://docs.bland.ai/tutorials/agent-speech.md) for how each level behaves.

**keywords** `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"]
}
```

**max\_duration** `number` (default: 30)

The maximum duration that calls to your agent can last before being automatically terminated.

Set to `null` to reset to default.

### Response

**status** `string`

Can be `success` or `error`.

**call\_id** `string`

A unique identifier for the call (present only if status is `success`).

```json Response theme={null}
{
  "agent": {
        "agent_id": "2c565dc7-f41f-43db-a99f-e4c8ba9d7d18",
        "dynamic_data": null,
        "interruption_threshold": null,
        "first_sentence": null,
        "voice_settings": null,
        "voice": "Karen",
        "prompt": "...",
        "temperature": null,
        "max_duration": 30,
        "language": "ENG",
        "tools": null
  }
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.