Öffentliche API

Erstellen Sie öffentliche Talkturo-Anruf-Erlebnisse mit KI-Mitarbeiter-Demos, ausgehenden Anrufen, eingebetteten Formularen und browser-bereiten Anruftokens.

Endpunktübersicht

Die öffentliche API ermöglicht öffentliche Anruf-Erlebnisse mit KI-Mitarbeitern, Demo-Assistenten, ausgehenden Anrufen und eingebetteten Formularen.

Methode	Pfad	Zweck	Authentifizierung
`POST`	`/api/public/ai-employee/create`	KI-Mitarbeiter-Entwurf erstellen	API-Key
`POST`	`/api/public/ai-employee/upload`	Referenzdokument hochladen	API-Key
`POST`	`/api/public/ai-employee/call-token`	KI-Mitarbeiter-Anruftoken erstellen	API-Key
`GET`	`/api/public/ai-employee/use-cases`	KI-Mitarbeiter-Anwendungsfälle auflisten	Öffentlich
`GET`	`/api/public/demo-assistants`	Demo-Assistenten auflisten	Öffentlich
`POST`	`/api/public/test-call/token`	Demo-Anruftoken erstellen	Öffentlich
`POST`	`/api/public/test-call/outbound`	Ausgehenden Demo-Anruf starten	API-Key
`POST`	`/api/public/form-call/outbound`	Ausgehenden Formular-Anruf starten	Öffentlich

Authentifizierung

Geschützte Endpunkte erwarten einen API-Key im Authorization-Header. Öffentliche Endpunkte benötigen keinen API-Key, können aber zusätzliche Angaben im Request-Body verlangen, um einen Assistenten oder eine Demo zu bestimmen.

Authorization: Bearer tk_live_example_9xmk7q2r

Verwenden Sie browser-bereite Anruftokens für clientseitige Anruferlebnisse. Geben Sie Ihren API-Key nicht an Browser-Clients weiter.

KI-Mitarbeiter-Erstellung

Mit der KI-Mitarbeiter-Erstellung erstellen Sie einen Entwurf, laden ein Referenzdokument hoch und erzeugen anschließend ein Anruftoken für den Browser.

KI-Mitarbeiter-Entwurf erstellen

POST /api/public/ai-employee/create
Authorization: Bearer tk_live_example_9xmk7q2r
Content-Type: application/json

{
  "name": "Mia",
  "instructions": "Qualify inbound leads and schedule qualified appointments.",
  "language": "en"
}

Body-Parameter

Anzeigename des KI-Mitarbeiters.

instructionsstring

Anweisungen für das Verhalten und die Aufgaben des KI-Mitarbeiters.

Sprache, in der der KI-Mitarbeiter kommuniziert.

Antwort

{
  "id": "a1b2c3d4-e5f6-47a8-9012-345678901234",
  "name": "Mia",
  "status": "draft"
}

idstring

Eindeutige ID des KI-Mitarbeiters.

namestring

Anzeigename des KI-Mitarbeiters.

statusstring

Aktueller Status des KI-Mitarbeiter-Entwurfs.

Referenzdokument hochladen

POST /api/public/ai-employee/upload
Authorization: Bearer tk_live_example_9xmk7q2r
Content-Type: multipart/form-data

{
  "ai_employee_id": "a1b2c3d4-e5f6-47a8-9012-345678901234",
  "file": "company-handbook.pdf"
}

Body-Parameter

ai_employee_idstring

ID des KI-Mitarbeiters, dem das Referenzdokument zugeordnet wird.

Referenzdokument, das der KI-Mitarbeiter für seine Antworten verwenden soll.

KI-Mitarbeiter-Anruftoken erstellen

POST /api/public/ai-employee/call-token
Authorization: Bearer tk_live_example_9xmk7q2r
Content-Type: application/json

{
  "ai_employee_id": "a1b2c3d4-e5f6-47a8-9012-345678901234",
  "expires_in": 900
}

Body-Parameter

ai_employee_idstring

ID des KI-Mitarbeiters, für den das Anruftoken erstellt wird.

expires_ininteger

Gültigkeitsdauer des Tokens in Sekunden.

Antwort

{
  "token": "call_example_7f3k9m2q",
  "expires_at": "2025-01-15T10:15:00.000Z"
}

tokenstring

Browser-bereites Token für den Anruf.

expires_atstring

Zeitpunkt, an dem das Token abläuft.

Demo-Assistenten

Demo-Assistenten ermöglichen öffentliche Anruf-Erlebnisse, ohne einen eigenen KI-Mitarbeiter einzurichten.

KI-Mitarbeiter-Anwendungsfälle auflisten

GET /api/public/ai-employee/use-cases

Abfrageparameter

Filtert die Anwendungsfälle nach Sprache.

Antwort

{
  "use_cases": [
    {
      "id": "lead-qualification",
      "name": "Lead qualification",
      "description": "Qualify leads and schedule meetings."
    }
  ]
}

use_casesarray

Liste der verfügbaren KI-Mitarbeiter-Anwendungsfälle.

Demo-Assistenten auflisten

GET /api/public/demo-assistants

Abfrageparameter

Filtert Demo-Assistenten nach einem Anwendungsfall.

Filtert Demo-Assistenten nach Sprache.

Antwort

{
  "assistants": [
    {
      "id": "demo_sales_01",
      "name": "Sales qualification",
      "description": "Qualify a prospect and identify the next step.",
      "language": "en"
    }
  ]
}

assistantsarray

Liste der verfügbaren Demo-Assistenten.

assistants[].idstring

Eindeutige ID des Demo-Assistenten.

assistants[].namestring

Anzeigename des Demo-Assistenten.

assistants[].descriptionstring

Beschreibung des Demo-Assistenten.

assistants[].languagestring

Sprache des Demo-Assistenten.

Demo-Anrufe

Demo-Anruftoken erstellen

POST /api/public/test-call/token
Content-Type: application/json

{
  "assistant_id": "demo_sales_01",
  "expires_in": 900
}

Body-Parameter

assistant_idstring

ID des Demo-Assistenten, für den das Token erstellt wird.

expires_ininteger

Gültigkeitsdauer des Tokens in Sekunden.

Antwort

{
  "token": "call_example_7f3k9m2q",
  "assistant_id": "demo_sales_01",
  "expires_at": "2025-01-15T10:15:00.000Z"
}

tokenstring

Browser-bereites Token für den Demo-Anruf.

assistant_idstring

ID des verwendeten Demo-Assistenten.

expires_atstring

Zeitpunkt, an dem das Token abläuft.

Ausgehenden Demo-Anruf starten

POST /api/public/test-call/outbound
Authorization: Bearer tk_live_example_9xmk7q2r
Content-Type: application/json

{
  "assistant_id": "demo_sales_01",
  "phone_number": "+493012345678",
  "recipient_name": "Anna Weber"
}

Body-Parameter

assistant_idstring

ID des Demo-Assistenten, der den Anruf führt.

phone_numberstring

Telefonnummer des Empfängers im internationalen Format.

recipient_namestring

Name des Anrufempfängers.

Antwort

{
  "call_id": "call_a1b2c3d4",
  "status": "queued"
}

call_idstring

Eindeutige ID des ausgehenden Anrufs.

statusstring

Aktueller Status des Anrufs.

Eingebettete Formular-Anrufe

Mit eingebetteten Formular-Anrufen verbinden Sie ein öffentliches Formular mit einem ausgehenden Anruf.

Ausgehenden Formular-Anruf starten

POST /api/public/form-call/outbound
Content-Type: application/json

{
  "assistant_id": "demo_sales_01",
  "phone_number": "+493012345678",
  "form_data": {
    "name": "Anna Weber",
    "company": "Nordstern GmbH",
    "interest": "Produktdemo"
  }
}

Body-Parameter

assistant_idstring

ID des Assistenten, der den Formular-Anruf führt.

phone_numberstring

Telefonnummer für den ausgehenden Anruf im internationalen Format.

form_dataobject

Formulardaten, die dem Assistenten als Kontext für den Anruf zur Verfügung stehen.

form_data.namestring

Name der Person, die das Formular ausgefüllt hat.

form_data.companystring

Unternehmen der Person, die das Formular ausgefüllt hat.

form_data.intereststring

Anliegen oder Produktinteresse der Person.

Antwort

{
  "call_id": "call_a1b2c3d4",
  "status": "queued"
}

call_idstring

Eindeutige ID des ausgehenden Formular-Anrufs.

statusstring

Aktueller Status des Anrufs.

Validieren Sie Telefonnummern und Formulardaten serverseitig, bevor Sie einen ausgehenden Anruf starten. Stellen Sie sicher, dass Sie die erforderliche Einwilligung für den Anruf besitzen.

Fehlerantworten

Die API verwendet JSON-Fehlerantworten. Der HTTP-Statuscode zeigt die Fehlerklasse an.

{
  "error": "invalid_request",
  "message": "The request body is invalid."
}

errorstring

Maschinenlesbarer Fehlercode.

messagestring

Beschreibung des Fehlers.

Statuscode	Bedeutung
`400`	Der Request enthält ungültige oder fehlende Parameter.
`401`	Die Authentifizierung fehlt oder ist ungültig.
`403`	Der authentifizierte Aufrufer ist für die angeforderte Ressource nicht berechtigt.
`404`	Die angeforderte Ressource wurde nicht gefunden.
`409`	Der Request steht im Konflikt mit dem aktuellen Ressourcenstatus.
`429`	Das Rate Limit wurde überschritten.
`500`	Ein unerwarteter Fehler ist aufgetreten.

Was this page helpful?