Zum Inhalt springen
Hilfe-Center
Support kontaktierenApp öffnen

Gespräche auflisten

GET
/v1/conversations
curl --request GET \
--url 'https://api.speakki.de/v1/conversations?direction=inbound' \
--header 'Authorization: Bearer <token>'

Geführte Telefongespräche Ihrer Assistenten, eingehend und ausgehend, neueste zuerst. Mit Zusammenfassung, Einordnung und erfassten Daten, ohne Transkript. GET /v1/calls zeigt dagegen die Aufträge für ausgehende Anrufe, auch solche ohne Gespräch.

Berechtigung: calls:read.

direction
string
Allowed values: inbound outbound

Nur eingehende oder nur ausgehende Gespräche.

from
string format: date-time

Beginn ab diesem Zeitpunkt (einschließlich).

to
string format: date-time

Beginn vor diesem Zeitpunkt (ausschließlich).

limit
integer
>= 1 <= 100

Gespräche je Seite, 1 bis 100, Standard 25.

cursor
string
>= 1 characters <= 200 characters

next_cursor der vorigen Seite.

Eine Seite Gespräche.

Media typeapplication/json

Eine Seite Gespräche, neueste zuerst.

object
data
required

Die Einträge dieser Seite.

Array<object>

Ein geführtes Telefongespräch, eingehend oder ausgehend, ohne Transkript.

object
id
required

ID des Gesprächs (dieselbe wie interactionId im Webhook).

string format: uuid
direction
required

inbound eingehend, outbound ausgehend.

string
Allowed values: inbound outbound
started_at
required

Beginn des Gesprächs.

string format: date-time
ended_at
required
Any of:
string format: date-time
duration_seconds
required
Any of:
integer
phone_number
required

Nummer des Gesprächspartners in E.164: der Anrufer bei eingehenden, das Ziel bei ausgehenden Gesprächen. null bei unterdrückter Nummer.

string | null
own_number
required

Ihre Rufnummer: die angerufene Nummer bei eingehenden, der Absender bei ausgehenden Gesprächen.

string | null
caller_name
required

Name des Gesprächspartners, falls bekannt.

string | null
assistant_id
required
Any of:
string format: uuid
assistant_name
required

Name des Assistenten, wie er im Dashboard steht.

string | null
contact_id
required
Any of:
string format: uuid
status
required

Bearbeitungsstand im Posteingang.

string
Allowed values: open in_progress done archived
category
required
Any of:
object
slug
required

Fester Schlüssel der Einordnung.

string
label
required

Bezeichnung der Einordnung.

string
summary
required

Zusammenfassung des Gesprächs.

string | null
captured_data
required

Daten, die der Assistent im Gespräch erfasst hat.

Array<object>
object
tool_name
required

Name der Erfassung im Assistenten.

string
label
required

Bezeichnung der Erfassung.

string | null
case_key
required

Nur bei „Anliegen aufnehmen“: Schlüssel des Falls.

string | null
case_name
required

Nur bei „Anliegen aufnehmen“: Name des Falls.

string | null
incomplete
required

true, wenn der Anrufer vor den letzten Angaben aufgelegt hat.

boolean
captured_at
required

Zeitpunkt der Erfassung.

string
fields
required

Die erfassten Angaben.

Array<object>
object
name
required

Name des Felds.

string
type
required

Typ des Felds, zum Beispiel string oder boolean.

string | null
value
required

Der erfasste Wert, Typ je Feld.

outbound_call_id
required
Any of:
string format: uuid
content_deleted
required

true, wenn Inhalte nach Ablauf der Löschfrist entfernt wurden (Zusammenfassung, erfasste Daten, Transkript).

boolean
next_cursor
required

Für die nächste Seite als cursor senden. null = keine weitere Seite.

string | null

Example

{
"data": [
{
"id": "c1a7e3f9-2b4d-4c6e-9f8a-0d3b5e7a9c21",
"direction": "inbound",
"started_at": "2026-11-16T09:00:00.000Z",
"ended_at": "2026-11-16T09:03:00.000Z",
"duration_seconds": 180,
"phone_number": "+4915228817386",
"own_number": "+493023125010",
"caller_name": "Max Mustermann",
"assistant_id": "5e2a9c1b-7f43-4c1d-8b0a-3d9e6f2a1c44",
"assistant_name": "Empfang",
"contact_id": "a4d2c8e6-5f1b-4a3d-8c7e-9b0f2d4a6c81",
"status": "open",
"category": {
"slug": "REQUEST_RECORDED",
"label": "Anliegen aufgenommen"
},
"summary": "Herr Mustermann möchte ein Angebot für die jährliche Heizungswartung und bittet um Rückruf.",
"captured_data": [
{
"tool_name": "rueckruf_erfassen",
"label": "Rückrufwunsch erfassen",
"case_key": null,
"case_name": null,
"incomplete": false,
"captured_at": "2026-11-16T09:02:40.000Z",
"fields": [
{
"name": "name",
"type": "string",
"value": "Max Mustermann"
}
]
}
],
"outbound_call_id": null,
"content_deleted": false
}
]
}

Ungültige Anfrage.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Exampleinvalid_request
{
"error": {
"code": "invalid_request",
"message": "Die Anfrage ist ungültig."
}
}

API-Schlüssel fehlt oder ist ungültig.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Exampleunauthorized
{
"error": {
"code": "unauthorized",
"message": "Der API-Schlüssel fehlt oder ist ungültig. Senden Sie ihn als „Authorization: Bearer spk_live_…“."
}
}

Nicht erlaubt: Tarif, Freischaltung oder Berechtigung des Schlüssels.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

{
"error": {
"code": "insufficient_scope",
"message": "Diesem API-Schlüssel fehlt die Berechtigung für diese Anfrage."
}
}

Zu viele Anfragen. retry-after und x-ratelimit-reset nennen die Sekunden, bis wieder Anfragen möglich sind.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Examplerate_limited
{
"error": {
"code": "rate_limited",
"message": "Zu viele Anfragen. Bitte versuchen Sie es gleich noch einmal."
}
}

Interner Fehler.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Exampleinternal_error
{
"error": {
"code": "internal_error",
"message": "Interner Fehler. Bitte versuchen Sie es später noch einmal."
}
}