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"
}

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'}
  /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'}
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}
  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

Sur cette page