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

# API-Anfragen

> Konfiguration externer API-Integrationen für Voice Agents.

Sie können API-Anfrage-Definitionen im **API-Anfragen**-Tab des Voice Wizards erstellen. Klicken Sie auf **"API-Anfrage hinzufügen"** und Sie sehen das folgende Eingabeformular mit den unten erklärten Feldern.

<img src="https://mintcdn.com/pscgmbh/HIBIlKxDFiD3efK1/images/create-api-request-modal.png?fit=max&auto=format&n=HIBIlKxDFiD3efK1&q=85&s=e5b54f6bd74c20eb10a6c94fa8d59b6a" alt="API Request Configuration Form" width="1522" height="1249" data-path="images/create-api-request-modal.png" />

## Formularfelder erklärt

### Name der API-Anfrage

Ein beschreibender Name für Ihre API-Anfrage (z. B. "Produktbestellung erstellen")

### URL

Die API-Endpunkt-URL. Sie können Platzhalter wie `{{userId}}` verwenden, die durch Werte aus Ihren **dynamischen** Funktionsparametern ersetzt werden.

* Beispiel: `https://api.shop.com/orders/{{userId}}`

### HTTP-Methode

Wählen Sie die HTTP-Methode für Ihre Anfrage (GET, POST, PUT, DELETE, etc.)

### API Key

Ihr Authentifizierungs-Token. Dieser ersetzt automatisch alle `{{api_key}}`-Platzhalter in Ihrer URL oder in den Headern.

### Headers

HTTP-Header für Ihre Anfrage im JSON-Format:

```json theme={null}
{
  "Authorization": "Bearer {{api_key}}",
  "Content-Type": "application/json"
}
```

* `{{api_key}}` wird durch Ihren API Key ersetzt

### Funktionsdefinition (Dynamische Parameter)

Definieren Sie die Parameter, die Benutzer beim Aufruf Ihrer Funktion übergeben können:

```json theme={null}
{
  "type": "function",
  "name": "place_order",
  "description": "Bestellt ein Produkt für einen Kunden",
  "parameters": {
    "type": "object",
    "properties": {
      "userId": {
        "type": "string",
        "description": "Kunden-Benutzer-ID"
      },
      "orderDetails": {
        "type": "object",
        "properties": {
          "product": {"type": "string"},
          "quantity": {"type": "number"}
        }
      }
    }
  }
}
```

Diese Parameter werden:

* Passende Platzhalter in URL und Headern ersetzen
* **Alle dynamischen Parameter, die nicht mit Platzhaltern übereinstimmen, werden in den Request Body eingefügt**
* **Funktioniert mit verschachtelten Objekten** - z. B. wird das `orderDetails`-Objekt im Body beibehalten

### Feste Parameter

Statische Werte, die immer in jeder Anfrage enthalten sind:

```json theme={null}
{
  "storeId": "STORE_123",
  "paymentMethod": "credit_card",
  "currency": "USD"
}
```

Diese werden:

* **Immer unverändert in den Request Body eingefügt**
* Sie ersetzen KEINE Platzhalter in Headern oder URL

### Vorher sagen

Eine optionale Nachricht, die der KI-Assistent dem Benutzer mitteilt, bevor die API-Anfrage ausgeführt wird. Zum Beispiel: "Ich erstelle jetzt Ihre Bestellung..." oder "Einen Moment, ich rufe die Produktinformationen ab..."

## Beispiel: GET-Anfrage ohne dynamische Parameter

Manche API-Aufrufe benötigen keine Parameter von der KI - zum Beispiel "Alle Produkte abrufen". In diesem Fall ist trotzdem eine Funktionsdefinition erforderlich, damit die KI die API-Anfrage auslöst.

<img src="https://mintcdn.com/pscgmbh/HIBIlKxDFiD3efK1/images/create-api-request-modal-empty-request.png?fit=max&auto=format&n=HIBIlKxDFiD3efK1&q=85&s=13252c6e32ca5a37275711040e664a30" alt="API Request Configuration for GET without parameters" width="1522" height="1325" data-path="images/create-api-request-modal-empty-request.png" />

### Konfiguration für "Get all products"

* **Name der API-Anfrage**: "Get all products"
* **URL**: `https://example.proxy.beeceptor.com/products` (Beispiel-Testendpunkt)
* **HTTP-Methode**: GET
* **API Key**: (leer oder Ihr API-Schlüssel)
* **Headers**: Standard-GET-Headers

### Funktionsdefinition ohne Parameter

Klicken Sie auf **"Keine dynamischen Parameter"** um eine Vorlage zu erhalten:

```json theme={null}
{
  "type": "function",
  "name": "listProducts",
  "description": "Get all available products from the catalog",
  "parameters": {
    "type": "object",
    "properties": {}
  }
}
```

**Wichtig:**

* Ein aussagekräftiger **Funktionsname** und eine **Beschreibung** sind entscheidend, weil die KI verstehen muss, wann die Funktion aufgerufen werden soll
* Fügen Sie explizite Anweisungen im **Benutzer-Prompt** hinzu, falls die KI Schwierigkeiten hat
* Die leeren `properties: {}` sind erforderlich für eine gültige Funktionsdefinition

### Resultierende HTTP-Anfrage

Basierend auf der obigen Konfiguration wird folgende HTTP-Anfrage erstellt:

```
GET https://example.proxy.beeceptor.com/products
Content-Type: application/json
```

**Erklärung:**

* **URL**: Direkte URL ohne Platzhalter-Ersetzungen
* **Headers**: GET-Headers mit Bearer API Token
* **Parameter**: Keine dynamischen Parameter erforderlich

## Wie die endgültige Anfrage erstellt wird

1. **URL**: Platzhalter werden durch dynamische Funktionsparameter ersetzt
2. **Headers**: `{{api_key}}` wird durch den API Key ersetzt, andere Platzhalter durch dynamische Parameterwerte
3. **Body**: Kombination aus Festen Parametern + dynamischen Parametern, die nicht mit Platzhaltern übereinstimmen

### Beispiel der endgültigen HTTP-Anfrage

Basierend auf den obigen Parametern wird folgende HTTP-Anfrage erstellt:

```
POST https://api.shop.com/orders/user123
Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json

{
  "storeId": "STORE_123",
  "paymentMethod": "credit_card",
  "currency": "USD",
  "orderDetails": {
    "product": "Wireless Headphones",
    "quantity": 2
  }
}
```

**Erklärung:**

* **URL**: `{{userId}}` wurde durch "user123" ersetzt
* **Headers**: `{{api_key}}` wurde durch Ihren tatsächlichen API Key ersetzt
* **Body**: Enthält sowohl feste Parameter (storeId, paymentMethod, currency) als auch dynamische Parameter (orderDetails)