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. Unterstützt werden beide folgenden Header:

Authorization: Bearer <ihr-api-token>

oder:

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; nt=true liefert das Nested-Text-Format.

curl --get 'https://voicebooker.de/app/api/v1/exportBots/<bot-id>' \
  --header 'Authorization: Bearer <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 'Authorization: Bearer <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
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"
}

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 'Authorization: Bearer <ihr-api-token>'

Beispielantwort:

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

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: [{bearerAuth: []}, {apiToken: []}]
      parameters:
        - {name: botId, in: path, required: true, schema: {type: string}}
        - {name: pretty, in: query, schema: {type: boolean, default: false}}
        - {name: nt, 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: [{bearerAuth: []}, {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: [{tokenAuth: []}]
      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'}
  /usage:
    get:
      summary: Nutzung abrufen
      operationId: listUsage
      security: [{bearerAuth: []}, {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: [{bearerAuth: []}, {apiToken: []}]
      responses:
        '200':
          description: Liste der Partnerunternehmen.
          content: {application/json: {schema: {type: array, items: {$ref: '#/components/schemas/PartnerBusiness'}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
components:
  securitySchemes:
    tokenAuth: {type: apiKey, in: header, name: Token, description: 'Token: <token>'}
    bearerAuth: {type: http, scheme: bearer, description: 'Authorization: Bearer <token>'}
    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}
  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

Auf dieser Seite