API-Keys (Outbound-Anrufe)

Zuletzt aktualisiert: 7.2.2026

Du kannst über unsere API Outbound-Anrufe auslösen und den Health-State unserer Services abfragen. Hierfür kannst du in deinem Dashboard API-Keys anlegen.

Schritt 1

API-Key erstellen

Erstelle einen neuen API-Key in deinem Dashboard.

Benenne deinen API-Key, um ihn später einfacher finden und zuordnen zu können.

Schritt 2

API-Key kopieren

Der API-Schlüssel wird nur einmal angezeigt. Speichere ihn sicher. Er kann nicht erneut angezeigt werden.

Kopiere den API-Key in die Zwischenablage und speichere ihn.

Übersicht

API-Key

Der API-Key wird in der Liste angezeigt. Du kannst ihn hier vorübergehend widerrufen oder löschen. Du siehst hier außerdem grundlegende Informationen zum API-Key wie Präfix, Status und Ersteller.

API-Key nutzen

Bearer Token

Dein API-Key ist ein Bearer Token. Dieser muss bei jeder API-Anfrage im Authorization-Header mitgeschickt werden. Der Header muss dabei mit dem Wort "Bearer" und einem Leerzeichen vor dem API-Key beginnen. Danach folgt dein API-Key.

http

Authorization: Bearer {API-Key}

API-Anfrage

Health Check

Du kannst den Health-State unserer Services abfragen. Der API-Key muss im Authorization-Header mitgeschickt werden.

GET https://api.smao.ai/api/v1/health

Antwort:

json

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2025-10-13T10:00:00.000Z"
}

API-Anfrage

Outbound-Anruf auslösen

Du kannst einen Outbound-Anruf auslösen. Der API-Key muss im Authorization-Header mitgeschickt werden.

POST https://api.smao.ai/api/v1/outbound/call

Body:

json

{
  "assistantPhoneNumber": "+4915123456789",
  "targetPhoneNumber": "+491771234567",
  "details": "Customer requested callback regarding order #12345. They have questions about delivery."
}

Antwort:

json

{
  "status": "success",
  "data": {
    "callId": "507f1f77bcf86cd799439012",
    "assistantPhoneNumber": "+4915123456789",
    "targetPhoneNumber": "+491771234567",
    "timestamp": "2025-10-13T10:00:00.000Z"
  }
}

Schritt 1

Code-Beispiele

Node.js

javascript

const axios = require("axios");

const API_KEY = "your_api_key_here";
const API_URL = "https://api.localhost";

async function triggerOutboundCall(assistantPhone, targetPhone, details = "") {
    try {
        const response = await axios.post(
            `${API_URL}/api/v1/outbound/call`,
            {
                assistantPhoneNumber: assistantPhone,
                targetPhoneNumber: targetPhone,
                details: details, // Optional: additional context for the voice agent (max 1000 words)
            },
            {
                headers: {
                    Authorization: `Bearer ${API_KEY}`,
                    "Content-Type": "application/json",
                },
            }
        );
        console.log("Call initiated:", response.data);
        return response.data;
    } catch (error) {
        console.error("Error:", error.response?.data || error.message);
        throw error;
    }
}

// Usage
triggerOutboundCall(
    "+4915123456789",
    "+491771234567",
    "Customer requested callback regarding order #12345."
);

Python

python

import requests

API_KEY = 'your_api_key_here'
API_URL = 'https://api.localhost'

def trigger_outbound_call(assistant_phone, target_phone, details=""):
    response = requests.post(
        f'{API_URL}/api/v1/outbound/call',
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json'
        },
        json={
            'assistantPhoneNumber': assistant_phone,
            'targetPhoneNumber': target_phone,
            'details': details  # Optional: additional context for the voice agent (max 1000 words)
        }
    )
    response.raise_for_status()
    return response.json()

# Usage
result = trigger_outbound_call(
    '+4915123456789',
    '+491771234567',
    'Customer requested callback regarding order #12345.'
)
print('Call initiated:', result)

cURL

bash

curl -X POST https://api.localhost/api/v1/outbound/call \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantPhoneNumber": "+4915123456789",
    "targetPhoneNumber": "+491771234567",
    "details": "Customer requested callback regarding order #12345."
  }'

No-Code-Tools-Integration

Hier erfährst du, wie du die smao API mit No-Code-Tools wie Make, n8n oder Zapier verwenden kannst - ganz ohne Programmierkenntnisse.

Bearer Token richtig verwenden: Dein API-Schlüssel muss IMMER mit dem Wort „Bearer“ (gefolgt von einem Leerzeichen) beginnen. Das Wort „Bearer“ ist ein fester Bestandteil und muss mitgeschrieben werden!

Richtig: Bearer dein_api_schluessel_hier

Falsch: dein_api_schluessel_hier

Make (ehemals Integromat)

Mit Make kannst du Workflows erstellen, die automatisch Anrufe mit deinem Voice AI Agent tätigen.

Schritt 1

HTTP-Modul hinzufügen

Suche in deinem Make-Szenario nach „HTTP“ und wähle das Modul HTTP > Make a request aus.

Schritt 2

URL und Methode konfigurieren

Trage folgende Informationen ein:

URL: https://api.localhost/api/v1/outbound/callMethod: POST

Schritt 3

Authorization-Header hinzufügen

Klicke auf „Show advanced settings“. Scrolle zu „Headers“ und füge einen neuen Header hinzu. Das Wort „Bearer“ muss mit dabei sein!

Name: Authorization
Value: Bearer your_api_key_here

Schritt 4

Request Body konfigurieren

Wähle Body type: Raw und Content type: JSON (application/json). Füge folgenden JSON-Body ein:

json

{
  "assistantPhoneNumber": "+4915123456789",
  "targetPhoneNumber": "+491771234567",
  "details": "Customer requested callback regarding order #12345."
}

n8n

n8n ist ein Open-Source-Workflow-Automatisierungstool. So integrierst du die smao API:

Schritt 1

HTTP Request Node hinzufügen

Suche in der Node-Liste nach „HTTP Request“ und füge diesen Node zu deinem Workflow hinzu.

Schritt 2

Request konfigurieren

Stelle im HTTP Request Node ein: Method: POST, URL: https://api.localhost/api/v1/outbound/call

Schritt 3

Authentication hinzufügen

Unter „Authentication“ wähle Generic Credential Type → Header Auth. Konfiguriere: Name Authorization, Value Bearer your_api_key_here („Bearer “ mit Leerzeichen zuerst!).

Schritt 4

Body Data hinzufügen

Unter „Body“ wähle Body Content Type: JSON und gib den folgenden Body ein:

json

{
  "assistantPhoneNumber": "+4915123456789",
  "targetPhoneNumber": "+491771234567",
  "details": "Customer requested callback regarding order #12345."
}

Zapier

Zapier verbindet smao mit über 7.000 anderen Apps. So richtest du es ein:

Schritt 1

Webhooks by Zapier hinzufügen

Erstelle einen neuen Zap. Wähle als Action-App Webhooks by Zapier und als Action Event POST.

Schritt 2

URL konfigurieren

Im Setup des Webhooks: Payload Type: POST, URL: https://api.localhost/api/v1/outbound/call

Schritt 3

Headers hinzufügen

In der Sektion „Headers“ füge einen Header hinzu: Key Authorization, Value Bearer your_api_key_here. Das Wort „Bearer“ ist Pflicht!

Schritt 4

Data konfigurieren

In der Sektion „Data“ wähle „Form“ oder „JSON“ und füge folgenden Payload ein:

json

{
  "assistantPhoneNumber": "+4915123456789",
  "targetPhoneNumber": "+491771234567",
  "details": "Customer requested callback regarding order #12345."
}

Fehlercodes

Mögliche Fehlercodes der Outbound-Call-API:

Fehlercode	HTTP-Status	Beschreibung
MISSING_API_KEY	401	Authorization-Header fehlt oder ungültig
INVALID_API_KEY	401	API-Schlüssel ungültig oder widerrufen
ASSISTANT_NOT_FOUND	400	Assistent-Telefonnummer nicht gefunden
INVALID_PHONE_FORMAT	400	Telefonnummer-Format ungültig
INVALID_TARGET_NUMBER	400	Nur deutsche Nummern (+49) werden unterstützt
RATE_LIMIT_EXCEEDED	429	Zu viele Anfragen (siehe Retry-After-Header)
CALL_FAILED	500	Anruf konnte nicht getätigt werden
VALIDATION_ERROR	400	Anfrage-Validierung fehlgeschlagen
INTERNAL_ERROR	500	Interner Serverfehler

Vorheriger ArtikelIntegrationen