Acesso à API

O VoiceBooker disponibiliza acesso programático à API para integrar outras aplicações e automatizar fluxos, como obter dados de utilização, implementar bots e integrar pipelines de CI/CD.

URL base

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

Autenticação

Envie um token de API em cada pedido usando um dos seguintes headers:

Authorization: Bearer <o-seu-token-api>

ou:

X-API-Token: <o-seu-token-api>

O token determina a empresa associada ao pedido. Mantenha-o protegido.

Exportar um bot

GET /exportBots/{botId} exporta um bot da empresa associada ao token de API. Use pretty=true para obter HJSON legível ou nt=true para o formato de texto aninhado.

curl --get 'https://voicebooker.de/app/api/v1/exportBots/<bot-id>' \
  --header 'Authorization: Bearer <o-seu-token-api>' \
  --data-urlencode 'pretty=true'

Exemplo de resposta:

{
  "name": "Assistente de receção",
  "id": "kqrmxaveli",
  "stages": [
    {
      "name": "Welcome",
      "id": "mavotirenu",
      "linkId": "qeluzanopi",
      "template": false,
      "prompt": "Cumprimente quem liga.",
      "tools": [],
      "functions": [],
      "settings": {},
      "stageConfig": [],
      "x": 0,
      "y": 0,
      "order": 0,
      "instanceSettings": {}
    }
  ],
  "settings": {},
  "wizard": {}
}

POST /importBots importa uma definição de bot para a empresa associada ao token. Envie a definição em contents. Para HJSON, filename deve terminar em .hjson. overwriteBotStages, overwriteTemplates e replaceBotStages são parâmetros booleanos opcionais.

curl --request POST \
  --url https://voicebooker.de/app/api/v1/importBots \
  --header 'Authorization: Bearer <o-seu-token-api>' \
  --header 'Content-Type: application/json' \
  --data '{"filename":"bot.json","contents":{"name":"Assistente de receção","settings":{},"stages":[]},"overwriteBotStages":false,"overwriteTemplates":false,"replaceBotStages":false}'

Exemplo de resposta:

{
  "id": "vexorimaku",
  "name": "Assistente de receção",
  "settings": {},
  "invisible": false
}

Efetuar chamadas de saída

Para efetuar uma chamada de saída, envie um pedido POST para:

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

Content-Type: application/json
Token: <o-seu-token-api>

Exemplo de pedido:

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

Parâmetro	Descrição
`dest`	Número a chamar no formato E.164.
`botId`	Bot utilizado na chamada.
`sipAccountId`	Conta SIP utilizada; o respetivo número é mostrado ao destinatário.
`ringTimeout`	Segundos durante os quais toca antes de cancelar sem resposta. Predefinição: 30 segundos.
`startTimeout`	Segundos que o bot aguarda antes de começar a falar.
`state`	Dados disponíveis para webhooks ou chamadas API durante a chamada, como um ID de cliente.

A API devolve um callId:

{
  "callId": "xavurimeto"
}

Obter utilização

GET /usage devolve sessões telefónicas e de chat da empresa autenticada e das suas empresas parceiras disponíveis.

Sem businessId, são incluídas todas as empresas disponíveis. Use businessId para selecionar uma empresa e start e end para filtrar pela data de criação da sessão.

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

start e end são inclusivos. Use datas ISO 8601 válidas. Uma empresa fora do âmbito do token resulta em 403 Forbidden.

Exemplo de resposta:

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

Listar empresas parceiras

Para integrações de parceiros e revendedores, GET /partnerClients devolve as empresas visíveis ligadas à empresa autenticada. Os respetivos IDs podem ser usados com o filtro businessId do endpoint de utilização.

curl --request GET \
  --url https://voicebooker.de/app/api/v1/partnerClients \
  --header 'Authorization: Bearer <o-seu-token-api>'

Exemplo de resposta:

[
  {
    "id": "zpjwletodo",
    "name": "Empresa parceira de exemplo",
    "city": "Lisboa",
    "country": "PT"
  }
]

Especificação OpenAPI

openapi: 3.1.0
info:
  title: VoiceBooker Partner API
  version: 1.0.0
  description: API para consultar empresas parceiras e dados de utilização.
servers: [{url: https://voicebooker.de/app/api/v1}]
paths:
  /exportBots/{botId}:
    get:
      summary: Exportar um bot
      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: Definição do 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: O bot não pertence à empresa do token.}
  /importBots:
    post:
      summary: Importar um bot
      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: Bot importado., content: {application/json: {schema: {type: object, properties: {id: {type: string}, name: {type: string}}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /makeCall:
    post:
      summary: Efetuar uma chamada de saída
      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: Chamada de saída iniciada., content: {application/json: {schema: {type: object, properties: {callId: {type: string}}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /usage:
    get:
      summary: Obter utilização
      operationId: listUsage
      security: [{bearerAuth: []}, {apiToken: []}]
      parameters:
        - {name: businessId, in: query, schema: {type: string}, description: Empresa a consultar.}
        - {name: start, in: query, schema: {type: string, format: date-time}, description: Início inclusivo.}
        - {name: end, in: query, schema: {type: string, format: date-time}, description: Fim inclusivo.}
      responses:
        '200': {description: Dados de utilização., content: {application/json: {schema: {type: array, items: {$ref: '#/components/schemas/UsageRecord'}}}}}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: A empresa não está disponível para este token.}
  /partnerClients:
    get:
      summary: Listar empresas parceiras
      operationId: listPartnerClients
      security: [{bearerAuth: []}, {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:
    tokenAuth: {type: apiKey, in: header, name: Token}
    bearerAuth: {type: http, scheme: bearer}
    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: O token está em falta ou é inválido.}

Erros HTTP

401 Unauthorized: o token de API está em falta ou é inválido.
403 Forbidden: a empresa pedida não está disponível para este token.

Acesso à API

Nesta página