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.

Lister les sessions d’appel et récupérer les transcriptions

Utilisez GET /call_sessions pour lister les sessions d’appel ou GET /conversations pour lister les sessions dont la transcription est visible. Pour lister les sessions, ces deux endpoints nécessitent les dates start et end et renvoient 30 éléments par page par défaut. Le champ call indique s’il s’agit d’un appel téléphonique.

curl --get https://voicebooker.de/app/api/v1/call_sessions \
  --header 'X-API-TOKEN: <votre-token-api>' \
  --data-urlencode 'start=2026-01-01' \
  --data-urlencode 'end=2026-01-31' \
  --data-urlencode 'page=1'

Utilisez l’identifiant de session d’une liste pour récupérer sa transcription (cs.id dans /call_sessions, id dans /conversations) :

curl --get 'https://voicebooker.de/app/api/v1/conversations/<id-de-session>' \
  --header 'X-API-TOKEN: <votre-token-api>' \
  --data-urlencode 'trace=true' \
  --data-urlencode 'page=1'

Avec trace=true, chaque page contient jusqu’à 1 000 tours de transcription dans l’ordre chronologique, ainsi que les prompts, l’état, la pile et les détails fsCalls des fonctions/webhooks disponibles. Omettez trace pour obtenir la page standard de 30 éléments. Utilisez page pour récupérer les pages suivantes. L’accès est limité aux entreprises disponibles pour le token.

Si vous connaissez déjà l’identifiant du contexte téléphonique, GET /conversations?contextUId=<id-du-contexte> renvoie une transcription compacte.

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.

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.}
  /call_sessions:
    get:
      tags: [Partner access]
      operationId: listCallSessions
      summary: Lister les sessions d’appel
      description: Renvoie les sessions d’appel des entreprises accessibles avec le token API.
      security: [{apiToken: []}]
      parameters:
        - {name: start, in: query, required: true, description: Date de début incluse (AAAA-MM-JJ)., schema: {type: string, format: date}}
        - {name: end, in: query, required: true, description: Date de fin incluse (AAAA-MM-JJ)., schema: {type: string, format: date}}
        - {name: page, in: query, required: false, schema: {type: integer, minimum: 1, default: 1}}
      responses:
        '200': {description: Page de sessions d’appel (30 éléments par page)., content: {application/json: {schema: {type: array, items: {type: object, additionalProperties: true}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /conversations:
    get:
      tags: [Partner access]
      operationId: listTranscribedSessions
      summary: Lister les sessions avec transcription
      description: Renvoie les sessions visibles avec transcription des entreprises accessibles avec le token API. Le paramètre contextUId peut à la place récupérer une transcription compacte pour un contexte téléphonique connu.
      security: [{apiToken: []}]
      parameters:
        - {name: start, in: query, required: false, description: Obligatoire pour lister les sessions., schema: {type: string, format: date}}
        - {name: end, in: query, required: false, description: Obligatoire pour lister les sessions., schema: {type: string, format: date}}
        - {name: page, in: query, required: false, schema: {type: integer, minimum: 1, default: 1}}
        - {name: contextUId, in: query, required: false, description: Renvoie une transcription compacte pour ce contexte téléphonique au lieu d’une liste de sessions., schema: {type: string}}
      responses:
        '200': {description: Page de sessions avec transcription ou transcription compacte du contexte., content: {application/json: {schema: {type: array, items: {type: object, additionalProperties: true}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /conversations/{id}:
    get:
      tags: [Partner access]
      operationId: getCallTranscript
      summary: Récupérer une transcription d’appel
      description: Renvoie les tours de transcription dans l’ordre chronologique et les données de trace associées à une session disponible. trace=true inclut jusqu’à 1 000 tours par page, avec les prompts, l’état, la pile et les appels de fonction/webhook disponibles.
      security: [{apiToken: []}]
      parameters:
        - {name: id, in: path, required: true, description: Identifiant de session obtenu dans une liste., schema: {type: string}}
        - {name: page, in: query, required: false, schema: {type: integer, minimum: 1, default: 1}}
        - {name: trace, in: query, required: false, description: Définissez true pour obtenir la trace détaillée ; omettez ce paramètre pour la réponse standard., schema: {type: boolean}}
      responses:
        '200': {description: Tours de transcription de la page demandée., content: {application/json: {schema: {type: array, items: {type: object, additionalProperties: true}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /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