Accès à l’API

VoiceBooker fournit un accès programmatique à son API pour intégrer d’autres applications et automatiser des processus, notamment la récupération de l’utilisation, le déploiement de bots et l’intégration de pipelines CI/CD.

URL de base

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

Authentification

Envoyez un token API avec chaque requête via ce header :

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

Le token détermine le contexte de l’entreprise pour la requête. Conservez-le en lieu sûr.

Exporter un bot

GET /exportBots/{botId} exporte un bot de l’entreprise associée au token API. Utilisez pretty=true pour obtenir un HJSON lisible.

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

Exemple de réponse :

{
  "name": "Assistant d’accueil",
  "id": "kqrmxaveli",
  "stages": [
    {
      "name": "Welcome",
      "id": "mavotirenu",
      "linkId": "qeluzanopi",
      "template": false,
      "prompt": "Accueillez l’appelant.",
      "tools": [],
      "functions": [],
      "settings": {},
      "stageConfig": [],
      "x": 0,
      "y": 0,
      "order": 0,
      "instanceSettings": {}
    }
  ],
  "settings": {},
  "wizard": {}
}

Importer un bot

POST /importBots importe une définition de bot dans l’entreprise associée au token. Envoyez la définition dans contents. Pour le HJSON, filename doit se terminer par .hjson. overwriteBotStages, overwriteTemplates et replaceBotStages sont des paramètres booléens facultatifs.

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

Exemple de réponse :

{
  "id": "vexorimaku",
  "name": "Assistant d’accueil",
  "settings": {},
  "invisible": false
}

Passer des appels sortants

Pour passer un appel sortant, envoyez une requête POST à :

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

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

Exemple de requête :

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

Paramètre	Description
`dest`	Numéro à appeler au format E.164.
`botId`	Bot utilisé pour l’appel.
`sipAccountId`	Compte SIP utilisé ; son numéro est affiché au destinataire.
`ringTimeout`	Secondes de sonnerie avant l’annulation sans réponse. Par défaut : 30 secondes.
`startTimeout`	Secondes d’attente avant que le bot commence à parler.
`state`	Données utilisables par les webhooks ou appels API pendant l’appel, comme un ID client.

L’API renvoie un callId :

{
  "callId": "xavurimeto"
}

Gérer les tests de bots

Les tests de bots comparent un bot source/appelant avec un bot destination/répondant. Les requêtes avec une clé API sont limitées à l’entreprise associée au token ; les deux bots doivent appartenir à cette entreprise.

Méthode	Endpoint	Fonction
`GET`	`/bot_test_setups`	Lister les tests.
`POST`	`/bot_test_setups`	Créer un test.
`PUT`	`/bot_test_setups/{id}`	Modifier un test.
`DELETE`	`/bot_test_setups/{id}`	Supprimer un test.

La réponse publique contient uniquement id, name, settings, srcBotId et destBotId. settings peut contenir convInitBot, maxConvTurns, asCall, startTimeout et stateUpdate. Lors d’une modification, les champs omis sont conservés.

Récupérer un enregistrement d’appel

GET /getRecording/{id} renvoie l’enregistrement MP3 d’une session d’appel. Utilisez comme id l’identifiant de session renvoyé par /usage. L’enregistrement doit avoir été activé pour l’appel.

La réponse est transmise en audio/mpeg et peut être enregistrée directement dans un fichier .mp3 :

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

L’endpoint renvoie 404 Not Found lorsque la session ou son enregistrement n’est pas disponible pour le token API. Il renvoie 401 Unauthorized si le token API est absent ou invalide.

Récupérer l’utilisation

GET /usage renvoie les sessions téléphoniques et de chat de l’entreprise authentifiée et de ses entreprises partenaires disponibles.

Sans businessId, toutes les entreprises disponibles sont incluses. Utilisez businessId pour sélectionner une entreprise, puis start et end pour filtrer selon la date de création de la session.

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

start et end sont inclusifs. Utilisez des dates ISO 8601 valides. Une entreprise hors du périmètre du token renvoie 403 Forbidden.

Exemple de réponse :

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

Lister les entreprises partenaires

Pour les intégrations de partenaires et de revendeurs, GET /partnerClients renvoie les entreprises visibles associées à l’entreprise authentifiée. Leurs IDs peuvent être utilisés avec le filtre businessId de l’endpoint d’utilisation.

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

Exemple de réponse :

[
  {
    "id": "zpjwletodo",
    "name": "Entreprise partenaire",
    "city": "Paris",
    "country": "FR"
  }
]

Gérer les fichiers de la base de connaissances et les fichiers multimédias

Les clés API peuvent lister, téléverser et supprimer les fichiers de l’entreprise associée au token. Les identifiants sont obfusqués, mais les noms des attributs de réponse ne le sont pas.

Lister les fichiers de la base de connaissances

GET /knowledgeBase renvoie id, name, fileSize et tokens.

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

Téléverser un fichier de la base de connaissances

POST /knowledgeBase accepte un envoi multipart avec les champs file et name.

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

Supprimer un fichier de la base de connaissances

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

Lister et téléverser des fichiers multimédias

GET /mediaFiles renvoie id, name et fileSize. POST /mediaFiles utilise les mêmes champs multipart.

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

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

Supprimer un fichier multimédia

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

Spécification OpenAPI

openapi: 3.1.0
info:
  title: VoiceBooker Partner API
  version: 1.0.0
  description: API de consultation des entreprises partenaires et de leur utilisation.
servers: [{url: https://voicebooker.de/app/api/v1}]
paths:
  /exportBots/{botId}:
    get:
      summary: Exporter un bot
      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: Définition du bot exporté., 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: Le bot n’appartient pas à l’entreprise du token.}
  /importBots:
    post:
      summary: Importer un bot
      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: Bot importé., content: {application/json: {schema: {type: object, properties: {id: {type: string}, name: {type: string}}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /makeCall:
    post:
      summary: Passer un appel sortant
      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: Appel sortant démarré., content: {application/json: {schema: {type: object, properties: {callId: {type: string}}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /getRecording/{id}:
    get:
      summary: Récupérer un enregistrement d’appel
      operationId: getCallRecording
      security: [{apiToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string}, description: Identifiant de la session d’appel.}
      responses:
        '200': {description: Enregistrement d’appel., content: {audio/mpeg: {schema: {type: string, format: binary}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '404': {description: La session ou l’enregistrement n’est pas disponible pour ce token API.}
  /usage:
    get:
      summary: Récupérer l’utilisation
      operationId: listUsage
      security: [{apiToken: []}]
      parameters:
        - {name: businessId, in: query, schema: {type: string}, description: Entreprise à consulter.}
        - {name: start, in: query, schema: {type: string, format: date-time}, description: Début inclusif.}
        - {name: end, in: query, schema: {type: string, format: date-time}, description: Fin inclusive.}
      responses:
        '200': {description: Données d’utilisation., content: {application/json: {schema: {type: array, items: {$ref: '#/components/schemas/UsageRecord'}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: L’entreprise n’est pas disponible pour ce token.}
  /partnerClients:
    get:
      summary: Lister les entreprises partenaires
      operationId: listPartnerClients
      security: [{apiToken: []}]
      responses:
        '200': {description: Liste des entreprises., 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: Fichiers de la base de connaissances., 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: ID du fichier téléversé., 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: Fichier supprimé.}, '401': {$ref: '#/components/responses/Unauthorized'}, '403': {description: Fichier hors du périmètre du token.}}
  /mediaFiles:
    get:
      operationId: listMediaFiles
      security: [{apiToken: []}]
      responses: {'200': {description: Fichiers multimédias., 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: ID du fichier téléversé., 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: Fichier supprimé.}, '401': {$ref: '#/components/responses/Unauthorized'}, '403': {description: Fichier hors du périmètre du token.}}
  /bot_test_setups:
    get:
      operationId: listBotTests
      security: [{apiToken: []}]
      responses: {'200': {description: Tests de bots., 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: Test créé., content: {application/json: {schema: {$ref: '#/components/schemas/BotTestSetup'}}}}, '401': {$ref: '#/components/responses/Unauthorized'}, '403': {description: Bot hors périmètre ou bots identiques.}}
  /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: Test modifié., content: {application/json: {schema: {$ref: '#/components/schemas/BotTestSetup'}}}}, '401': {$ref: '#/components/responses/Unauthorized'}, '403': {description: Bot hors périmètre ou bots identiques.}, '404': {description: Test introuvable.}}
    delete:
      operationId: deleteBotTest
      security: [{apiToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: string}}]
      responses: {'200': {description: Test supprimé.}, '401': {$ref: '#/components/responses/Unauthorized'}, '404': {description: Test introuvable.}}
components:
  securitySchemes:
    apiToken: {type: apiKey, in: header, name: X-API-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: Le token est absent ou invalide.}

Erreurs HTTP

401 Unauthorized : le token API est absent ou invalide.
403 Forbidden : l’entreprise demandée n’est pas disponible pour ce token.

Accès à l’API

On this page