Assistenten

curl -X POST "https://api.talkturo.com/api/assistants" \
  -H "Authorization: Bearer tk_test_example_9xmk7q2r" \
  -H "Content-Type: application/json" \
  -d '{
    "accountSlug": "acme-sales",
    "name": "Inbound Qualification Assistant",
    "templateId": "tmpl_voice_inbound"
  }'

const response = await fetch("https://api.talkturo.com/api/assistants", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tk_test_example_9xmk7q2r",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    accountSlug: "acme-sales",
    name: "Inbound Qualification Assistant",
    templateId: "tmpl_voice_inbound"
  })
});

const data = await response.json();
console.log(data);

{
  "success": true,
  "assistant": {
    "id": "7d2d1b8f-1f2e-4c24-8d31-6bf0c3d54b4e",
    "account_slug": "acme-sales",
    "name": "Inbound Qualification Assistant",
    "type": "tmpl_voice_inbound",
    "created_at": "2025-01-14T10:22:31.000Z",
    "updated_at": "2025-01-14T10:22:31.000Z"
  }
}

curl -X PATCH "https://api.talkturo.com/api/assistants/7d2d1b8f-1f2e-4c24-8d31-6bf0c3d54b4e" \
  -H "Authorization: Bearer tk_test_example_9xmk7q2r" \
  -H "Content-Type: application/json" \
  -d '{
    "accountSlug": "acme-sales",
    "name": "Inbound Qualification Assistant v2",
    "voice": "alloy",
    "model": "gpt-4o-realtime",
    "transcriptor_options": {
      "provider": "deepgram",
      "model": "nova-2"
    }
  }'

const response = await fetch("https://api.talkturo.com/api/assistants/7d2d1b8f-1f2e-4c24-8d31-6bf0c3d54b4e", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer tk_test_example_9xmk7q2r",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    accountSlug: "acme-sales",
    name: "Inbound Qualification Assistant v2",
    voice: "alloy",
    model: "gpt-4o-realtime",
    transcriptor_options: {
      provider: "deepgram",
      model: "nova-2"
    }
  })
});

const data = await response.json();
console.log(data);

{
  "success": true,
  "assistant": {
    "id": "7d2d1b8f-1f2e-4c24-8d31-6bf0c3d54b4e",
    "account_slug": "acme-sales",
    "name": "Inbound Qualification Assistant v2",
    "type": "tmpl_voice_inbound",
    "created_at": "2025-01-14T10:22:31.000Z",
    "updated_at": "2025-01-14T11:04:09.000Z"
  }
}

curl -X DELETE "https://api.talkturo.com/api/assistants/7d2d1b8f-1f2e-4c24-8d31-6bf0c3d54b4e" \
  -H "Authorization: Bearer tk_test_example_9xmk7q2r"

const response = await fetch("https://api.talkturo.com/api/assistants/7d2d1b8f-1f2e-4c24-8d31-6bf0c3d54b4e", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer tk_test_example_9xmk7q2r"
  }
});

const data = await response.json();
console.log(data);

{
  "success": true,
  "message": "Assistant deleted successfully"
}

curl -X POST "https://api.talkturo.com/api/assistants/7d2d1b8f-1f2e-4c24-8d31-6bf0c3d54b4e/clone" \
  -H "Authorization: Bearer tk_test_example_9xmk7q2r"

const response = await fetch("https://api.talkturo.com/api/assistants/7d2d1b8f-1f2e-4c24-8d31-6bf0c3d54b4e/clone", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tk_test_example_9xmk7q2r"
  }
});

const data = await response.json();
console.log(data);

{
  "success": true,
  "assistant": {
    "id": "2f850d8a-a9d5-4906-af87-8c9838ab7d5d",
    "name": "Inbound Qualification Assistant (Copy)",
    "created_at": "2025-01-14T11:10:42.000Z",
    "updated_at": "2025-01-14T11:10:42.000Z"
  }
}

curl -X GET "https://api.talkturo.com/api/assistants/7d2d1b8f-1f2e-4c24-8d31-6bf0c3d54b4e/usage-stats?accountId=9a7c2d41-5a13-4d5f-b8d1-2e7f1c4a8b90" \
  -H "Authorization: Bearer tk_test_example_9xmk7q2r"

const response = await fetch("https://api.talkturo.com/api/assistants/7d2d1b8f-1f2e-4c24-8d31-6bf0c3d54b4e/usage-stats?accountId=9a7c2d41-5a13-4d5f-b8d1-2e7f1c4a8b90", {
  method: "GET",
  headers: {
    "Authorization": "Bearer tk_test_example_9xmk7q2r"
  }
});

const data = await response.json();
console.log(data);

{
  "totalCalls": 148,
  "totalMinutes": 912.0,
  "avgDurationMinutes": 6.2,
  "completedCallsWithDuration": 145,
  "successRatePercent": 87.5,
  "successEvaluatedCount": 130,
  "timeline": {
    "today": 5,
    "last7Days": 45,
    "last30Days": 148,
    "last365Days": 148
  },
  "dailySeries": [
    { "date": "2025-02-18", "count": 6 },
    { "date": "2025-02-17", "count": 4 }
  ]
}

{
  "success": true,
  "assistant": {
    "id": "7d2d1b8f-1f2e-4c24-8d31-6bf0c3d54b4e",
    "account_slug": "acme-sales",
    "name": "Inbound Qualification Assistant",
    "type": "tmpl_voice_inbound",
    "created_at": "2025-01-14T10:22:31.000Z",
    "updated_at": "2025-01-14T10:22:31.000Z"
  }
}

{
  "success": true,
  "message": "Assistant deleted successfully"
}

Assistenten verwalten

Erstellen Sie Assistenten, aktualisieren Sie ihre Konfiguration, klonen Sie bestehende Setups, löschen Sie nicht mehr benötigte Assistenten und rufen Sie Nutzungsdaten für Reporting oder operative Prüfungen ab.

Alle Assistant-Endpunkte unterstützen Dual-Authentifizierung über withApiAuth. Authentifizieren Sie sich entweder mit einem Talkturo-API-Schlüssel oder mit einem authentifizierten Session-Cookie.

Basispfad: /api/assistants

Endpunktübersicht

Einen Assistenten erstellen

Erstellen Sie einen Assistenten mit einem Kontoslug und einem Namen. Optional können Sie auch eine Vorlage angeben, um den Assistententyp beim Anlegen zu setzen.

Request-Body

Antwortfelder

Einen Assistenten aktualisieren

Aktualisieren Sie einen vorhandenen Assistenten, indem Sie seine Kennung im Pfad und die zu ändernden Felder im Request-Body übergeben. Der Endpunkt akzeptiert accountSlug optional und validiert transcriptor_options gegen den gewählten Provider und das Modell, bevor Änderungen gespeichert werden.

Pfadparameter

Request-Body

Antwortfelder

Einen Assistenten löschen

Löschen Sie einen Assistenten dauerhaft über seine Kennung. Der Endpunkt prüft, ob der Assistent dem authentifizierten Konto gehört, bevor der Löschvorgang ausgeführt wird.

Pfadparameter

Antwortfelder

Einen Assistenten klonen

Klonen Sie einen vorhandenen Assistenten, um schnell eine neue Konfiguration auf Basis eines bestehenden Setups zu erstellen.

Pfadparameter

Request-Body

Antwortfelder

Nutzungsstatistiken abrufen

Rufen Sie aggregierte Nutzungsdaten für einen einzelnen Assistenten ab, um Aufrufe, Gesprächsminuten und den Zeitpunkt des letzten Anrufs zu prüfen.

Pfadparameter

Abfrageparameter

Antwortfelder

Werkzeugkonfigurationen

Werkzeugkonfigurationen ermöglichen es Ihnen, Drittanbieter-Tools wie Cal.com-Scheduling, Zapier oder benutzerdefinierte Webhooks an einen Assistenten anzuhängen. Alle Endpunkte erfordern Session-Authentifizierung.

Konfigurationen für einen Werkzeugtyp abrufen

Rufen Sie Konfigurationen für einen einzelnen Werkzeugtyp ab. Verwenden Sie configId, wenn Sie eine bestimmte Konfiguration adressieren möchten, oder all=true, um alle Konfigurationen dieses Typs zurückzugeben.

Pfadparameter

Abfrageparameter

Werkzeugkonfiguration erstellen oder aktualisieren

Erstellen Sie eine neue Werkzeugkonfiguration oder aktualisieren Sie eine vorhandene Konfiguration für den angegebenen Werkzeugtyp.

Abfrageparameter

Request-Body

Werkzeugkonfigurationen löschen

Löschen Sie entweder eine bestimmte Konfiguration oder alle Konfigurationen eines Werkzeugtyps.

Abfrageparameter

Kostenschätzung

Gibt eine geschätzte Kosten pro Minute in Credits zurück, basierend auf den Provider-Einstellungen des Assistenten und dem aktiven Kostenkatalog.

Endpunkt

GET /api/assistants/{assistantId}/billing/estimate

Pfadparameter

Abfrageparameter

Antwortfelder

Wissensdatenbank-Anhänge

Verwalten Sie Wissensdatenbank-Dateien, die an einen Assistenten angehängt sind. Hängen Sie vorhandene Dateien aus der Kontobibliothek an. Diese Endpunkte laden keine neuen Dateien hoch. Siehe Wissensdatenbank für Datei-Upload und -Verwaltung.

Angehängte Wissensdatenbank-Dateien auflisten

Ruft alle Wissensdatenbank-Dateien ab, die an den Assistenten angehängt sind. Ergebnisse sind nach Anhänge-Erstellungszeit sortiert, neueste zuerst.

Endpunkt

GET /api/assistants/{assistantId}/knowledge-base

Pfadparameter

Antwortfelder

Wissensdatenbank-Datei anhängen

Hängen Sie eine vorhandene Wissensdatenbank-Datei aus der Kontobibliothek an den Assistenten an. Die Datei muss bereits existieren und zum selben Konto wie der Assistenten gehören. Dieser Vorgang ist idempotent, das Anhängen einer bereits angehängten Datei gibt Erfolg zurück, ohne ein Duplikat zu erstellen.

Endpunkt

POST /api/assistants/{assistantId}/knowledge-base

Pfadparameter

Body-Parameter

Antwortfelder

Wissensdatenbank-Datei trennen

Entfernen Sie eine Wissensdatenbank-Datei von einem Assistenten. Dies entfernt nur den Anhang. Die zugrunde liegende Datei bleibt in der Kontobibliothek. Das Trennen eines nicht vorhandenen Anhangs gibt trotzdem Erfolg zurück.

Endpunkt

DELETE /api/assistants/{assistantId}/knowledge-base/{fileId}

Pfadparameter

Antwortfelder

Telefonieverwaltung

Verwalten Sie ein- und ausgehende Telefonie für einen Assistenten. Diese Endpunkte stellen LiveKit-Trunks bereit, konfigurieren diese, weisen Telefonnummern zu und starten Testanrufe.

Die meisten Telefonieverwaltungs-Endpunkte erfordern Session-Authentifizierung und unterstützen keine API-Schlüssel-Authentifizierung. Nur der Endpunkt zum Auflisten von Telefonnummern unterstützt API-Schlüssel.

Zugewiesene Telefonnummern auflisten

Ruft aktive, nicht gelöschte Telefonnummern ab, die dem Assistenten zugewiesen sind. Ergebnisse umfassen Nummern, die nicht zugewiesen oder diesem Assistenten zugewiesen sind, sortiert nach Telefonnummer aufsteigend.

Endpunkt

GET /api/assistants/{assistantId}/telephony/phone-numbers

Pfadparameter

Abfrageparameter

Antwortfelder

Telefonnummern zuweisen (PATCH)

Weisen Sie dem Assistenten Telefonnummern zu. Alle vorhandenen Zuweisungen werden zuerst entfernt, dann werden die angegebenen IDs zugewiesen. LiveKit-Routing wird für betroffene Assistenten neu synchronisiert.

Endpunkt

PATCH /api/assistants/{assistantId}/telephony/phone-numbers

Body-Parameter

Antwortfelder

Eingehende Anrufe aktivieren oder deaktivieren

Schalten Sie eingehende Anrufe für den Assistenten um. Das Aktivieren erfordert mindestens eine aktive, nicht gelöschte Telefonnummer, die dem Assistenten zugewiesen ist. Talkturo stellt den LiveKit-Eingehend-Trunk und die Dispatch-Regel beim Aktivieren bereit oder aktualisiert sie und entfernt sie beim Deaktivieren.

Endpunkt

POST /api/assistants/{assistantId}/telephony/inbound

Body-Parameter

Antwortfelder

Ausgehende Anrufe aktivieren oder deaktivieren

Schalten Sie ausgehende Anrufe für den Assistenten um. Das Aktivieren erfordert mindestens eine aktive zugewiesene Telefonnummer. Talkturo stellt den LiveKit-Ausgehend-Trunk beim Aktivieren bereit oder aktualisiert ihn und entfernt ihn beim Deaktivieren.

Endpunkt

POST /api/assistants/{assistantId}/telephony/outbound

Body-Parameter

Antwortfelder

Telefonieeinstellungen aktualisieren

Konfigurieren Sie Telefonnummern-Zuweisungen, Anrufbeantworter, Compliance und Zielland in einer einzigen Anfrage. Dieser Endpunkt verarbeitet LiveKit-Bereitstellung, Anrufbeantworter-Erkennung und Compliance-Zustimmungs-Workflows.

Endpunkt

POST /api/assistants/{assistantId}/telephony/settings

Body-Parameter

Antwortfelder

Telefonieeinstellungen werden atomar angewendet. Wenn die LiveKit-Bereitstellung fehlschlägt, setzt die Route alle aktivierten Flags und Trunk-IDs auf ihren vorherigen Status zurück.

Testanruf starten

Starten Sie einen Testanruf mit der Telefoniekonfiguration des Assistenten. Erfordert ausreichende Kontoguthaben und aktivierte ausgehende Anrufe.

Endpunkt

POST /api/assistants/{assistantId}/telephony/test-call

Body-Parameter

Antwortfelder

Testanrufe erfordern ausreichende Kontoguthaben. Wenn das Guthaben zu niedrig ist, gibt die API HTTP 402 mit dem aktuellen Guthaben und dem mindestens erforderlichen Guthaben zurück.

Zuweisbare Telefonnummern auflisten

Ruft Telefonnummern ab, die dem Assistenten zugewiesen werden können, einschließlich nicht zugewiesener Nummern und bereits zugewiesener Nummern.

Endpunkt

GET /api/assistants/{assistantId}/telephony/assign-phone-numbers

Pfadparameter

Abfrageparameter

Antwortfelder

Compliance-Vorlagen auflisten

Ruft Compliance-Vorlagen ab, die für die Telefoniekonfiguration des Assistenten verfügbar sind.

Endpunkt

GET /api/assistants/{assistantId}/telephony/compliance-templates

Pfadparameter

Antwortfelder

Test-Link erstellen oder aktualisieren

Generieren oder aktualisieren Sie einen Test-Link für einen Assistenten. Der Test-Link bietet eine URL, die einen browserbasierten Testanruf mit dem Assistenten öffnet.

Endpunkt

POST /api/assistants/{assistantId}/test-link

Pfadparameter

Antwortfelder

CRM-Gruppenzuweisung

Weisen Sie einem Assistenten eine CRM-Gruppe zu. Die CRM-Gruppe bestimmt, welche Kontakte der Assistent während Anrufen aufrufen kann. Die Gruppe muss zum selben Konto wie der Assistent gehören.

Endpunkt

POST /api/assistants/{assistantId}/crm-group

Pfadparameter

Body-Parameter

Antwortfelder

Webhook-Test

Senden Sie ein Test-Webhook-Event, um zu überprüfen, ob die Webhook-Konfiguration des Assistenten funktioniert. Der Endpunkt generiert ein synthetisches call.ended-Event und reiht es zur Zustellung ein. Er führt keinen echten Anruf durch und ruft den Webhook nicht synchron auf.

Der Assistent muss Webhooks aktiviert haben mit sowohl URL als auch Secret konfiguriert, bevor getestet wird.

Endpunkt

POST /api/assistants/{assistantId}/webhooks/test

Pfadparameter

Antwortfelder

Prompt-Versionsverlauf

Verfolgen und stellen Sie frühere Versionen des System-Prompts eines Assistenten wieder her. Jedes Mal, wenn sich der Prompt ändert, speichert Talkturo einen versionierten Snapshot. Verwenden Sie diese Endpunkte, um den Verlauf zu durchsuchen, eine neue Version zu speichern, einen alten Prompt wiederherzustellen oder eine nicht mehr benötigte Version zu löschen.

Alle Prompt-Versions-Endpunkte verwenden withApiAuth und unterstützen sowohl API-Schlüssel- als auch Session-Cookie-Authentifizierung. API-Schlüssel-Anfragen verwenden das dem Schlüssel zugeordnete Konto. Session-Token-Anfragen erfordern accountSlug im Query-String. Cookie-Session-Anfragen erfordern teamId oder accountSlug im Query-String oder Request-Body.

Prompt-Versionen auflisten

Ruft eine paginierte Liste von Prompt-Versionen ab, neueste zuerst.

Endpunkt

GET /api/assistants/{assistantId}/prompt-versions

Pfadparameter

Abfrageparameter

Antwortfelder

Prompt-Version speichern

Speichert den aktuellen System-Prompt des Assistenten als neue Version. Wenn sich der Prompt seit der letzten Version nicht geändert hat, gibt der Endpunkt unchanged: true zurück und erstellt keine neue Version.

Endpunkt

POST /api/assistants/{assistantId}/prompt-versions

Body-Parameter

Antwortfelder

Prompt-Version löschen

Löschen Sie eine Prompt-Version anhand ihrer ID. Die aktuell aktive Version kann nicht gelöscht werden.

Endpunkt

DELETE /api/assistants/{assistantId}/prompt-versions/{versionId}

Pfadparameter

Antwortfelder

Prompt-Version wiederherstellen

Stellen Sie eine frühere Prompt-Version wieder her, indem Sie deren system_prompt auf den Assistenten kopieren. Dies aktualisiert den aktuellen Prompt und den Versionszeiger des Assistenten, erstellt aber keine neue Version.

Endpunkt

POST /api/assistants/{assistantId}/prompt-versions/{versionId}/restore

Pfadparameter

Antwortfelder

Workflow-Werkzeug-Anhang

Hängen Sie einen veröffentlichten TurboFlow-Workflow als aufrufbares Werkzeug an einen Assistenten an. Der Assistent kann den Workflow während Anrufen aufrufen. Name, Beschreibung und Parameter des Workflows werden zur Laufzeit aus der veröffentlichten Flow-Version ermittelt.

Endpunkt

POST /api/assistants/{assistantId}/tools/workflow

Pfadparameter

Body-Parameter

Antwortfelder

Das doppelte Anhängen desselben Workflows an denselben Assistenten gibt HTTP 409 mit dem Fehler workflow_already_attached zurück.

Workflow-Werkzeug trennen

Entfernen Sie ein Workflow-Werkzeug von einem Assistenten anhand der Konfigurations-ID.

Endpunkt

DELETE /api/assistants/{assistantId}/tools/workflow?config_id={configId}

Abfrageparameter

Antwortfelder

Gemeinsame Antwortstruktur

Die Assistant-Endpunkte verwenden eine konsistente Antwortform mit einem success-Flag und einem ressourcenspezifischen Payload.