openapi: 3.1.0
info:
  title: 'Voxbi PBX Api'
  description: |-
    Voxbi PBX Web Api. This API is used to communicate with the VOXBI PBX.  
    ## Functions:
    - Phone Interactions (Deployment and Status changes) 
    - Call actions : Control Calls remotely
    - Phone Control : Control Phones remotely

    ## Currently supported phone vendors for web api:
    - Phone Interactions : Yealink 
    - Phone Control : Yealink

    System Version: 1.0.4+e08a93f90c44264b2f5baf632d512f820f76560d-master | Module: PBX - Web [1.0.4+e08a93f90c44264b2f5baf632d512f820f76560d-master] | Framework: 1.0.0
  termsOfService: 'https://www.mixvoip.com/legal'
  contact:
    name: 'PBX support team'
    email: voice.pbx@mixvoip.com
  version: 1.0.4+e08a93f90c44264b2f5baf632d512f820f76560d-master
servers:
  -
    url: 'https://{username}.voxbi.cloud/api/{version}'
    description: 'Voxbi PBX system'
    variables:
      username:
        default: ''
        description: 'Voxbi instance name under which you pbx runs (provided by mixvoip)'
      version:
        enum:
          - v1
        default: v1
        description: 'The API version'
paths:
  '/*':
    options:
      tags:
        - cors
      summary: 'Cors Options Request'
      description: 'Cors Preflight Request'
      operationId: de6d6ad5b2687449b4798d2e23df1644
      responses:
        200:
          description: 'Successful Options request for CORS'
          headers:
            Access-Control-Allow-Origin:
              description: 'Provided Origin header'
              schema:
                type: string
            Access-Control-Allow-Methods:
              description: 'Allowed methods'
              schema:
                type: string
            Access-Control-Allow-Headers:
              description: 'Allowed Headers'
              schema:
                type: string
            Access-Control-Max-Age:
              description: 'Max age of the cors request'
              schema:
                type: string
  /calls/new/tapi:
    get:
      tags:
        - v1
        - Calls
      summary: 'Start new call'
      description: |
        # Start a new call to a destination from a User using the [xtelsio Tapi](https://www.xtelsio.com/en/products/ast_tsp/tapi_for_asterisk.htm)
        DialBack mode: we dial first the targets and once one of those has answered we dial the destination. This allows the user to select which device will be used to start a new call  
        When no targets are specified we dial all linked device for the user in DialBack mode.  
        When only one target.sip_devices (and no other targets) is specified we try to start the call via the Phone api if this fails we dial the device
        When the target is webrtc and we only have one instance of voxbi open we don't use DialBack mode
      operationId: 44f6fee3183e37cb70610ac7dffe83ae
      parameters:
        -
          $ref: '#/components/parameters/DebugAmiTrace'
        -
          name: destination
          in: query
          description: 'Destination number to dial'
          required: true
          allowEmptyValue: false
          schema:
            type: string
          example: '20333300'
        -
          name: targets
          in: query
          description: 'Target device used to start the call'
          required: false
          allowEmptyValue: false
          schema:
            type: string
          example: 'a469de67-b79a-4dea-87d2-9a15858f10cd,webrtc,twinning,teams'
        -
          name: caller_identity
          in: query
          description: 'Specify the caller identity of the call'
          required: false
          allowEmptyValue: false
          schema:
            type: string
          example: 905a334f-5bf6-4ebc-85d3-2d5411187f68
        -
          name: autoAnswer
          in: query
          description: 'Auto Answer the call on the src device (default: false) (overrides default behaviors)'
          required: false
          allowEmptyValue: false
          schema:
            type: boolean
          example: 'false'
        -
          name: forceDialBack
          in: query
          description: 'Forces the pbx to start a call in DialBack mode (default: false) (overrides default behaviors)'
          required: false
          allowEmptyValue: false
          schema:
            type: boolean
          example: 'false'
        -
          name: anonymous
          in: query
          description: 'Should the call be anonymous (default: false)'
          required: false
          allowEmptyValue: false
          schema:
            type: boolean
          example: 'false'
      responses:
        200:
          description: 'Call Started'
      security:
        -
          'User Auth in Basic Header': {}
        -
          'User Auth Password inQuery': {}
        -
          'User Auth Username in Query': {}
  /calls/placemulticast:
    post:
      tags:
        - v1
        - calls
      summary: 'Start a new multicast announcement'
      description: 'Start a new multicast announcement'
      operationId: 6e149e99cfe620064ade85a87833e56e
      parameters:
        -
          $ref: '#/components/parameters/DebugAmiTrace'
        -
          name: ip
          in: query
          description: 'IP to send the call to'
          required: true
          allowEmptyValue: false
          schema:
            type: string
          example: 'false'
        -
          name: emergency
          in: query
          description: 'Should the multicast overwrite a call 0 or 1'
          required: false
          allowEmptyValue: false
          schema:
            type: string
          example: '0'
        -
          name: soundFile
          in: query
          description: 'Sound file to play'
          required: false
          allowEmptyValue: false
          schema:
            type: string
          example: all-your-base
      responses:
        200:
          description: 'Call Started'
          content:
            application/json:
              schema:
                properties:
                  status:
                    description: 'Status of the call'
                    type: string
                    enum:
                      - ok
                    example: ok
                  device:
                    description: 'Src Device'
                    properties:
                      number:
                        description: 'Device Number'
                        type: string
                        example: '520'
                    type: object
                  destination:
                    description: 'Destination to Call'
                    type: string
                    example: '0035220333000'
                type: object
      security:
        -
          'Instance ApiKey in Bearer Header': {}
        -
          'Instance ApiKey in Query': {}
  /calls/hangup:
    post:
      tags:
        - v1
        - calls
      summary: 'Hangup calls'
      description: 'Hangup calls for a user'
      operationId: 922b6cc696972d842daa95040f3217ea
      parameters:
        -
          $ref: '#/components/parameters/DebugAmiTrace'
      requestBody:
        description: 'Channel to hangup'
        required: true
        content:
          application/json:
            schema:
              required:
                - channels
              properties:
                channels:
                  description: 'Channels to hangup'
                  type: array
                  items:
                    description: 'Channel Name'
                    type: string
              type: object
      responses:
        400:
          description: 'Bad Request - Request validation failed'
        200:
          description: 'Call has been hangup'
          content:
            application/json:
              schema:
                properties:
                  hungUpChannles:
                    description: 'Amount of hangup channels'
                    type: integer
                    example: 1
                type: object
      security:
        -
          'User Auth in Basic Header': {}
        -
          'User Auth Password inQuery': {}
        -
          'User Auth Username in Query': {}
  /calls/new:
    post:
      tags:
        - v1
        - Calls
      summary: 'Start new call'
      description: |
        # Start a new call to a destination from a User or Device
        DialBack mode: we dial first the targets and once one of those has answered we dial the destination. This allows the user to select which device will be used to start a new call  
        When no targets are specified we dial all linked device for the user in DialBack mode.  
        When the source parameter is defined we dial the source number in dial back mode and ignore all the other targets.  
        When only one target.sip_devices (and no other targets) is specified we try to start the call via the Phone api if this fails we dial the device
      operationId: 0feab11b168cc4e35d7725ce6c93701b
      parameters:
        -
          $ref: '#/components/parameters/DebugAmiTrace'
        -
          name: autoAnswer
          in: query
          description: 'Auto Answer the call on the src device (default: false) (overrides default behaviors)'
          required: false
          allowEmptyValue: false
          schema:
            type: boolean
          example: 'false'
        -
          name: forceDialBack
          in: query
          description: 'Forces the pbx to start a call in DialBack mode (default: false) (overrides default behaviors)'
          required: false
          allowEmptyValue: false
          schema:
            type: boolean
          example: 'false'
        -
          name: anonymous
          in: query
          description: 'Should the call be anonymous (default: false)'
          required: false
          allowEmptyValue: false
          schema:
            type: boolean
          example: 'false'
      requestBody:
        description: 'Call to start'
        required: true
        content:
          application/json:
            schema:
              required:
                - destination
              properties:
                targets:
                  description: |-
                    Which targets to start the call from  
                                        - if multiple targets are specified we call each target in dial back mode
                  properties:
                    sip_devices:
                      description: |-
                        Src Device id's
                                            - if multiple devices are specified we call each device in DialBack mode  
                                            - if only one device is specified and if the pbx can reach the device we instrukt the device to start a call  
                                            - if the device is not accessible via the pbx we send a call to the device in DialBack mode
                      type: array
                      items:
                        description: sip_device.id
                        type: uuid
                        minItems: 1
                        example: a469de67-b79a-4dea-87d2-9a15858f10cd
                    webrtc:
                      description: 'Include the webrtc devices (Voxbi Web)'
                      type: boolean
                      enum:
                        - true
                        - false
                      example: true
                    twinning:
                      description: 'Include the twinning devices'
                      type: boolean
                      enum:
                        - true
                        - false
                      example: true
                    teams:
                      description: 'Include the teams devices'
                      type: boolean
                      enum:
                        - true
                        - false
                      example: true
                    flipChannel:
                      description: 'Specify which channel to flip, When the flipChannel is defined we always use the DialBack mode'
                      type: string
                      example: Local/905a334f-5bf6-4ebc-85d3-2d5411187f68@C-TW-pbx16dev-00000057;2
                  type: object
                destination:
                  description: |-
                    Destination to Call.  
                                        - Allowed characters are 0-9 and + or * at the first position or a UUID of a user or ### (flip call)  
                                        - If the starts with * we try to perform a pickup of the extension or the UUID of the user  
                                        - If the destination is ### (flip call) you can add the flipChannel Parameter
                  type: string
                  example: '0035220333300'
                source:
                  description: |-
                    Specify the source number of the call (optional, forces dial back mode and ignores all `targets`)  
                                        When the source parameter is defined we first dial the source number and then when the number answered the call we dial the destination.  
                                        - Allowed characters are 0-9 and + or a UUID of a user  
                                        - When using tts this parameter defines the where we route the call to once the `destination` answered the call
                  type: string
                  example: '2017'
                caller_identity:
                  description: 'Specify the caller identity of the call'
                  type: string
                  example: 905a334f-5bf6-4ebc-85d3-2d5411187f68
                tts:
                  description: |-
                    Text to speach messages to play.  
                                        - When the tts is defined and the `source` we go to the `source` and execute the call flow attached to it after the `destination` answered the call  
                                        - When the tts is defined but no `source` is defined we play the tts messages to the `destination` and then we hangup the call
                  type: array
                  items:
                    description: 'Text to speach message with tag'
                    required:
                      - tag
                      - message
                    properties:
                      tag:
                        type: string
                        example: welcome_message
                      message:
                        type: string
                        example: 'Hello World'
                    type: object
                  minItems: 1
                options:
                  description: 'Additional options for the call (tts only)'
                  properties:
                    dialed_user_id:
                      description: 'Set the User UUID for dynamic dialing (Overwrites `dialed_extension_number`)'
                      type: string
                    dialed_extension_number:
                      description: 'Set the Extension number for dynamic dialing'
                      type: string
                  type: object
              type: object
      responses:
        200:
          description: 'Call Started'
          content:
            application/json:
              schema:
                properties:
                  status:
                    description: 'Status of the call'
                    type: string
                    enum:
                      - ok
                    example: ok
                  dialBack:
                    description: 'Did we used the dialBack Method to place the call'
                    type: boolean
                    enum:
                      - true
                      - false
                    example: true
                  destination:
                    description: 'Destination to Call'
                    type: string
                    example: '0035220333000'
                  targets:
                    description: 'Targets the pbx tried to DialBack to'
                    properties:
                      sip_devices:
                        description: 'Dialed SipDevices'
                        type: array
                        items:
                          description: sip_device.id
                          type: uuid
                          minItems: 1
                          example: a469de67-b79a-4dea-87d2-9a15858f10cd
                      webrtc:
                        description: 'Did we dialed the webrtc devices (Voxbi Web)'
                        type: boolean
                        enum:
                          - true
                          - false
                        example: true
                      twinning:
                        description: 'Did we dialed the twinning devices'
                        type: boolean
                        enum:
                          - true
                          - false
                        example: true
                      teams:
                        description: 'Did we dialed the teams devices'
                        type: boolean
                        enum:
                          - true
                          - false
                        example: true
                    type: object
                  click2dial_id:
                    description: 'Click2Dial Call ID'
                    type: string
                    example: 936a90653194073f7ce14f80b067186f68ab32749e1f1b8840d49bf6cd5c9e75
                type: object
        400:
          description: 'Bad Request - Request validation failed'
      security:
        -
          'User Auth in Basic Header': {}
        -
          'User Auth Password inQuery': {}
        -
          'User Auth Username in Query': {}
  /:
    get:
      tags:
        - Server
      summary: 'System status'
      description: 'Health Check'
      operationId: d2dd53a682f8da808b9e8701828d0abc
      responses:
        200:
          description: 'System Ok'
          content:
            application/json:
              schema:
                description: 'Health of the server'
                properties:
                  code:
                    type: Integer
                    example: 200
                  status:
                    type: String
                    example: OK
                  time:
                    description: 'Server Time'
                    type: Integer
                    example: '1727690094'
                  debug:
                    description: 'Is debug enabled'
                    type: Boolean
                    example: 'false'
                type: object
  /phone/enableCallFlow:
    get:
      tags:
        - Phone
        - v1
      summary: 'Toggle /  Enable / Disable a call flow from a phone'
      description: 'Toggle / Enable / Disable a call flow'
      operationId: 8576a60b631e3dd6ac5c8fa6e366affe
      parameters:
        -
          parameter: call_flow_id
          name: call_flow_id
          in: query
          description: 'ID of the call flow to toggle / enable / disable'
          required: true
          schema:
            type: string
            example: 00000000-1111-2222-3333-444444444444
        -
          parameter: action
          name: action
          in: query
          description: 'Action to perform on the call flow, can be active, inactive or toggle'
          required: true
          schema:
            type: string
            enum:
              - active
              - inactive
              - toggle
      responses:
        200:
          description: 'Phone reply'
      security:
        -
          'SipDevice Auth Username in Query': {}
        -
          'SipDevice Auth Password in Query': {}
  /phone/deployment:
    get:
      tags:
        - Phone
        - v1
      summary: 'Deployment for phone'
      description: 'Main Provisioning for the phones'
      operationId: ebec2c42a042342dedf5fafb78be9766
      parameters:
        -
          parameter: mac
          name: mac
          in: query
          description: 'MAC of the phone to deploy'
          required: true
          schema:
            type: string
            example: AABBCCDDEEFF
        -
          parameter: User-Agent
          name: User-Agent
          in: header
          description: 'User agent used to determine the vendor and model of the phone'
          required: false
          schema:
            type: string
            example: 'Yealink SIP-T53 XX.XX.YY.ZZ AA:BB:CC:DD:EE:FF'
      responses:
        200:
          description: 'Phone configuration'
      security:
        -
          'Instance ApiKey in Bearer Header': {}
        -
          'Instance ApiKey in Query': {}
  /phone/directory:
    get:
      tags:
        - Phone
        - v1
      summary: 'Get the directory for phones'
      description: 'Get the phone directory'
      operationId: 0c41969f4937d103c90ecc062ae6b454
      parameters:
        -
          parameter: user_id
          name: user_id
          in: query
          description: 'The user ID'
          required: true
          schema:
            type: string
            example: abcd1234
        -
          parameter: User-Agent
          name: User-Agent
          in: header
          description: 'User agent used to determine the vendor and model of the phone'
          required: false
          example:
            schema: DirectoryController
            type: string
            example: 'Yealink SIP-T53 XX.XX.YY.ZZ AA:BB:CC:DD:EE:FF'
        -
          parameter: setting
          name: setting
          in: query
          description: 'Setting to determine directory or super-search'
          required: false
          schema:
            type: string
            example: directory
      responses:
        200:
          description: 'Phone directory'
      security:
        -
          'SipDevice Auth Username in Query': {}
        -
          'SipDevice Auth Password in Query': {}
  '/phone/dnd[/{status}]':
    get:
      tags:
        - Phone
        - v1
      summary: 'Enable / Disable DND from a phone'
      description: 'Enable / Disable DND'
      operationId: 3a5581b9f4ba2b638427e12eebf548c3
      parameters:
        -
          parameter: status
          name: status
          in: path
          description: 'Set the status of the dnd'
          required: false
          schema:
            type: string
            enum:
              - 'on'
              - 'off'
        -
          parameter: mac
          name: mac
          in: query
          description: 'MAC of the phone to deploy'
          required: true
          schema:
            type: string
            example: AABBCCDDEEFF
        -
          parameter: user_id
          name: user_id
          in: query
          description: 'Id of the user'
          required: true
          schema:
            type: string
            example: '123'
        -
          parameter: activeUser
          name: activeUser
          in: query
          description: 'Username of the line to activate or deactivate'
          required: true
          schema:
            type: string
            example: '<instance>_<user.id>_<calleridentity.id>'
        -
          parameter: User-Agent
          name: User-Agent
          in: header
          description: 'User agent used to determine the vendor and model of the phone'
          required: false
          schema:
            type: string
            example: 'Yealink SIP-T53 XX.XX.YY.ZZ AA:BB:CC:DD:EE:FF'
      responses:
        200:
          description: 'Phone reply'
      security:
        -
          'SipDevice Auth Username in Query': {}
        -
          'SipDevice Auth Password in Query': {}
  /phone/forwards:
    get:
      tags:
        - Phone
        - v1
      summary: 'Enable / Disable forwards from a phone'
      description: 'Enable / Disable forwards via a phone or button on a phone linked to the user'
      operationId: 669bf838e5778899a1a4439504c5952e
      parameters:
        -
          parameter: action
          name: action
          in: query
          description: 'Set the status of the forwards'
          required: true
          schema:
            type: string
            enum:
              - 'on'
              - 'off'
        -
          parameter: event
          name: event
          in: query
          description: 'For what event we want to check'
          required: true
          schema:
            type: string
            enum:
              - always
              - no_answer
              - busy
        -
          parameter: target
          name: target
          in: query
          description: 'Forward Target'
          required: true
          schema:
            type: string
            example: '20333000'
        -
          parameter: mac
          name: mac
          in: query
          description: 'MAC of the phone to deploy'
          required: true
          schema:
            type: string
            example: AABBCCDDEEFF
        -
          parameter: user_id
          name: user_id
          in: query
          description: 'Id of the user'
          required: true
          schema:
            type: string
            example: '123'
        -
          parameter: activeUser
          name: activeUser
          in: query
          description: 'Username of the line to activate or deactivate'
          required: true
          schema:
            type: string
            example: '<instance>_<user.id>_<calleridentity.id>'
        -
          parameter: User-Agent
          name: User-Agent
          in: header
          description: 'User-Agent used to determine the vendor and the model of the phone'
          required: false
          schema:
            type: string
            example: 'Yealink SIP-T53 XX.XX.YY.ZZ AA:BB:CC:DD:EE:FF'
      responses:
        200:
          description: 'Phone reply'
        400:
          description: 'Bad request'
      security:
        -
          'SipDevice Auth Username in Query': {}
        -
          'SipDevice Auth Password in Query': {}
  /user/forwards:
    get:
      tags:
        - Phone
        - v1
      summary: 'Enable / Disable forwards for a user via a button'
      description: 'Enable / Disable forwards for a user via a button on a phone not linked to the user'
      operationId: 6b7394794a383cb59deb14f99fe8f360
      parameters:
        -
          parameter: action
          name: action
          in: query
          description: 'Set the status of the forwards'
          required: true
          schema:
            type: string
            enum:
              - 'on'
              - 'off'
        -
          parameter: event
          name: event
          in: query
          description: 'For what event we want to check'
          required: true
          schema:
            type: string
            enum:
              - always
              - no_answer
              - busy
        -
          parameter: target
          name: target
          in: query
          description: 'Forward Target'
          required: true
          schema:
            type: string
            example: '20333000'
        -
          parameter: User-Agent
          name: User-Agent
          in: header
          description: 'User-Agent used to determine the vendor and the model of the phone'
          required: false
          schema:
            type: string
            example: 'Yealink SIP-T53 XX.XX.YY.ZZ AA:BB:CC:DD:EE:FF'
      responses:
        200:
          description: 'Phone reply'
        400:
          description: 'Bad request'
      security:
        -
          'User Auth in Basic Header': {}
        -
          'User Auth Username in Query': {}
        -
          'User Auth Password inQuery': {}
  '/phone/deployment/gigaset/{key}/{filename}':
    get:
      tags:
        - Phone
        - v1
      summary: 'Deployment for Gigaset'
      description: 'Provisioning endpoint for Gigaset devices'
      operationId: 7949a4324eeebcd75d7de46106ae29bd
      parameters:
        -
          parameter: key
          name: key
          in: path
          description: 'Instance API key (path param)'
          required: true
          schema:
            type: string
            example: pbx16dev-...
        -
          parameter: filename
          name: filename
          in: path
          description: 'gigaset addition for autoprov'
          required: false
          schema:
            type: string
            example: provisioning.xml
        -
          parameter: User-Agent
          name: User-Agent
          in: header
          description: 'User agent sent by the device'
          required: false
          schema:
            type: string
            example: 'Gigaset N870 IP PRO/83.V2.57.0...;589EC65D1E59;Handset=50'
      responses:
        200:
          description: 'Gigaset configuration'
      security:
        -
          'Instance ApiKey in Bearer Header': {}
        -
          'Instance ApiKey in Query': {}
  '/phone/directory/gigaset/{key}':
    get:
      tags:
        - Phone
        - v1
      summary: 'Get the directory for Gigaset devices'
      description: 'Get the shared Gigaset directory (one directory per DECT manager)'
      operationId: 83d8ec2e400fefc2e0f812d368623747
      parameters:
        -
          parameter: User-Agent
          name: User-Agent
          in: header
          description: 'User agent used to determine vendor/model (if needed)'
          required: false
          schema:
            type: string
            example: 'Gigaset N870 IP PRO ...'
      responses:
        200:
          description: 'Gigaset directory'
      security:
        -
          'SipDevice Auth Username in Query': {}
        -
          'SipDevice Auth Password in Query': {}
  /phone/options/info:
    get:
      tags:
        - Phone
        - v1
      summary: 'Class OptionsController'
      description: 'Get debug infos'
      operationId: edd0175cecafaf729c1d703bbc71ecae
      parameters:
        -
          parameter: user_id
          name: user_id
          in: query
          description: 'Id of the user'
          required: true
          schema:
            type: string
            example: '123'
        -
          parameter: User-Agent
          name: User-Agent
          in: header
          description: 'User agent used to determine the vendor and model of the phone'
          required: false
          schema:
            type: string
            example: 'Yealink SIP-T53 XX.XX.YY.ZZ AA:BB:CC:DD:EE:FF'
      responses:
        200:
          description: 'Phone debug info'
      security:
        -
          'SipDevice Auth Username in Query': {}
        -
          'SipDevice Auth Password in Query': {}
  /phone/options/sync:
    get:
      tags:
        - Phone
        - v1
      summary: 'Class SyncController'
      description: 'Init config sync'
      operationId: 34b4e6e7edce7eec33d6d9eb32cd271f
      parameters:
        -
          parameter: user_id
          name: user_id
          in: query
          description: 'Id of the user'
          required: true
          schema:
            type: string
            example: '123'
        -
          parameter: User-Agent
          name: User-Agent
          in: header
          description: 'User agent used to determine the vendor and model of the phone'
          required: false
          schema:
            type: string
            example: 'Yealink SIP-T53 XX.XX.YY.ZZ AA:BB:CC:DD:EE:FF'
      responses:
        200:
          description: 'Phone config sync reply'
      security:
        -
          'SipDevice Auth Username in Query': {}
        -
          'SipDevice Auth Password in Query': {}
  /phone/options:
    get:
      tags:
        - Phone
        - v1
      summary: 'Get options menu for phones'
      description: 'Get options menu'
      operationId: 425ffdc1e11821502efec2e407a9a6bb
      parameters:
        -
          parameter: user_id
          name: user_id
          in: query
          description: 'Id of the user'
          required: true
          schema:
            type: string
            example: '123'
        -
          parameter: User-Agent
          name: User-Agent
          in: header
          description: 'User agent used to determine the vendor and model of the phone'
          required: false
          schema:
            type: string
            example: 'Yealink SIP-T53 XX.XX.YY.ZZ AA:BB:CC:DD:EE:FF'
      responses:
        200:
          description: 'Phone options menu'
      security:
        -
          'SipDevice Auth Username in Query': {}
        -
          'SipDevice Auth Password in Query': {}
  /phoneControl/action:
    get:
      tags:
        - v1
        - phoneControl
      summary: 'Control your phone'
      description: 'Remotely control your phone'
      operationId: e6f3f272e6c5f93b29180bab33eb7435
      parameters:
        -
          $ref: '#/components/parameters/DebugAmiTrace'
        -
          name: action
          in: query
          description: 'Action to be performed'
          required: true
          allowEmptyValue: false
          schema:
            type: enum
            enum:
              - Answer
              - Reject
              - Hangup
              - Hold
          example: 'false'
        -
          name: sip_device_id
          in: query
          description: 'Id of the sip device you want to perform the action from'
          required: true
          allowEmptyValue: false
          schema:
            type: uuid
            example: a469de67-b79a-4dea-87d2-9a15858f10cd
      responses:
        200:
          description: 'Action Performed'
        400:
          description: 'Bad Request - Request validation failed'
      security:
        -
          'User Auth in Basic Header': {}
        -
          'User Auth Password inQuery': {}
        -
          'User Auth Username in Query': {}
  /smartIvr/callback:
    post:
      tags:
        - v1
        - smartIvr
      summary: 'Smart IVR AI callback'
      description: "Deliver the AI's routing decision for a Smart IVR call"
      operationId: d8b351d24ddf74b2ca7c809cd4449a6c
      parameters:
        -
          name: token
          in: query
          description: 'Opaque per-call token issued by SmartIvrSendScript, validated against the channel'
          required: true
          schema:
            type: string
      requestBody:
        description: 'Routing decision for the channel'
        required: true
        content:
          application/json:
            schema:
              required:
                - channel
                - ivrId
                - action
              properties:
                channel:
                  description: 'Asterisk channel name'
                  type: string
                ivrId:
                  description: 'IVR the call originated from'
                  type: string
                action:
                  description: 'transfer or hangup'
                  type: string
                  enum:
                    - transfer
                    - hangup
                language:
                  description: 'AI-identified language, used only if none was detected earlier'
                  type: string
                destination:
                  description: 'Required when action=transfer'
                  properties:
                    extension:
                      description: 'Extension/number to route to via INCOMING-{instance}, same as a normally dialed extension'
                      type: string
                  type: object
              type: object
      responses:
        400:
          description: 'Bad Request - Request validation failed'
        200:
          description: 'Channel redirected'
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                type: object
        404:
          description: 'Channel/token invalid, or the call already ended before this callback arrived'
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                type: object
  /user:
    get:
      tags:
        - User
        - v1
      summary: 'Get user info'
      description: 'Get the all the Phone infos of the currently Authenticated user'
      operationId: b6f44695c1d5c7b30fcd3745596deebd
      responses:
        200:
          description: 'Current user information'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      security:
        -
          'User Auth in Basic Header': {}
        -
          'User Auth Password inQuery': {}
        -
          'User Auth Username in Query': {}
components:
  schemas:
    Device:
      description: 'Phone Device'
      properties:
        channelType:
          description: 'Channel type is the device using'
          type: string
          enum:
            - PJSIP
            - EXTINT
            - SIP
          example: PJSIP
        number:
          description: 'The number of the device which can be dialed'
          type: string
          example: '520'
        username:
          description: 'Register username'
          type: string
          example: devpbx_520
        password:
          description: 'Register Password'
          type: string
          example: foobar123
      type: object
    Extension:
      description: Extension
      properties:
        number:
          description: 'Number of the extension'
          type: string
          example: '1234'
        devices:
          description: 'Devices linked to the extension'
          type: array
          items:
            $ref: '#/components/schemas/Device'
      type: object
    PbxInstance:
      description: 'Instance of the Pbx'
      properties:
        instanceName:
          description: 'Instance name (Normally this is your Mixvoip account name)'
          type: string
          example: instance
        pbxType:
          description: 'What Pbx type is it'
          type: string
          enum:
            - VoxbiPBX
            - MixPBX
      type: object
    User:
      description: User
      properties:
        username:
          description: Username
          type: string
        pbxInstance:
          $ref: '#/components/schemas/PbxInstance'
          description: 'Instance Linked to the user'
        extensions:
          description: 'Extensions Linked to the user'
          type: array
          items:
            $ref: '#/components/schemas/Extension'
      type: object
  responses: {}
  parameters:
    DebugAmiTrace:
      name: debugAmiTrace
      in: query
      description: 'Display the debug trace from asterisk manager'
      required: false
      allowEmptyValue: false
      schema:
        type: boolean
      example: 'true'
  securitySchemes:
    'SipDevice Auth Username in Query':
      type: apiKey
      description: 'Authenticate using a the credentials of a sip device'
      name: username
      in: query
    'SipDevice Auth Password in Query':
      type: apiKey
      description: 'Authenticate using a the credentials of a sip device'
      name: password
      in: query
    'User Auth Username in Query':
      type: apiKey
      description: |-
        Authenticate using a User account (Pbx.instance_name_User.id (example: `pbx20dev_7e6ba1ad-4c3c-43a6-a4b7-8c50e13e730d`) is the username and password is sha256 of user.password or user.webrtc_password)
        Alternative for HTTP Basic Auth username for clients who don\'t support Headers'
      name: username
      in: query
    'User Auth Password inQuery':
      type: apiKey
      description: |-
        Authenticate using a User account (Pbx.instance_name_User.id (example: `pbx20dev_7e6ba1ad-4c3c-43a6-a4b7-8c50e13e730d`) is the username and password is sha256 of user.password or user.webrtc_password)
        Alternative for HTTP Basic Auth password for clients who don\'t support Headers'
      name: password
      in: query
    'User Auth in Basic Header':
      type: http
      description: 'Authenticate using a User account (Pbx.instance_name_User.id (example: `pbx20dev_7e6ba1ad-4c3c-43a6-a4b7-8c50e13e730d`) is the username and password is sha256 of user.password or user.webrtc_password)'
      scheme: basic
    'Instance ApiKey in Query':
      type: apiKey
      description: |-
        Authenticate using the Users global api key in Query
        - When using a Voxbi pbx this is md5(instanceApiKey)
        - Not supported for MIXpbx
      name: key
      in: query
    'Instance ApiKey in Bearer Header':
      type: http
      description: |-
        Authenticate using the Users global api key in Header'
        - When using a Voxbi pbx this is md5(instanceApiKey)
        - Not supported for MIXpbx
      scheme: Bearer
tags:
  -
    name: v1
    description: 'Version 1 of the api'
  -
    name: Phone
    description: 'Actions used by the phones to interact with the PBX'
  -
    name: Calls
    description: 'Actions to handle Calls'
  -
    name: User
    description: 'Actions to interact with the Users endpoints'
  -
    name: Server
    description: 'Actions to interact with the Server endpoints'
  -
    name: cors
    description: cors
  -
    name: calls
    description: calls
  -
    name: phoneControl
    description: phoneControl
  -
    name: smartIvr
    description: smartIvr
webhooks:
  'Call flow step webhook':
    summary: 'Call flow step webhook'
    description: |-
      The Voxbi PBX supports calling a Web hook during a call flow via the web hook call flow step.  
      The Web hook send a POST request with a JSON body as payload.
    path: 'Call flow step webhook'
    post:
      summary: 'Call flow step webhook'
      description: |-
        The Voxbi PBX supports calling a Web hook during a call flow via the web hook call flow step.  
        The Web hook send a POST request with a JSON body as payload.
      operationId: 855b7c03c2b29ca48a3a9c697d1ff2b4
      requestBody:
        content:
          application/json:
            schema:
              properties:
                instance_name:
                  description: 'Name of the pbx instance'
                  type: string
                  example: myCoolPbx1234
                recording:
                  description: 'Information about the recording'
                  properties:
                    src:
                      description: 'Source number used in the recording file'
                      type: string
                      example: '+3522033332017'
                    dst:
                      description: 'Destination number used in the recording file'
                      type: string
                      example: '+35220602700'
                    files:
                      description: 'Recording files information'
                      properties:
                        combined:
                          description: 'Path to the recordings file with the combined audio'
                          type: string
                          example: /mnt/hdd/recordings/spool/myCoolPbx1234_CF_8a274b6e-d50b-4abd-ad18-fc153898841c_1751009487.68.wav
                        receive:
                          description: 'Path to the recordings file with the audio received by the PBX'
                          type: string
                          example: /mnt/hdd/recordings/spool/myCoolPbx1234_CF_8a274b6e-d50b-4abd-ad18-fc153898841c_1751009487.68.RX.wav
                        transmit:
                          description: 'Path to the recordings file with the audio send by the PBX'
                          type: string
                          example: /mnt/hdd/recordings/spool/myCoolPbx1234_CF_8a274b6e-d50b-4abd-ad18-fc153898841c_1751009487.68.TX.wav
                      type: object
                  type: object
                call:
                  description: 'Information about the call'
                  properties:
                    id:
                      description: 'ID of the call'
                      type: string
                    type:
                      description: 'Type of this call (external the call originated for a external source | Internal: the call has been started from a authorized user)'
                      type: string
                      example: external
                    direction:
                      description: 'Direction of the call (incoming or outgoing)'
                      type: string
                      example: incoming
                    detected_language:
                      description: 'Detected language of the call (if languge detection ran)'
                      type: string
                      example: en
                    detected_language_confidence:
                      description: 'Confidence of the detected language (if languge detection ran)'
                      type: string
                      example: '0.99'
                    detected_language_attempts:
                      description: 'Number of attempts to detect the language (if languge detection ran)'
                      type: string
                      example: '1'
                  type: object
                channel:
                  description: 'Information about the current channel'
                  properties:
                    id:
                      description: 'ID of the channel'
                      type: string
                    name:
                      description: 'Name of the channel'
                      type: string
                  type: object
                routing:
                  description: 'Information about the routing'
                  properties:
                    is_vip:
                      description: 'This variable is set to TRUE when the call has been marked as a VIP call'
                      type: string
                      example: 'TRUE'
                    via_number:
                      description: 'Number which was used to route the call'
                      type: string
                      example: '1234'
                    via_name:
                      description: 'Name which was used to route the call'
                      type: string
                      example: 'Test 1234'
                    callflow_id:
                      description: 'UUID of the callflow where the web hook has been triggered'
                      type: string
                      example: 8a274b6e-d50b-4abd-ad18-fc153898841c
                    callflow_name:
                      description: 'Name of the callflow where the web hook has been triggered'
                      type: string
                      example: 'Default Call Flow External'
                  type: object
                user:
                  description: 'Information about the user where the call has been routed to'
                  properties:
                    dialed_user_id:
                      description: 'User ID of the dialed user'
                      type: string
                      example: 8a274b6e-ffff-ffff-ad18-fc153898841c
                    dialed_exten:
                      description: 'Dialed Extension Number'
                      type: string
                      example: '1234'
                    dialed_exten_id:
                      description: 'Dialed Extension Id'
                      type: string
                      example: 8a274b6e-cccc-cccc-ad18-fc153898841c
                  type: object
                caller_id:
                  description: 'Information about the caller id set on the call'
                  properties:
                    name:
                      description: 'Caller ID name of the incoming call'
                      type: string
                      example: 'LAURES Christophe'
                    number:
                      description: 'Caller ID number of the incoming call (How we got it form the Source)'
                      type: string
                      example: '+3522033332017'
                    number_international:
                      description: 'Caller ID number of the incoming call (Formatted to +E.164)'
                      type: string
                      example: '+3522033332017'
                    international_prefix:
                      description: 'International Prefix guessed by the PBX'
                      type: string
                      example: '352'
                  type: object
                queue:
                  description: 'Information set after a Queue was executed'
                  properties:
                    id:
                      description: 'ID of the Queue'
                      type: string
                      example: 54374fbc-8a38-4712-b832-97b86bde5e4a
                    name:
                      description: 'Name of the Queue'
                      type: string
                      example: 'Demo Q'
                    exit_key:
                      description: 'This variable is set when the Call left a Queue because the Caller pressed a Exit Key'
                      type: string
                      example: '5'
                    status:
                      description: 'Why the user left the Queue'
                      type: string
                      example: TIMEOUT
                    position:
                      description: 'Position which the user was when he left the queue'
                      type: string
                      example: '1'
                    abandoned:
                      description: 'When set to TRUE the call has not been answered in the queue'
                      type: string
                      example: 'TRUE'
                  type: object
                ivr:
                  description: 'Information set after a IVR was executed'
                  properties:
                    id:
                      description: 'ID of the IVR'
                      type: string
                      example: 54374fbc-8a38-4712-b832-97b86bde5e4a
                    name:
                      description: 'Name of the IVR'
                      type: string
                      example: 'Demo IVR'
                    step:
                      description: 'Selected step of the IVR'
                      properties:
                        id:
                          description: 'ID of the IVR Step'
                          type: string
                          example: 54374fbc-8a38-4712-b832-97b86bde5e4a
                        option:
                          description: 'Selected option of the IVR Step'
                          type: string
                          enum:
                            - '0'
                            - '1'
                            - '2'
                            - '3'
                            - '4'
                            - '5'
                            - '6'
                            - '7'
                            - '8'
                            - '9'
                            - '*'
                            - '#'
                            - timeout
                            - default
                          example: '1'
                      type: object
                  type: object
              type: object
      responses:
        200:
          description: |-
            Your Reply to the PBX  
            💡 The json and all keys inside the json are optional (The system also accepts empty responses)
          content:
            application/json:
              schema:
                properties:
                  hangup:
                    description: 'When true hangup the call (default: false)'
                    type: boolean
                    example: false
                  vip:
                    description: 'When true mark the call is a VIP call (default: false)'
                    type: boolean
                    example: true
                  caller_id:
                    description: 'Set the caller id of the call'
                    properties:
                      number:
                        description: 'Overwrite the caller id number'
                        type: string
                        example: '+35220333300'
                      name:
                        description: 'Overwrite the caller id name'
                        type: string
                        example: 'My Company'
                    type: object
                  queue_priority:
                    description: 'If set we set the Queue Priority to the specified number. This can be used to prioritise calls in the Queues'
                    type: integer
                    example: 10
                  via:
                    description: 'Change the via header'
                    properties:
                      number:
                        description: 'Overwrite the via number'
                        type: string
                      name:
                        description: 'Overwrite the via name'
                        type: string
                      overwrite:
                        description: 'Overwrite instead of appending the via header (Default false)'
                        type: boolean
                        example: true
                    type: object
                  transfer:
                    description: 'Transfer the call to a other destination (Work in progress)'
                    properties:
                      destination:
                        description: 'Destination to transfer the call to'
                        type: string
                        example: '+35220333300'
                      type:
                        description: |-
                          Type of the transfer
                          - number: Transfer to a number or extension
                          - sip: Transfer to a sip URI
                          - call_flow: Transfer to a call flow (UUID of the call flow)
                          - user: Transfer to a user (UUID of the user)
                          - sip_device: Transfer to a sip device (UUID of the sip device)
                        enum:
                          - number
                          - sip
                          - call_flow
                          - user
                          - sip_device
                        example: number
                      caller_identity_id:
                        description: 'Caller Identity UUID used during the transfer (Optional)'
                        type: UUID
                        example: 8a274b6e-cccc-cccc-ad18-fc153898841c
                      carrier_id:
                        description: 'Carrier UUID used during the transfer (Optional)'
                        type: UUID
                        example: 8a274b6e-cccc-cccc-ad18-fc153898841c
                      timeout:
                        description: 'Timeout in seconds for the transfer (Optional, Default 300)'
                        type: integer
                        example: 300
                    type: object
                  volume:
                    description: 'Change the volume gain of the call'
                    properties:
                      tx:
                        description: 'Transmit volume gain of the call'
                        type: integer
                        example: 2
                      rx:
                        description: 'Receive volume gain of the call'
                        type: integer
                        example: 2
                    type: object
                type: object
