# Voxbi PBX Api
v1.0.4+e08a93f90c44264b2f5baf632d512f820f76560d-master · OpenAPI 3.1.0

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

## Servers

- `https://{username}.voxbi.cloud/api/{version}` — Voxbi PBX system

## Authentication

- `SipDevice Auth Username in Query` — API key in query "username"
- `SipDevice Auth Password in Query` — API key in query "password"
- `User Auth Username in Query` — API key in query "username"
- `User Auth Password inQuery` — API key in query "password"
- `User Auth in Basic Header` — HTTP Basic
- `Instance ApiKey in Query` — API key in query "key"
- `Instance ApiKey in Bearer Header` — HTTP Bearer

## Endpoints

### v1

Version 1 of the api

#### GET /calls/new/tapi

Start new call

# 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`

**Auth**: User Auth in Basic Header, User Auth Password inQuery, User Auth Username in Query

**Parameters**:
- `debugAmiTrace` (query, boolean, optional) — Display the debug trace from asterisk manager
- `destination` (query, string, required) — Destination number to dial
- `targets` (query, string, optional) — Target device used to start the call
- `caller_identity` (query, string, optional) — Specify the caller identity of the call
- `autoAnswer` (query, boolean, optional) — Auto Answer the call on the src device (default: false) (overrides default behaviors)
- `forceDialBack` (query, boolean, optional) — Forces the pbx to start a call in DialBack mode (default: false) (overrides default behaviors)
- `anonymous` (query, boolean, optional) — Should the call be anonymous (default: false)

**Responses**:
- `200` — Call Started

#### POST /calls/placemulticast

Start a new multicast announcement

`operationId: 6e149e99cfe620064ade85a87833e56e`

**Auth**: Instance ApiKey in Bearer Header, Instance ApiKey in Query

**Parameters**:
- `debugAmiTrace` (query, boolean, optional) — Display the debug trace from asterisk manager
- `ip` (query, string, required) — IP to send the call to
- `emergency` (query, string, optional) — Should the multicast overwrite a call 0 or 1
- `soundFile` (query, string, optional) — Sound file to play

**Responses**:
- `200` — Call Started
  ```json
  {
      "status": "ok",
      "device": {
          "number": "520"
      },
      "destination": "0035220333000"
  }
  ```

#### POST /calls/hangup

Hangup calls

Hangup calls for a user

`operationId: 922b6cc696972d842daa95040f3217ea`

**Auth**: User Auth in Basic Header, User Auth Password inQuery, User Auth Username in Query

**Parameters**:
- `debugAmiTrace` (query, boolean, optional) — Display the debug trace from asterisk manager

**Request body** (`application/json`) (required):
```json
{
    "channels": [
        "string"
    ]
}
```

**Responses**:
- `400` — Bad Request - Request validation failed
- `200` — Call has been hangup
  ```json
  {
      "hungUpChannles": 1
  }
  ```

#### POST /calls/new

Start new call

# 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`

**Auth**: User Auth in Basic Header, User Auth Password inQuery, User Auth Username in Query

**Parameters**:
- `debugAmiTrace` (query, boolean, optional) — Display the debug trace from asterisk manager
- `autoAnswer` (query, boolean, optional) — Auto Answer the call on the src device (default: false) (overrides default behaviors)
- `forceDialBack` (query, boolean, optional) — Forces the pbx to start a call in DialBack mode (default: false) (overrides default behaviors)
- `anonymous` (query, boolean, optional) — Should the call be anonymous (default: false)

**Request body** (`application/json`) (required):
```json
{
    "targets": {
        "sip_devices": [
            "a469de67-b79a-4dea-87d2-9a15858f10cd"
        ],
        "webrtc": true,
        "twinning": true,
        "teams": true,
        "flipChannel": "Local/905a334f-5bf6-4ebc-85d3-2d5411187f68@C-TW-pbx16dev-00000057;2"
    },
    "destination": "0035220333300",
    "source": "2017",
    "caller_identity": "905a334f-5bf6-4ebc-85d3-2d5411187f68",
    "tts": [
        {
            "tag": "welcome_message",
            "message": "Hello World"
        }
    ],
    "options": {
        "dialed_user_id": "string",
        "dialed_extension_number": "string"
    }
}
```

**Responses**:
- `200` — Call Started
  ```json
  {
      "status": "ok",
      "dialBack": true,
      "destination": "0035220333000",
      "targets": {
          "sip_devices": [
              "a469de67-b79a-4dea-87d2-9a15858f10cd"
          ],
          "webrtc": true,
          "twinning": true,
          "teams": true
      },
      "click2dial_id": "936a90653194073f7ce14f80b067186f68ab32749e1f1b8840d49bf6cd5c9e75"
  }
  ```
- `400` — Bad Request - Request validation failed

#### GET /phoneControl/action

Control your phone

Remotely control your phone

`operationId: e6f3f272e6c5f93b29180bab33eb7435`

**Auth**: User Auth in Basic Header, User Auth Password inQuery, User Auth Username in Query

**Parameters**:
- `debugAmiTrace` (query, boolean, optional) — Display the debug trace from asterisk manager
- `action` (query, enum, required) — Action to be performed · enum: Answer, Reject, Hangup, Hold
- `sip_device_id` (query, uuid, required) — Id of the sip device you want to perform the action from

**Responses**:
- `200` — Action Performed
- `400` — Bad Request - Request validation failed

#### POST /smartIvr/callback

Smart IVR AI callback

Deliver the AI's routing decision for a Smart IVR call

`operationId: d8b351d24ddf74b2ca7c809cd4449a6c`

**Parameters**:
- `token` (query, string, required) — Opaque per-call token issued by SmartIvrSendScript, validated against the channel

**Request body** (`application/json`) (required):
```json
{
    "channel": "string",
    "ivrId": "string",
    "action": "enum",
    "language": "string",
    "destination": {
        "extension": "string"
    }
}
```

**Responses**:
- `400` — Bad Request - Request validation failed
- `200` — Channel redirected
  ```json
  {
      "success": "boolean"
  }
  ```
- `404` — Channel/token invalid, or the call already ended before this callback arrived

### Phone

Actions used by the phones to interact with the PBX

#### GET /phone/enableCallFlow

Toggle /  Enable / Disable a call flow from a phone

Toggle / Enable / Disable a call flow

`operationId: 8576a60b631e3dd6ac5c8fa6e366affe`

**Auth**: SipDevice Auth Username in Query, SipDevice Auth Password in Query

**Parameters**:
- `call_flow_id` (query, string, required) — ID of the call flow to toggle / enable / disable
- `action` (query, enum, required) — Action to perform on the call flow, can be active, inactive or toggle · enum: active, inactive, toggle

**Responses**:
- `200` — Phone reply

#### GET /phone/deployment

Deployment for phone

Main Provisioning for the phones

`operationId: ebec2c42a042342dedf5fafb78be9766`

**Auth**: Instance ApiKey in Bearer Header, Instance ApiKey in Query

**Parameters**:
- `mac` (query, string, required) — MAC of the phone to deploy
- `User-Agent` (header, string, optional) — User agent used to determine the vendor and model of the phone

**Responses**:
- `200` — Phone configuration

#### GET /phone/directory

Get the directory for phones

Get the phone directory

`operationId: 0c41969f4937d103c90ecc062ae6b454`

**Auth**: SipDevice Auth Username in Query, SipDevice Auth Password in Query

**Parameters**:
- `user_id` (query, string, required) — The user ID
- `User-Agent` (header, string, optional) — User agent used to determine the vendor and model of the phone
- `setting` (query, string, optional) — Setting to determine directory or super-search

**Responses**:
- `200` — Phone directory

#### GET /phone/dnd[/{status}]

Enable / Disable DND from a phone

Enable / Disable DND

`operationId: 3a5581b9f4ba2b638427e12eebf548c3`

**Auth**: SipDevice Auth Username in Query, SipDevice Auth Password in Query

**Parameters**:
- `status` (path, enum, optional) — Set the status of the dnd · enum: on, off
- `mac` (query, string, required) — MAC of the phone to deploy
- `user_id` (query, string, required) — Id of the user
- `activeUser` (query, string, required) — Username of the line to activate or deactivate
- `User-Agent` (header, string, optional) — User agent used to determine the vendor and model of the phone

**Responses**:
- `200` — Phone reply

#### GET /phone/forwards

Enable / Disable forwards from a phone

Enable / Disable forwards via a phone or button on a phone linked to the user

`operationId: 669bf838e5778899a1a4439504c5952e`

**Auth**: SipDevice Auth Username in Query, SipDevice Auth Password in Query

**Parameters**:
- `action` (query, enum, required) — Set the status of the forwards · enum: on, off
- `event` (query, enum, required) — For what event we want to check · enum: always, no_answer, busy
- `target` (query, string, required) — Forward Target
- `mac` (query, string, required) — MAC of the phone to deploy
- `user_id` (query, string, required) — Id of the user
- `activeUser` (query, string, required) — Username of the line to activate or deactivate
- `User-Agent` (header, string, optional) — User-Agent used to determine the vendor and the model of the phone

**Responses**:
- `200` — Phone reply
- `400` — Bad request

#### GET /user/forwards

Enable / Disable forwards for a user via a button

Enable / Disable forwards for a user via a button on a phone not linked to the user

`operationId: 6b7394794a383cb59deb14f99fe8f360`

**Auth**: User Auth in Basic Header, User Auth Username in Query, User Auth Password inQuery

**Parameters**:
- `action` (query, enum, required) — Set the status of the forwards · enum: on, off
- `event` (query, enum, required) — For what event we want to check · enum: always, no_answer, busy
- `target` (query, string, required) — Forward Target
- `User-Agent` (header, string, optional) — User-Agent used to determine the vendor and the model of the phone

**Responses**:
- `200` — Phone reply
- `400` — Bad request

#### GET /phone/deployment/gigaset/{key}/{filename}

Deployment for Gigaset

Provisioning endpoint for Gigaset devices

`operationId: 7949a4324eeebcd75d7de46106ae29bd`

**Auth**: Instance ApiKey in Bearer Header, Instance ApiKey in Query

**Parameters**:
- `key` (path, string, required) — Instance API key (path param)
- `filename` (path, string, optional) — gigaset addition for autoprov
- `User-Agent` (header, string, optional) — User agent sent by the device

**Responses**:
- `200` — Gigaset configuration

#### GET /phone/directory/gigaset/{key}

Get the directory for Gigaset devices

Get the shared Gigaset directory (one directory per DECT manager)

`operationId: 83d8ec2e400fefc2e0f812d368623747`

**Auth**: SipDevice Auth Username in Query, SipDevice Auth Password in Query

**Parameters**:
- `User-Agent` (header, string, optional) — User agent used to determine vendor/model (if needed)

**Responses**:
- `200` — Gigaset directory

#### GET /phone/options/info

Class OptionsController

Get debug infos

`operationId: edd0175cecafaf729c1d703bbc71ecae`

**Auth**: SipDevice Auth Username in Query, SipDevice Auth Password in Query

**Parameters**:
- `user_id` (query, string, required) — Id of the user
- `User-Agent` (header, string, optional) — User agent used to determine the vendor and model of the phone

**Responses**:
- `200` — Phone debug info

#### GET /phone/options/sync

Class SyncController

Init config sync

`operationId: 34b4e6e7edce7eec33d6d9eb32cd271f`

**Auth**: SipDevice Auth Username in Query, SipDevice Auth Password in Query

**Parameters**:
- `user_id` (query, string, required) — Id of the user
- `User-Agent` (header, string, optional) — User agent used to determine the vendor and model of the phone

**Responses**:
- `200` — Phone config sync reply

#### GET /phone/options

Get options menu for phones

Get options menu

`operationId: 425ffdc1e11821502efec2e407a9a6bb`

**Auth**: SipDevice Auth Username in Query, SipDevice Auth Password in Query

**Parameters**:
- `user_id` (query, string, required) — Id of the user
- `User-Agent` (header, string, optional) — User agent used to determine the vendor and model of the phone

**Responses**:
- `200` — Phone options menu

### User

Actions to interact with the Users endpoints

#### GET /user

Get user info

Get the all the Phone infos of the currently Authenticated user

`operationId: b6f44695c1d5c7b30fcd3745596deebd`

**Auth**: User Auth in Basic Header, User Auth Password inQuery, User Auth Username in Query

**Responses**:
- `200` — Current user information
  ```json
  {
      "username": "string",
      "pbxInstance": {
          "instanceName": "instance",
          "pbxType": "enum"
      },
      "extensions": [
          {
              "number": "1234",
              "devices": [
                  {
                      "channelType": "PJSIP",
                      "number": "520",
                      "username": "devpbx_520",
                      "password": "foobar123"
                  }
              ]
          }
      ]
  }
  ```

### Server

Actions to interact with the Server endpoints

#### GET /

System status

Health Check

`operationId: d2dd53a682f8da808b9e8701828d0abc`

**Responses**:
- `200` — System Ok
  ```json
  {
      "code": 200,
      "status": "OK",
      "time": "1727690094",
      "debug": "false"
  }
  ```

### cors

cors

#### OPTIONS /*

Cors Options Request

Cors Preflight Request

`operationId: de6d6ad5b2687449b4798d2e23df1644`

**Responses**:
- `200` — Successful Options request for CORS