Acceso a la API

VoiceBooker ofrece acceso programático a la API para integrar otras aplicaciones y automatizar flujos, como la recuperación de uso, el despliegue de bots y la integración con pipelines de CI/CD.

URL base

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

Autenticación

Envíe un token API en cada solicitud mediante este header:

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

El token determina el contexto de empresa de la solicitud. Manténgalo seguro.

Exportar un bot

GET /exportBots/{botId} exporta un bot de la empresa asociada al token API. Use pretty=true para obtener HJSON legible.

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

Ejemplo de respuesta:

{
  "name": "Asistente de recepción",
  "id": "kqrmxaveli",
  "stages": [
    {
      "name": "Welcome",
      "id": "mavotirenu",
      "linkId": "qeluzanopi",
      "template": false,
      "prompt": "Saluda a la persona que llama.",
      "tools": [],
      "functions": [],
      "settings": {},
      "stageConfig": [],
      "x": 0,
      "y": 0,
      "order": 0,
      "instanceSettings": {}
    }
  ],
  "settings": {},
  "wizard": {}
}

POST /importBots importa una definición de bot en la empresa asociada al token. Envíe la definición exportada en contents. Para HJSON, filename debe terminar en .hjson. overwriteBotStages, overwriteTemplates y replaceBotStages son parámetros booleanos opcionales.

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

Ejemplo de respuesta:

{
  "id": "vexorimaku",
  "name": "Asistente de recepción",
  "settings": {},
  "invisible": false
}

Realizar llamadas salientes

Para realizar una llamada saliente, envíe una solicitud POST a:

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

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

Ejemplo de solicitud:

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

Parámetro	Descripción
`dest`	Número de destino en formato E.164.
`botId`	Bot utilizado para la llamada.
`sipAccountId`	Cuenta SIP utilizada; su número aparece al destinatario.
`ringTimeout`	Segundos que sonará antes de cancelar si nadie responde. Por defecto: 30 segundos.
`startTimeout`	Segundos que espera el bot antes de empezar a hablar.
`state`	Datos para webhooks o llamadas API durante la llamada, como un ID de cliente.

La API devuelve un callId:

{
  "callId": "xavurimeto"
}

Obtener uso

GET /usage devuelve sesiones telefónicas y de chat de la empresa autenticada y de sus empresas asociadas disponibles.

Sin businessId se incluyen todas las empresas disponibles. Use businessId para seleccionar una empresa y start y end para filtrar por la fecha de creación de la sesión.

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

start y end son inclusivos. Use fechas ISO 8601 que puedan analizarse. Una empresa fuera del alcance del token produce 403 Forbidden.

Ejemplo de respuesta:

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

Listar empresas asociadas

Para integraciones de socios y revendedores, GET /partnerClients devuelve las empresas visibles conectadas con la empresa autenticada. Sus IDs pueden utilizarse como filtro businessId en el endpoint de uso.

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

Ejemplo de respuesta:

[
  {
    "id": "zpjwletodo",
    "name": "Empresa de ejemplo",
    "city": "Madrid",
    "country": "ES"
  }
]

Gestionar archivos de la base de conocimientos y archivos multimedia

Las claves API pueden listar, cargar y eliminar archivos de la empresa asociada al token. Los ID de archivo están ofuscados, pero los nombres de los atributos de respuesta no lo están.

Listar archivos de la base de conocimientos

GET /knowledgeBase devuelve id, name, fileSize y tokens.

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

Cargar un archivo de la base de conocimientos

POST /knowledgeBase acepta una carga multipart con los campos file y name.

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

Eliminar un archivo de la base de conocimientos

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

Listar y cargar archivos multimedia

GET /mediaFiles devuelve id, name y fileSize. POST /mediaFiles utiliza los mismos campos multipart.

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

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

Eliminar un archivo multimedia

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

Especificación OpenAPI

openapi: 3.1.0
info:
  title: VoiceBooker Partner API
  version: 1.0.0
  description: API para consultar empresas asociadas y datos de uso.
servers: [{url: https://voicebooker.de/app/api/v1}]
paths:
  /exportBots/{botId}:
    get:
      summary: Exportar 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: Definición del bot exportado., 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: El bot no pertenece a la empresa del token.}
  /importBots:
    post:
      summary: Importar 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 importado., content: {application/json: {schema: {type: object, properties: {id: {type: string}, name: {type: string}}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /makeCall:
    post:
      summary: Realizar una llamada saliente
      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: Llamada saliente iniciada., content: {application/json: {schema: {type: object, properties: {callId: {type: string}}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /usage:
    get:
      summary: Obtener uso
      operationId: listUsage
      security: [{apiToken: []}]
      parameters:
        - {name: businessId, in: query, schema: {type: string}, description: Empresa que se desea consultar.}
        - {name: start, in: query, schema: {type: string, format: date-time}, description: Inicio inclusivo.}
        - {name: end, in: query, schema: {type: string, format: date-time}, description: Fin inclusivo.}
      responses:
        '200': {description: Registros de uso., content: {application/json: {schema: {type: array, items: {$ref: '#/components/schemas/UsageRecord'}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: La empresa no está disponible para este token.}
  /partnerClients:
    get:
      summary: Listar empresas asociadas
      operationId: listPartnerClients
      security: [{apiToken: []}]
      responses:
        '200': {description: Lista de empresas., 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: El token falta o no es válido.}

Errores HTTP

401 Unauthorized: falta el token API o no es válido.
403 Forbidden: la empresa solicitada no está disponible para el token.

Acceso a la API

En esta página