API-Zugriff

VoiceBooker bietet programmgesteuerten API-Zugriff zur Integration mit anderen Anwendungen und zur Automatisierung von Abläufen, etwa zum Abrufen von Nutzungsdaten, für Bot-Bereitstellungen und für CI/CD-Pipelines.

Basis-URL

https://voicebooker.de/app/api/v1

Authentifizierung

Senden Sie bei jeder Anfrage ein API-Token über diesen Header:

X-API-TOKEN: <ihr-api-token>

Das Token bestimmt den Unternehmenskontext der Anfrage. Bewahren Sie es sicher auf.

Bot exportieren

GET /exportBots/{botId} exportiert einen Bot des Unternehmens, das mit dem API-Token verbunden ist. Mit pretty=true wird ein lesbares HJSON-Dokument zurückgegeben.

curl --get 'https://voicebooker.de/app/api/v1/exportBots/<bot-id>' \
  --header 'X-API-TOKEN: <ihr-api-token>' \
  --data-urlencode 'pretty=true'

Beispielantwort:

{
  "name": "Empfangsassistent",
  "id": "kqrmxaveli",
  "stages": [
    {
      "name": "Welcome",
      "id": "mavotirenu",
      "linkId": "qeluzanopi",
      "template": false,
      "prompt": "Begrüßen Sie den Anrufer.",
      "tools": [],
      "functions": [],
      "settings": {},
      "stageConfig": [],
      "x": 0,
      "y": 0,
      "order": 0,
      "instanceSettings": {}
    }
  ],
  "settings": {},
  "wizard": {}
}

Bot importieren

POST /importBots importiert eine Bot-Definition in das Unternehmen des API-Tokens. Senden Sie die exportierte Definition als contents. Für HJSON muss filename mit .hjson enden. overwriteBotStages, overwriteTemplates und replaceBotStages sind optionale boolesche Parameter.

curl --request POST \
  --url https://voicebooker.de/app/api/v1/importBots \
  --header 'X-API-TOKEN: <ihr-api-token>' \
  --header 'Content-Type: application/json' \
  --data '{"filename":"bot.json","contents":{"name":"Empfangsassistent","settings":{},"stages":[]},"overwriteBotStages":false,"overwriteTemplates":false,"replaceBotStages":false}'

Beispielantwort:

{
  "id": "vexorimaku",
  "name": "Empfangsassistent",
  "settings": {},
  "invisible": false
}

Ausgehende Anrufe tätigen

Für einen ausgehenden Anruf senden Sie eine POST-Anfrage an:

https://voicebooker.de/app/api/v1/makeCall

Content-Type: application/json
X-API-TOKEN: <ihr-api-token>

Beispielanfrage:

{
  "dest": "+49-351-123456789",
  "botId": "kqrmxaveli",
  "sipAccountId": "lupenakori",
  "ringTimeout": 25,
  "startTimeout": 10,
  "state": {
    "customerId": "zpjwletodo"
  }
}

Parameter	Beschreibung
`dest`	Zielnummer im E.164-Format.
`botId`	Für den Anruf verwendeter Bot.
`sipAccountId`	Für den Anruf verwendetes SIP-Konto; dessen Nummer wird beim Angerufenen angezeigt.
`ringTimeout`	Sekunden, die geklingelt wird, bevor ohne Antwort abgebrochen wird. Standard: 30 Sekunden.
`startTimeout`	Sekunden, die der Bot vor dem Sprechen wartet.
`state`	Daten für Webhooks oder API-Aufrufe während des Anrufs, zum Beispiel eine Kunden-ID.

Die API gibt eine callId zurück:

{
  "callId": "xavurimeto"
}

Bot-Tests verwalten

Bot-Tests vergleichen einen Quell-/Anrufer-Bot mit einem Ziel-/Antwort-Bot. API-Key-Anfragen sind auf das mit dem Token verbundene Unternehmen beschränkt; beide Bots müssen zu diesem Unternehmen gehören.

Methode	Endpunkt	Zweck
`GET`	`/bot_test_setups`	Bot-Tests auflisten.
`POST`	`/bot_test_setups`	Bot-Test erstellen.
`PUT`	`/bot_test_setups/{id}`	Bot-Test aktualisieren.
`DELETE`	`/bot_test_setups/{id}`	Bot-Test löschen.

Die öffentliche Antwort verwendet die Felder id, name, settings, srcBotId und destBotId. settings kann unter anderem convInitBot, maxConvTurns, asCall, startTimeout und stateUpdate enthalten. Beim Aktualisieren bleiben nicht angegebene Felder erhalten.

Eine Anrufaufzeichnung abrufen

GET /getRecording/{id} gibt die MP3-Aufzeichnung einer Anrufsitzung zurück. Verwenden Sie als id die von /usage zurückgegebene ID der Anrufsitzung. Für den Anruf muss die Aufzeichnung aktiviert worden sein.

Die Antwort wird als audio/mpeg gestreamt und kann direkt als .mp3-Datei gespeichert werden:

curl --request GET \
  --url https://voicebooker.de/app/api/v1/getRecording/<anrufsitzungs-id> \
  --header 'X-API-TOKEN: <ihr-api-token>' \
  --output aufzeichnung.mp3

Der Endpunkt gibt 404 Not Found zurück, wenn die Anrufsitzung oder ihre Aufzeichnung für das API-Token nicht verfügbar ist. Bei fehlendem oder ungültigem API-Token wird 401 Unauthorized zurückgegeben.

Nutzung abrufen

GET /usage liefert Telefon- und Chat-Sitzungen des authentifizierten Unternehmens und seiner verfügbaren Partnerunternehmen.

Ohne businessId werden alle Unternehmen in diesem Bereich berücksichtigt. Mit businessId kann ein Unternehmen ausgewählt werden. start und end filtern nach dem Erstellungszeitpunkt der Sitzung.

curl --get https://voicebooker.de/app/api/v1/usage \
  --header 'X-API-TOKEN: <ihr-api-token>' \
  --data-urlencode 'businessId=zpjwletodo' \
  --data-urlencode 'start=2026-01-01T00:00:00Z' \
  --data-urlencode 'end=2026-02-01T00:00:00Z'

start und end sind einschließlich. Verwenden Sie parsebare ISO-8601-Datumswerte. Ein Unternehmen außerhalb des Token-Bereichs führt zu 403 Forbidden.

Beispielantwort:

[
  {
    "id": "xavurimeto", "businessId": "zpjwletodo", "botId": "kqrmxaveli",
    "isCall": true, "direction": "inbound", "phoneNumberCaller": "+491701234567",
    "phoneNumberCallee": "+49301234567", "duration": 184, "costs": 0.46,
    "start": "2026-01-15T10:30:00.000Z"
  }
]

Partnerunternehmen auflisten

Für Reseller- und Partnerintegrationen liefert GET /partnerClients die sichtbaren, mit dem authentifizierten Partnerunternehmen verbundenen Unternehmen. Die IDs können für den Filter businessId des Nutzungsendpunkts verwendet werden.

curl --request GET \
  --url https://voicebooker.de/app/api/v1/partnerClients \
  --header 'X-API-TOKEN: <ihr-api-token>'

Beispielantwort:

[
  {
    "id": "zpjwletodo",
    "name": "Beispielunternehmen",
    "city": "Berlin",
    "country": "DE"
  }
]

Wissensbasis- und Mediendateien verwalten

API-Schlüssel können Dateien des mit dem Token verknüpften Unternehmens auflisten, hochladen und löschen. Die Datei-IDs sind obfuskiert; die Antwortfelder werden für die API nicht obfuskiert.

Wissensbasisdateien auflisten

GET /knowledgeBase liefert id, name, fileSize und tokens.

curl --request GET \
  --url https://voicebooker.de/app/api/v1/knowledgeBase \
  --header 'X-API-TOKEN: <ihr-api-token>'

Wissensbasisdatei hochladen

POST /knowledgeBase akzeptiert einen Multipart-Upload mit den Feldern file und name.

curl --request POST \
  --url https://voicebooker.de/app/api/v1/knowledgeBase \
  --header 'X-API-TOKEN: <ihr-api-token>' \
  --form 'name=handbuch.pdf' \
  --form 'file=@handbuch.pdf'

Wissensbasisdatei löschen

curl --request DELETE \
  --url https://voicebooker.de/app/api/v1/knowledgeBase/<datei-id> \
  --header 'X-API-TOKEN: <ihr-api-token>'

Mediendateien auflisten und hochladen

GET /mediaFiles liefert id, name und fileSize. POST /mediaFiles verwendet dieselben Multipart-Felder wie der Wissensbasis-Upload.

curl --request GET \
  --url https://voicebooker.de/app/api/v1/mediaFiles \
  --header 'X-API-TOKEN: <ihr-api-token>'

curl --request POST \
  --url https://voicebooker.de/app/api/v1/mediaFiles \
  --header 'X-API-TOKEN: <ihr-api-token>' \
  --form 'name=musik.mp3' \
  --form 'file=@musik.mp3'

Mediendatei löschen

curl --request DELETE \
  --url https://voicebooker.de/app/api/v1/mediaFiles/<datei-id> \
  --header 'X-API-TOKEN: <ihr-api-token>'

OpenAPI-Spezifikation

openapi: 3.1.0
info:
  title: VoiceBooker Partner API
  version: 1.0.0
  description: API zum Abrufen verbundener Unternehmen und Nutzungsdaten.
servers:
  - url: https://voicebooker.de/app/api/v1
paths:
  /exportBots/{botId}:
    get:
      summary: Bot exportieren
      operationId: exportBot
      security: [{apiToken: []}]
      parameters:
        - {name: botId, in: path, required: true, schema: {type: string}}
        - {name: pretty, in: query, schema: {type: boolean, default: false}}
      responses:
        '200': {description: Exportierte Bot-Definition., content: {application/json: {schema: {type: object, properties: {id: {type: string}, name: {type: string}, stages: {type: array, items: {type: object}}, settings: {type: object}, wizard: {type: object}}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: Der Bot gehört nicht zum Unternehmen des Tokens.}
  /importBots:
    post:
      summary: Bot importieren
      operationId: importBot
      security: [{apiToken: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [contents]
              properties:
                filename: {type: string}
                contents: {oneOf: [{type: object}, {type: string}]}
                overwriteBotStages: {type: boolean, default: false}
                overwriteTemplates: {type: boolean, default: false}
                replaceBotStages: {type: boolean, default: false}
      responses:
        '200': {description: Importierter Bot., content: {application/json: {schema: {type: object, properties: {id: {type: string}, name: {type: string}}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /makeCall:
    post:
      summary: Ausgehenden Anruf tätigen
      operationId: makeOutboundCall
      security: [{apiToken: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [dest, botId, sipAccountId]
              properties:
                dest: {type: string}
                botId: {type: string}
                sipAccountId: {type: string}
                ringTimeout: {type: integer, default: 30}
                startTimeout: {type: integer, default: 0}
                state: {type: object, additionalProperties: true}
      responses:
        '200': {description: Ausgehender Anruf gestartet., content: {application/json: {schema: {type: object, properties: {callId: {type: string}}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /getRecording/{id}:
    get:
      summary: Eine Anrufaufzeichnung abrufen
      operationId: getCallRecording
      security: [{apiToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string}, description: ID der Anrufsitzung.}
      responses:
        '200': {description: Anrufaufzeichnung., content: {audio/mpeg: {schema: {type: string, format: binary}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '404': {description: Anrufsitzung oder Aufzeichnung ist für dieses API-Token nicht verfügbar.}
  /usage:
    get:
      summary: Nutzung abrufen
      operationId: listUsage
      security: [{apiToken: []}]
      parameters:
        - {name: businessId, in: query, schema: {type: string}, description: Unternehmen, für das Daten abgerufen werden.}
        - {name: start, in: query, schema: {type: string, format: date-time}, description: Einschließender Beginn.}
        - {name: end, in: query, schema: {type: string, format: date-time}, description: Einschließendes Ende.}
      responses:
        '200':
          description: Nutzungsdaten.
          content: {application/json: {schema: {type: array, items: {$ref: '#/components/schemas/UsageRecord'}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: Das Unternehmen liegt außerhalb des Token-Bereichs.}
  /partnerClients:
    get:
      summary: Partnerunternehmen auflisten
      operationId: listPartnerClients
      security: [{apiToken: []}]
      responses:
        '200':
          description: Liste der Partnerunternehmen.
          content: {application/json: {schema: {type: array, items: {$ref: '#/components/schemas/PartnerBusiness'}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /knowledgeBase:
    get:
      operationId: listKnowledgeBaseFiles
      security: [{apiToken: []}]
      responses:
        '200': {description: Knowledge-Base-Dateien., content: {application/json: {schema: {type: array, items: {$ref: '#/components/schemas/KnowledgeBaseFile'}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
    post:
      operationId: uploadKnowledgeBaseFile
      security: [{apiToken: []}]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema: {type: object, required: [file, name], properties: {file: {type: string, format: binary}, name: {type: string}}}
      responses:
        '200': {description: Hochgeladene Datei-ID., content: {application/json: {schema: {type: object, properties: {id: {type: string}}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /knowledgeBase/{fileId}:
    delete:
      operationId: deleteKnowledgeBaseFile
      security: [{apiToken: []}]
      parameters: [{name: fileId, in: path, required: true, schema: {type: string}}]
      responses:
        '200': {description: Datei gelöscht.}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: Die Datei gehört nicht zum Unternehmen des Tokens.}
  /mediaFiles:
    get:
      operationId: listMediaFiles
      security: [{apiToken: []}]
      responses:
        '200': {description: Mediendateien., content: {application/json: {schema: {type: array, items: {$ref: '#/components/schemas/MediaFile'}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
    post:
      operationId: uploadMediaFile
      security: [{apiToken: []}]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema: {type: object, required: [file, name], properties: {file: {type: string, format: binary}, name: {type: string}}}
      responses:
        '200': {description: Hochgeladene Datei-ID., content: {application/json: {schema: {type: object, properties: {id: {type: string}}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /mediaFiles/{fileId}:
    delete:
      operationId: deleteMediaFile
      security: [{apiToken: []}]
      parameters: [{name: fileId, in: path, required: true, schema: {type: string}}]
      responses:
        '200': {description: Datei gelöscht.}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: Die Datei gehört nicht zum Unternehmen des Tokens.}
  /bot_test_setups:
    get:
      operationId: listBotTests
      security: [{apiToken: []}]
      responses:
        '200': {description: Bot-Tests des authentifizierten Unternehmens., content: {application/json: {schema: {type: array, items: {$ref: '#/components/schemas/BotTestSetup'}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
    post:
      operationId: createBotTest
      security: [{apiToken: []}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/BotTestSetupInput'}}}}
      responses:
        '200': {description: Erstellt., content: {application/json: {schema: {$ref: '#/components/schemas/BotTestSetup'}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: Ungültiger Bot-Bereich oder identische Bots.}
  /bot_test_setups/{id}:
    put:
      operationId: updateBotTest
      security: [{apiToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: string}}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/BotTestSetupUpdate'}}}}
      responses:
        '200': {description: Aktualisiert., content: {application/json: {schema: {$ref: '#/components/schemas/BotTestSetup'}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: Ungültiger Bot-Bereich oder identische Bots.}
        '404': {description: Bot-Test nicht gefunden.}
    delete:
      operationId: deleteBotTest
      security: [{apiToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: string}}]
      responses:
        '200': {description: Bot-Test gelöscht.}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '404': {description: Bot-Test nicht gefunden.}
components:
  securitySchemes:
    apiToken: {type: apiKey, in: header, name: X-API-TOKEN, description: 'X-API-TOKEN: <token>'}
  schemas:
    PartnerBusiness:
      type: object
      properties: {id: {type: string}, name: {type: string}}
    UsageRecord:
      type: object
      properties:
        id: {type: string}
        businessId: {type: string}
        botId: {type: string, nullable: true}
        isCall: {type: boolean}
        direction: {type: string, enum: [inbound, outbound]}
        phoneNumberCaller: {type: string, nullable: true}
        phoneNumberCallee: {type: string, nullable: true}
        duration: {type: integer}
        costs: {type: number}
        start: {type: string, format: date-time}
    KnowledgeBaseFile:
      type: object
      properties: {id: {type: string}, name: {type: string}, fileSize: {type: integer}, tokens: {type: integer}}
    MediaFile:
      type: object
      properties: {id: {type: string}, name: {type: string}, fileSize: {type: integer}}
    BotTestSetup:
      type: object
      properties: {id: {type: string}, name: {type: string}, settings: {type: object, additionalProperties: true}, srcBotId: {type: string}, destBotId: {type: string}}
    BotTestSetupInput:
      type: object
      required: [name, srcBotId, destBotId]
      properties: {name: {type: string}, settings: {type: object, additionalProperties: true}, srcBotId: {type: string}, destBotId: {type: string}}
    BotTestSetupUpdate:
      type: object
      properties: {name: {type: string}, settings: {type: object, additionalProperties: true}, srcBotId: {type: string}, destBotId: {type: string}}
  responses:
    Unauthorized:
      description: Das Token fehlt oder ist ungültig.
      content: {application/json: {schema: {type: object, properties: {error: {type: string}}}}}

HTTP-Fehler

401 Unauthorized: Das API-Token fehlt oder ist ungültig.
403 Forbidden: Das angeforderte Unternehmen ist für das Token nicht verfügbar.

API-Zugriff

On this page