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

# Inbound Webhook

> Load API data before an inbound call and use it in the greeting, AI instruction, forwarding, and post-processing.

## Overview

The **Inbound Webhook** sends an HTTP request before the voice agent accepts an incoming call. Values from the JSON response become variables. You can use them in the initial greeting, the AI instruction (user prompt), a call-forwarding destination, and post-processing.

Typical examples include the customer's name, plan, customer ID, or the phone number of their account contact. The voice agent can use this information to greet callers personally, answer with relevant context, and forward them to the right destination.

> [!NOTE]
>
> The Inbound Webhook only runs for incoming calls. The HTTP request must finish before the voice agent accepts the call.

## Open the Inbound Webhook

**1. Open the voice agent**

Open the voice agent you want and switch to the **Advanced** tab.

**2. Configure the Inbound Webhook**

Open the **Inbound Webhook** card and click **Configure**.

**3. Enable the feature**

Once you have saved a valid configuration, use the toggle on the card to enable or pause the Inbound Webhook.

![Inbound Webhook in the Advanced tab](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/overview.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=0b0852dbace48ec6bca680e8e9f12556)

## 1. Configure the connection

In the first step, choose when and how the HTTP request is sent.

![Configure the connection, timeout, and system variables](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/connection-system-variables.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=2c107a8dc1146fc4922f9beab084b4aa)

### Timeout

The **timeout** determines the maximum time the system waits for the API. You can enter a value between **250 ms and 30,000 ms (30 seconds)**. The default is **5,000 ms**.

A longer timeout gives a slow API more time, but it also delays call acceptance. Use the lowest value at which your API responds reliably.

### Behavior on error or timeout

Under **On error or timeout**, two options are available:

| Option | Behavior |
| - | - |
| **Continue call with default values** | The call is accepted. Each unavailable variable uses its configured default value. A variable without a default remains empty. |
| **Do not accept call** | The voice agent does not accept the call if the HTTP request fails or exceeds the timeout. |

> [!TIP]
>
> For most use cases, **Continue call with default values** is the more robust setting. The voice agent remains reachable even if the connected system is temporarily unavailable.

### HTTP method and endpoint

The available HTTP methods are `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`. The endpoint URL must start with `https://`.

* System variables can be used in the URL path or query string, for example `https://api.example.com/customers/{{caller_number}}`.
* With `POST`, `PUT`, `PATCH`, and `DELETE`, you can also configure a JSON body.
* `GET` requests are sent without a request body.

### Authentication

The Inbound Webhook supports **no authentication**, **Bearer token**, **API key header**, **Basic auth**, **OAuth 2.0**, and **JWT OAuth**. For OAuth 2.0 and JWT OAuth, select an existing saved connection. Credentials are not shown in the technical test details.

### Send call data as system variables

The following system variables are available before the call:

| Variable | Meaning |
| - | - |
| `{{caller_number}}` | Phone number of the incoming caller. The value can be empty for anonymous calls. |
| `{{called_number}}` | The customer-facing destination number reached by the caller. |
| `{{forwarded_from_number}}` | Forwarding identifier supplied by the telephony provider, if available. It can contain a phone number or a technical identifier. |

You can use these variables in the **endpoint URL**, in **additional headers**, and - for methods with a request body - in the **JSON body**. Click a supported field and type `{{`. Then select the required variable from the list.

Example additional header:

| Key | Value |
| - | - |
| `X-Customer-Number` | `{{caller_number}}` |

If call information is unavailable, an empty value is inserted. The placeholder itself is never sent to your API.

> [!NOTE]
>
> In the **Inbound Webhook HTTP request**, use the system variables shown above without a namespace, for example `{{caller_number}}`. Use **values from the API response** with `pre_call` afterwards, for example `{{pre_call.first_name}}`.

## 2. Test the connection and inspect the response

In the second step, you can call your real API with sample data of your choice. All three phone number fields are optional and affect this test only.

![Optional sample data for the HTTP request](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/test-inputs.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=bd5c22c27366d7c57d661f62a7349c7f)

* **caller\_number** simulates the caller's phone number.
* **called\_number** simulates the called destination number.
* **forwarded\_from\_number** simulates a forwarded call.

Enter the values your API needs for a realistic test and click **Run test**. In the test, these values replace the matching placeholders in the URL, headers, and JSON body.

After a successful test, you see the HTTP status and request duration. Below that, you can select individual values directly from the response. Each selected value becomes an Inbound Webhook variable in the third step.

![Select fields directly from the test response](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/test-select-fields.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=c8176649b30afd6fbff4c59e8d9a0054)

### Technical details

Open **Technical details** to inspect two views side by side:

* **Final request preview** shows the method, URL, headers, and body after system variables have been replaced. Sensitive authentication values are redacted.
* **JSON response** shows the response returned by your API during the test.

![Final request preview and JSON response](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/technical-details.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=2fd0eb4f9b64d41f667c811f93dc7bc5)

### Search the response

For large responses, search by field name, response path, or value. Then select the required scalar field using its checkbox.

![Search for a field in the JSON response](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/search-response.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=6ffb6560eb071ac02b6dc79c6293a630)

Only scalar values can become variables: text, numbers, and `true` or `false`. For objects and arrays, select the specific value inside the structure.

## Dot notation for nested responses and arrays

Response paths use **dot notation**. Each dot moves one level deeper. For arrays, the index is also a path segment and starts at `0`.

Examples:

| Content | Response path |
| - | - |
| Field `firstName` in the first item of the `users` array | `users.0.firstName` |
| Field `sku` of the second item in the first order | `orders.0.items.1.sku` |
| Nested company address | `company.address.address` |

![Array elements in dot notation](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/array-dot-notation.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=84f004f2a2716737352f6feed075291f)

> [!NOTE]
>
> The selection list shows at most the first 1,000 scalar response fields. For larger responses, use search or manually enter a known dot path in the next step.

### Configure without a successful test

Testing is optional. If your API cannot be tested from the configuration dialog, continue to the **Variables** step. Create the variable name there and manually enter the expected response path using dot notation.

## 3. Define variables and default values

In the final step, review and edit the variable mappings.

![Variable names, response paths, and default values](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/variable-mapping.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=e073832d3620810a9a416435930e7736)

| Field | Meaning |
| - | - |
| **Variable** | The name you later use as a placeholder, for example `first_name`. In other fields, use it as `{{pre_call.first_name}}`. |
| **Response path** | The exact position of the value in the JSON response, for example `users.0.firstName`. |
| **Default value** | Optional replacement value used when no usable value is found at the response path. |

The default value is used when the path is missing, the value is `null` or empty, or the path points to an object or array instead of a scalar value. If **Continue call with default values** is selected, default values are also used when the request fails or times out.

Without a default value, the variable remains empty. The greeting never reads out an unresolved placeholder such as `{{pre_call.first_name}}`.

## Use variables in the voice agent

Save the Inbound Webhook configuration. A variable named `first_name` is then available as `{{pre_call.first_name}}`. In a supported field, type `{{` and select the variable.

| Area | Example | Use |
| - | - | - |
| **Initial greeting** | `Hallo {{pre_call.first_name}}, wie kann ich helfen?` | Greet the caller with relevant information immediately. |
| **AI instruction (user prompt)** | `Der Tarif des Kunden ist {{pre_call.plan}}.` | Give the agent context for the conversation; also available in the fullscreen editor. |
| **Tools → Forward calls → Phone number** | `{{pre_call.forward_to}}` | Use a phone number from your API as the forwarding destination. |
| **Post-processing** | `Kunden-ID: {{pre_call.customer_id}}` | Use the loaded value in email subjects and bodies, SMS, AI content instructions, and API URLs, header values, and bodies. |

### Initial greeting and AI instruction

For every incoming call, the HTTP request runs first. Placeholders are populated with the response values or configured defaults. These values are also available for forwarding and post-processing within the same call.

For more on the user prompt, see [AI instructions](/docs/en/ai-prompts).

### Dynamic forwarding destination

For example, create a variable named `forward_to` and map it to the phone-number field in your API response. Under **Tools → Forward calls**, enter the complete placeholder `{{pre_call.forward_to}}` in **Phone number**.

The resolved value must be a phone number in **international format with `+` and the country code, without spaces**, for example `+493012345678`. National formats such as `03012345678` and values such as `+49 30 12345678` are not supported. Do not combine the placeholder with an additional country code or other text.

### Post-processing with the same values

Use `{{pre_call.customer_id}}`, for example, to associate a [post-processing task](/docs/en/post-processing) with the correct customer. These values come from the Inbound Webhook before the conversation. Custom extractions such as `{{post_call.kunden_email}}` are produced only after the conversation, so they are unavailable in the greeting, user prompt, or forwarding destination.

## API response requirements

For the response to be processed, your API must:

* respond with an HTTP status from `200` through `299`,
* return a valid JSON object,
* provide the required values as text, numbers, or Boolean values.

Missing, empty, or unusable values follow the configured default-value and failure behavior.


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