> ## Documentation Index
> Fetch the complete documentation index at: https://aipro.placetel.de/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Inbound Webhook
> Load data from an API before an inbound call and use it in the initial greeting.
## Overview
The **Inbound Webhook** sends an HTTP request before the voice agent accepts an incoming call. Values from the JSON response become variables that can personalize the initial greeting.
Typical examples include the customer's name, their plan, or information from your CRM. This allows the voice agent to greet the caller with relevant information immediately.
The Inbound Webhook only runs for incoming calls. The HTTP request must finish before the voice agent accepts the call.
## Open the Inbound Webhook
Open the voice agent you want and switch to the **Advanced** tab.
Open the **Inbound Webhook** card and click **Configure**.
Once you have saved a valid configuration, use the toggle on the card to enable or pause the Inbound Webhook.
## 1. Configure the connection
In the first step, choose when and how the HTTP request is sent.
### 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. |
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}}` | Number from which the call was forwarded, if the telephony provider supplies this information. |
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.
## 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.
* **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.
### 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.
### Search the response
For large responses, search by field name, response path, or value. Then select the required scalar field using its checkbox.
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` |
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.
| Field | Meaning |
| ----------------- | -------------------------------------------------------------------------------------- |
| **Variable** | The name you later use as a placeholder, for example `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 `{{first_name}}`.
## Use a variable in the initial greeting
Save the Inbound Webhook configuration, then open the voice agent's **Initial greeting**. Type `{{` and select a configured variable.
Example: `Hi, {{first_name}}`
For every incoming call, the HTTP request runs first. The voice agent then replaces the placeholder with the response value or configured default and starts with the completed greeting.
## 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.