Compass

https://www.pbx.speakup-telecom.com/docs/
Admin
Compass is a telephony platform providing REST and XMPP APIs for managing calls, users, queues,...
Tokens:22,717
Snippets:240
Trust Score:4.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Get Queue Information

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Send a GET request to retrieve queue details. Requires the target phone service and a unique request ID.

```xml
<iq xmlns="jabber:client" to="phone.uc.pbx.speakup-telecom.com" type="get" id="78fb8fa8-3dbd-47eb-8b11-9c81521a9464:lisa">
    <request xmlns="http://iperity.com/compass" type="GET">
        <filter type="queue" />
    </request>
</iq>
```

```xml
<iq xmlns="jabber:client" from="phone.uc.pbx.speakup-telecom.com" to="testuser@uc.pbx.speakup-telecom.com/LisaApi_BplUI0bnYj" type="result" id="78fb8fa8-3dbd-47eb-8b11-9c81521a9464:lisa">
    <result xmlns="http://iperity.com/compass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="getResult">
        <queue id="1442896">
            <name>My Queue</name>
            <userEntries>
                <entry>
                    <queueId>1442896</queueId>
                    <userId>8323556</userId>
                    <priority>10</priority>
                </entry>
            </userEntries>
            <callIds />
        </queue>
    </result>
</iq>
```

--------------------------------

### Get Company

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Requests company information from the XMPP server.

```APIDOC
## Get Company

### Description
This operation retrieves company details using an XMPP IQ stanza.

### Method
Send XMPP IQ stanza.

### Request Example
```xml
<iq xmlns="jabber:client" to="phone.uc.pbx.speakup-telecom.com" type="get" id="24f9da6b-5a48-4199-b308-5eeb0a0fbf7e:lisa">
    <request xmlns="http://iperity.com/compass" type="GET_COMPANY" />
</iq>
```

### Response
#### Success Response (200)
Returns an IQ result stanza containing company information.

#### Response Example
```xml
<iq xmlns="jabber:client" from="phone.uc.pbx.speakup-telecom.com" to="testuser@uc.pbx.speakup-telecom.com/LisaApi_BplUI0bnYj" type="result" id="24f9da6b-5a48-4199-b308-5eeb0a0fbf7e:lisa">
    <result xmlns="http://iperity.com/compass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="getCompanyResult">
        <id>8323166</id>
        <name>My Company Name</name>
    </result>
</iq>
```
```

--------------------------------

### Get User Information

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Send a GET request to retrieve user details. Requires the target phone service and a unique request ID.

```xml
<iq xmlns="jabber:client" to="phone.uc.pbx.speakup-telecom.com" type="get" id="16b35ce3-4276-466a-9072-112fe43c249c:lisa">
    <request xmlns="http://iperity.com/compass" type="GET">
        <filter type="user" />
    </request>
</iq>
```

```xml
<iq xmlns="jabber:client" from="phone.uc.pbx.speakup-telecom.com" to="testuser@uc.pbx.speakup-telecom.com/LisaApi_BplUI0bnYj" type="result" id="16b35ce3-4276-466a-9072-112fe43c249c:lisa">
    <result xmlns="http://iperity.com/compass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="getResult">
        <user id="8323556">
            <identifiers>
                <lisaId>8323556</lisaId>
                <xmppJid>testuser@uc.pbx.speakup-telecom.com</xmppJid>
                <compassId>test</compassId>
            </identifiers>
            <queueEntries>
                <entry>
                    <queueId>1442896</queueId>
                    <userId>8323556</userId>
                    <priority>10</priority>
                </entry>
                <entry>
                    <queueId>1761056</queueId>
                    <userId>8323556</userId>
                    <priority>10</priority>
                </entry>
            </queueEntries>
            <name>Test User</name>
            <loggedIn>true</loggedIn>
            <location>1442646</location>
            <language>nl</language>
            <contact>test@iperity.com</contact>
            <extensions>200</extensions>
        </user>
    </result>
</iq>
```

--------------------------------

### Get Users Response

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

The server responds with a list of user elements. Each user object contains identifiers, queue entries, name, login status, location, and other details.

```xml
<iq from="phone.pbx.speakup-telecom.com" id="2833:lisa" to="user@uc.pbx.speakup-telecom.com/resource" type="result" xmlns="jabber:client">
    <result xmlns="http://iperity.com/compass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="getResult">
        <user id="105">
            <identifiers>
                <lisaId>105</lisaId>
                <xmppJid>testuser@domain.nl</xmppJid>
                <compassId>testuser</compassId>
            </identifiers>
            <queueEntries/>
            <name>Test User</name>
            <loggedIn>false</loggedIn>
            <location>-1</location>
            <shortname/>
            <language>nl</language>
            <contact/>
            <extensions/>
        </user>
        <user id="16">
            <identifiers>
                <lisaId>16</lisaId>
                <xmppJid>othertestuser@domain.nl</xmppJid>
                <compassId>Other Test User</compassId>
            </identifiers>
            <queueEntries>
                <entry>
                    <queueId>641</queueId>
                    <userId>16</userId>
                    <priority>10</priority>
                </entry>
                <entry>
                    <queueId>663</queueId>
                    <userId>16</userId>
                    <priority>10</priority>
                </entry>
                <entry>
                    <queueId>665</queueId>
                    <userId>16</userId>
                    <priority>10</priority>
                </entry>
            </queueEntries>
            <name>Test User</name>
            <loggedIn>false</loggedIn>
            <location>776</location>
            <shortname/>
            <language>en</language>
            <contact>testuser@testdomain.com</contact>
            <extensions>222</extensions>
        </user>
    </result>
</iq>
```

--------------------------------

### Retrieve User Information via REST API (JavaScript)

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Use jQuery's AJAX to fetch user details. This example requires the jQuery library and assumes a modern browser environment where btoa is available.

```javascript
var username = "my-username";
var password = "my-password";

$.ajax({
        type: "GET",
        url: "https://rest.pbx.speakup-telecom.com/user",
        headers: {
            "Authorization": "Basic " + btoa(username + ":" + password),
            "X-No-Redirect": true,
            "Accept": "application/vnd.iperity.compass.v3+json"
        },
    })
    .done(function(data) {
        alert("Hello there, " + data.name);
    });

```

--------------------------------

### Get Queue

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Retrieves queue information from the PBX system. This operation allows fetching details about queues and their associated user entries.

```APIDOC
## Get Queue

### Description
Retrieves queue information from the PBX system.

### Method
GET

### Endpoint
`/queues` (Implicit, based on filter type)

### Parameters
#### Request Body
- **filter** (object) - Required - Specifies the type of filter, e.g., `{ "type": "queue" }`

### Request Example
```xml
<iq xmlns="jabber:client" to="phone.uc.pbx.speakup-telecom.com" type="get" id="78fb8fa8-3dbd-47eb-8b11-9c81521a9464:lisa">
    <request xmlns="http://iperity.com/compass" type="GET">
        <filter type="queue" />
    </request>
</iq>
```

### Response
#### Success Response (200)
- **queue** (object) - Contains queue details including id, name, userEntries, and callIds.

#### Response Example
```xml
<iq xmlns="jabber:client" from="phone.uc.pbx.speakup-telecom.com" to="testuser@uc.pbx.speakup-telecom.com/LisaApi_BplUI0bnYj" type="result" id="78fb8fa8-3dbd-47eb-8b11-9c81521a9464:lisa">
    <result xmlns="http://iperity.com/compass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="getResult">
        <queue id="1442896">
            <name>My Queue</name>
            <userEntries>
                <entry>
                    <queueId>1442896</queueId>
                    <userId>8323556</userId>
                    <priority>10</priority>
                </entry>
            </userEntries>
            <callIds />
        </queue>
    </result>
</iq>
```
```

--------------------------------

### Example Pubsub Message for Incoming Call

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

This XML message format is received when an incoming call event occurs. It details the source and destination of the call, along with its state.

```xml
<message xmlns="jabber:client" from="pubsub.uc.pbx.speakup-telecom.com" to="testuser@uc.pbx.speakup-telecom.com/LisaApi_BplUI0bnYj" type="headline">
    <event xmlns="http://jabber.org/protocol/pubsub#event">
        <items node="8323266">
            <item id="5D4AC4DA3888">
                <notification xmlns="http://iperity.com/compass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" timestamp="1492705754" type="notification.call.start" xsi:type="callStartNotification">
                    <call id="IKhDw.MuTOkUTDa8nEV-6dd.c133ada042758fa0b92a6ed8621bd224.0">
                        <source id="8093725" type="External" xsi:type="callpointExternal">
                            <timeCreated>1492705754</timeCreated>
                            <properties />
                            <number>31614241111</number>
                            <name>31614241111</name>
                            <state>CONNECTING</state>
                        </source>
                        <destination id="8093726" type="Dialplan" xsi:type="callpointDialplan">
                            <timeCreated>1492705754</timeCreated>
                            <properties />
                            <exten>31413231111</exten>
                            <state>CONNECTING</state>
                        </destination>
                        <state>CONNECTING</state>
                        <properties />
                    </call>
                </notification>
            </item>
        </items>
    </event>
    <headers xmlns="http://jabber.org/protocol/shim">
        <header name="Collection">8323266</header>
    </headers>
</message>
```

--------------------------------

### Queue Data Model Example

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Represents a waiting queue for calls, including its ID, name, associated users, and waiting call IDs. The 'id' attribute uniquely identifies the queue.

```xml
<queue id="641">
    <name>Queue 1</name>
    <userEntries>
        <entry>
            <queueId>641</queueId>
            <userId>16</userId>
            <priority>10</priority>
        </entry>
    </userEntries>
    <callIds>
        <id>528638e0d5ee-m9u68m629b7.bf9fd24cbe10dd80439bc413.0</id>
    </callIds>
    <xmppJid>queue-641</xmppJid>
</queue>
```

--------------------------------

### Example Call Structure

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

This XML structure represents a call with source and destination callpoints, their states, and additional properties. Calls with a DISCONNECTED state are no longer active.

```xml
<call id="30680e334948d50e0ae355db5bae6a05316e5438/1">
    <source id="192" type="User" xsi:type="callpointUser">
        <timeCreated>1384535809</timeCreated>
        <properties/>
        <userId>17</userId>
        <userName>Jan Jansen</userName>
        <identityId>73</identityId>
        <state>CONNECTING</state>
    </source>
    <destination id="194" type="User" xsi:type="callpointUser">
        <timeCreated>1384535809</timeCreated>
        <properties/>
        <userId>16</userId>
        <userName>Alex Groot</userName>
        <identityId>74</identityId>
        <state>CONNECTING</state>
    </destination>
    <state>CONNECTING</state>
    <properties>
        <QueueCallForCall>
            30680e334948d50e0ae355db5bae6a05316e5438
        </QueueCallForCall>
    </properties>
</call>
```

--------------------------------

### Handle HTTPS Redirects

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

If a request is made over HTTP, the API returns a redirect to the secure HTTPS URL. This example shows the redirect response.

```http
GET /user/100 HTTP/1.1
Host: rest.pbx.speakup-telecom.com
Accept: application/vnd.iperity.compass.v3+json

>> HTTP/1.1 308 Permanent Redirect
>> Location: https://rest.pbx.speakup-telecom.com/user/
```

--------------------------------

### Get Calls

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Retrieves call information from the PBX system. This operation allows fetching details about active calls.

```APIDOC
## Get Calls

### Description
Retrieves call information from the PBX system.

### Method
GET

### Endpoint
`/calls` (Implicit, based on filter type)

### Parameters
#### Request Body
- **filter** (object) - Required - Specifies the type of filter, e.g., `{ "type": "call" }`

### Request Example
```xml
<iq xmlns="jabber:client" to="phone.uc.pbx.speakup-telecom.com" type="get" id="a5f7f827-e585-42cc-bd29-d05f66c2e406:lisa">
    <request xmlns="http://iperity.com/compass" type="GET">
        <filter type="call" />
    </request>
</iq>
```

### Response
#### Success Response (200)
- **result** (object) - An empty object indicating success if no calls are active, or containing call details if calls are present.

#### Response Example
```xml
<iq xmlns="jabber:client" from="phone.uc.pbx.speakup-telecom.com" to="testuser@uc.pbx.speakup-telecom.com/LisaApi_BplUI0bnYj" type="result" id="a5f7f827-e585-42cc-bd29-d05f66c2e406:lisa">
    <result xmlns="http://iperity.com/compass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="getResult" />
</iq>
```
```

--------------------------------

### User Data Model Example

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Represents a user on the platform, including identifiers, login status, and queue memberships. The 'id' attribute is the primary identifier, equivalent to 'userId' in queue-related elements.

```xml
<user id="883" xmlns="http://iperity.com/compass">
    <identifiers>
        <lisaId>883</lisaId>
        <xmppJid>alex@domain.nl</xmppJid>
        <compassId>alex</compassId>
    </identifiers>
    <queueEntries>
        <entry>
            <queueId>2</queueId>
            <userId>883</userId>
            <priority>10</priority>
        </entry>
    </queueEntries>

    <name>Alex Groot</name>
    <loggedIn>false</loggedIn>
    <address>Straat 123</address>
    <contact>alex@groot.nl</contact>
    <extensions>333</extensions>
</user>
```

--------------------------------

### Get User

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Retrieves user information from the PBX system. This operation allows fetching details about a specific user based on provided filters.

```APIDOC
## Get User

### Description
Retrieves user information from the PBX system.

### Method
GET

### Endpoint
`/users` (Implicit, based on filter type)

### Parameters
#### Request Body
- **filter** (object) - Required - Specifies the type of filter, e.g., `{ "type": "user" }`

### Request Example
```xml
<iq xmlns="jabber:client" to="phone.uc.pbx.speakup-telecom.com" type="get" id="16b35ce3-4276-466a-9072-112fe43c249c:lisa">
    <request xmlns="http://iperity.com/compass" type="GET">
        <filter type="user" />
    </request>
</iq>
```

### Response
#### Success Response (200)
- **user** (object) - Contains user details including id, identifiers, queueEntries, name, loggedIn, location, language, contact, and extensions.

#### Response Example
```xml
<iq xmlns="jabber:client" from="phone.uc.pbx.speakup-telecom.com" to="testuser@uc.pbx.speakup-telecom.com/LisaApi_BplUI0bnYj" type="result" id="16b35ce3-4276-466a-9072-112fe43c249c:lisa">
    <result xmlns="http://iperity.com/compass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="getResult">
        <user id="8323556">
            <identifiers>
                <lisaId>8323556</lisaId>
                <xmppJid>testuser@uc.pbx.speakup-telecom.com</xmppJid>
                <compassId>test</compassId>
            </identifiers>
            <queueEntries>
                <entry>
                    <queueId>1442896</queueId>
                    <userId>8323556</userId>
                    <priority>10</priority>
                </entry>
                <entry>
                    <queueId>1761056</queueId>
                    <userId>8323556</userId>
                    <priority>10</priority>
                </entry>
            </queueEntries>
            <name>Test User</name>
            <loggedIn>true</loggedIn>
            <location>1442646</location>
            <language>nl</language>
            <contact>test@iperity.com</contact>
            <extensions>200</extensions>
        </user>
    </result>
</iq>
```
```

--------------------------------

### Get Call Information

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Send a GET request to retrieve call details. Requires the target phone service and a unique request ID.

```xml
<iq xmlns="jabber:client" to="phone.uc.pbx.speakup-telecom.com" type="get" id="a5f7f827-e585-42cc-bd29-d05f66c2e406:lisa">
    <request xmlns="http://iperity.com/compass" type="GET">
        <filter type="call" />
    </request>
</iq>
```

```xml
<iq xmlns="jabber:client" from="phone.uc.pbx.speakup-telecom.com" to="testuser@uc.pbx.speakup-telecom.com/LisaApi_BplUI0bnYj" type="result" id="a5f7f827-e585-42cc-bd29-d05f66c2e406:lisa">
    <result xmlns="http://iperity.com/compass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="getResult" />
</iq>
```

--------------------------------

### XMPP Get Company Request

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

This XML demonstrates a request to retrieve company information using the Compass XMPP extension.

```xml
<iq xmlns="jabber:client" to="phone.uc.pbx.speakup-telecom.com" type="get" id="24f9da6b-5a48-4199-b308-5eeb0a0fbf7e:lisa">
    <request xmlns="http://iperity.com/compass" type="GET_COMPANY" />
</iq>
```

--------------------------------

### Get Company Request

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Send this IQ request to retrieve company information. Ensure a unique value is used for the 'id' attribute.

```xml
<iq id="9055:lisa" to="phone.uc.pbx.speakup-telecom.com" type="get" xmlns="jabber:client">
    <request type="GET_COMPANY" xmlns="http://iperity.com/compass"/>
</iq>
```

--------------------------------

### Get Users Request

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Retrieve a list of users by setting the filter type to 'user'. This request can be used after obtaining the company name.

```xml
<iq id="2833:lisa" to="phone.uc.pbx.speakup-telecom.com" type="get" xmlns="jabber:client">
    <request type="GET" xmlns="http://iperity.com/compass">
        <filter type="user"/>
    </request>
</iq>
```

--------------------------------

### XMPP Get Company Response

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

This XML shows the result of a 'GET_COMPANY' request, returning company ID and name.

```xml
<iq xmlns="jabber:client" from="phone.uc.pbx.speakup-telecom.com" to="testuser@uc.pbx.speakup-telecom.com/LisaApi_BplUI0bnYj" type="result" id="24f9da6b-5a48-4199-b308-5eeb0a0fbf7e:lisa">
    <result xmlns="http://iperity.com/compass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="getCompanyResult">
        <id>8323166</id>
        <name>My Company Name</name>
    </result>
</iq>
```

--------------------------------

### Retrieve User Information via REST API (PHP)

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Perform a GET request to retrieve user information using cURL in PHP. Ensure proper error handling for the request.

```php
$username = 'my-username';
$password = 'my-password';

ch = curl_init('https://rest.pbx.speakup-telecom.com/user');

url_setopt($ch, CURLOPT_USERPWD, "$username:$password");
url_setopt($ch, CURLOPT_RETURNTRANSFER, true);
url_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
url_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Accept: application/vnd.iperity.compass.v3+json'
));

$res = curl_exec($ch);

if ($res === false) {
    echo 'Request failed: '. curl_error($ch);
    exit(1);
}

$user = json_decode($res);

echo "You are {$user->name} ";
echo "with email address {$user->contact}.\n";
echo "Requests can be performed on URL {$user->self}.\n\n";
echo "Your user data is: \n";
print_r($user);

```

--------------------------------

### Get Lists of Objects (Users, Queues, Calls)

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Retrieve lists of users, queues, or calls. The type of list to retrieve is specified by the `type` attribute of the `filter` element. Optionally, `history` can be set to `true` for call history.

```APIDOC
## GET /lists

### Description
Retrieves a list of objects (users, queues, or calls). The type of object to retrieve is specified by the `type` attribute within the `filter` element. For calls, setting `history` to `true` will include past calls.

### Method
GET

### Endpoint
`/lists`

### Parameters
#### Query Parameters
- **type** (string) - Required - Specifies the type of list to retrieve. Accepted values: `user`, `queue`, `call`.
- **history** (boolean) - Optional - If set to `true` and `type` is `call`, returns past and ongoing calls.

### Request Example
```xml
<iq id="2833:lisa" to="phone.uc.pbx.speakup-telecom.com" type="get" xmlns="jabber:client">
    <request type="GET" xmlns="http://iperity.com/compass">
        <filter type="user"/>
    </request>
</iq>
```

### Response
#### Success Response (200)
- **result** (object) - Contains a list of the requested objects (e.g., `user`, `queue`, `call`).

#### Response Example (Users)
```xml
<iq from="phone.pbx.speakup-telecom.com" id="2833:lisa" to="user@uc.pbx.speakup-telecom.com/resource" type="result" xmlns="jabber:client">
    <result xmlns="http://iperity.com/compass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="getResult">
        <user id="105">
            <identifiers>
                <lisaId>105</lisaId>
                <xmppJid>testuser@domain.nl</xmppJid>
                <compassId>testuser</compassId>
            </identifiers>
            <queueEntries/>
            <name>Test User</name>
            <loggedIn>false</loggedIn>
            <location>-1</location>
            <shortname/>
            <language>nl</language>
            <contact/>
            <extensions/>
        </user>
        </result>
</iq>
```
```

--------------------------------

### GET Request

Source: https://www.pbx.speakup-telecom.com/docs/xsd/requests.xsd

Represents a generic GET request. It can be used to retrieve various types of data based on the specified filter.

```APIDOC
## GET Request

### Description
This endpoint is used for general data retrieval. It requires a filter to specify what data to fetch.

### Method
GET

### Endpoint
/request

### Parameters
#### Query Parameters
- **type** (string) - Required - Specifies the type of request, e.g., 'GET'.
- **company** (string) - Optional - Identifier for the company context.

#### Request Body
- **filter** (object) - Required - Defines the filtering criteria for the request.
  - **type** (string) - Required - The type of entity to filter by (e.g., 'company', 'user', 'queue', 'call', 'callpoint').
  - **id** (string) - Optional - The specific ID of the entity to filter.
```

--------------------------------

### Connect to XMPP

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Details on how to establish a connection to the Compass XMPP API.

```APIDOC
## XMPP Connection Details

### Description
Establishes a connection to the Compass telephony platform via XMPP for real-time events and monitoring.

### Hostname
`uc.pbx.speakup-telecom.com`

### Port
`5222` (Standard XMPP port)

### Security
Clients are required to use stream negotiation to encrypt the stream using TLS.

### Web Clients
- **WebSockets**: `wss://bosh.pbx.speakup-telecom.com/ws`
- **BOSH**: `https://bosh.pbx.speakup-telecom.com/http-bind`

### Notes
It is recommended to use available XMPP software libraries rather than implementing a client from scratch.
```

--------------------------------

### Compass REST Interface - Using the API

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Details on how to interact with the Compass REST API, including request formats, security, authentication, and versioning.

```APIDOC
## Using the API

### Request Format
- `GET` requests consist of a URL and optional query parameters.
- `PATCH` and `POST` requests have bodies encoded as JSON.

### Security
All REST requests are available via HTTPS only.

### Authentication
All REST requests require HTTP basic authentication over HTTPS. Unauthenticated requests will result in a `401 Not authorized` response.

### Versioning
API versioning is managed via the `Accept` and `Content-type` HTTP headers.
- The `Accept` header should be in the format: `application/vnd.iperity.compass.<api-version-number>+json`.
- Clients must include a valid `Accept` header.
- The negotiated API version can be determined from the `Content-type` header returned by the server.
- Non-breaking changes (e.g., adding endpoints or properties) do not necessarily result in a new API version.
```

--------------------------------

### Get Authenticated User

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Retrieves the resource URL for the authenticated user.

```APIDOC
## GET /user

### Description
Retrieves the resource URL for the authenticated user.

### Method
GET

### Endpoint
/user

### Response
#### Success Response (303 See Other)
- **Location** (string) - URL to the authenticated user's resource.
```

--------------------------------

### GET_COMPANY Request

Source: https://www.pbx.speakup-telecom.com/docs/xsd/requests.xsd

Specifically retrieves company information. This is a specialized GET request.

```APIDOC
## GET_COMPANY Request

### Description
This endpoint is used to retrieve detailed information about a specific company. It requires a filter to identify the company.

### Method
GET

### Endpoint
/request

### Parameters
#### Query Parameters
- **type** (string) - Required - Must be 'GET_COMPANY'.
- **company** (string) - Optional - Identifier for the company context.

#### Request Body
- **filter** (object) - Required - Defines the filtering criteria for the request.
  - **type** (string) - Required - Must be 'company'.
  - **id** (string) - Optional - The ID of the company to retrieve.
```

--------------------------------

### Bootstrap URL's

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Special URLs to discover the authenticated user's resource and company resource.

```APIDOC
## Bootstrap URL's

For a client to discover references to the authenticated user’s resource URL and to the authenticated user’s company resource URL, two special URL’s can be used:

* `https://rest.pbx.speakup-telecom.com/user` will respond with `303 See other` and a `Location` header specifying a URL to the authenticated user’s resource.
* `https://rest.pbx.speakup-telecom.com/company` will respond with `303 See other` and a `Location` header specifying a URL to the authenticated user’s company resource.
```

--------------------------------

### Get Company Response

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

The API response includes a unique ID and name for the company.

```xml
<iq from="phone.pbx.speakup-telecom.com" id="9055:lisa" to="user@uc.pbx.speakup-telecom.com/resource" type="result" xmlns="jabber:client">
    <result xmlns="http://iperity.com/compass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="getCompanyResult">
        <id>15</id>
        <name>companyname</name>
    </result>
</iq>
```

--------------------------------

### Get User Information (REST)

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Retrieves additional information about the authenticated user via the REST interface.

```APIDOC
## GET /user

### Description
Retrieves additional information about the authenticated user.

### Method
GET

### Endpoint
/user

### Headers
- **X-No-Redirect** (boolean) - Optional - If true, prevents automatic redirection.
- **Accept** (string) - Required - Specifies the desired response format, e.g., `application/vnd.iperity.compass.v3+json`.

### Request Example
```http
GET /user HTTP/1.1
X-No-Redirect: true
Accept: application/vnd.iperity.compass.v3+json
Host: rest.pbx.speakup-telecom.com
```

### Response
#### Success Response (200)
- **name** (string) - The user's name.
- **contact** (string) - The user's contact information (e.g., email).
- **self** (string) - A URL to the user's resource.

#### Response Example
```json
{
  "name": "John Doe",
  "contact": "john.doe@example.com",
  "self": "https://rest.pbx.speakup-telecom.com/user"
}
```
```

--------------------------------

### Get Company Information

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Retrieve the unique ID and name of the company. A unique value should be used for the `id` attribute in the request.

```APIDOC
## GET /company

### Description
Retrieves the unique ID and name of the company.

### Method
GET

### Endpoint
`/company`

### Request Example
```xml
<iq id="9055:lisa" to="phone.uc.pbx.speakup-telecom.com" type="get" xmlns="jabber:client">
    <request type="GET_COMPANY" xmlns="http://iperity.com/compass"/>
</iq>
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the company.
- **name** (string) - The name of the company.

#### Response Example
```xml
<iq from="phone.pbx.speakup-telecom.com" id="9055:lisa" to="user@uc.pbx.speakup-telecom.com/resource" type="result" xmlns="jabber:client">
    <result xmlns="http://iperity.com/compass" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="getCompanyResult">
        <id>15</id>
        <name>companyname</name>
    </result>
</iq>
```
```

--------------------------------

### Verify XMPP Server SRV Records with dig

Source: https://www.pbx.speakup-telecom.com/docs/user-admin-manual.html

Use the 'dig' command to verify the SRV records for XMPP server connections. This confirms that your DNS is correctly configured for XMPP federation.

```bash
$ dig SRV +noall +answer _xmpp-server._tcp.example-domain.ext
_xmpp-server._tcp.example-domain.ext.  7200 IN SRV 100 33 5269 xmpp3.pbx.speakup-telecom.com.
_xmpp-server._tcp.example-domain.ext.  7200 IN SRV 100 33 5269 xmpp1.pbx.speakup-telecom.com.
_xmpp-server._tcp.example-domain.ext.  7200 IN SRV 100 33 5269 xmpp2.pbx.speakup-telecom.com.

```

--------------------------------

### Add User to Queue

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Uses a POST request to add a user to a specified queue. The request includes the queue URL, priority, and call forwarding status.

```http
POST /user/100/loginQueue HTTP/1.1
Accept: application/vnd.iperity.compass.v3+json
Host: rest.pbx.speakup-telecom.com

{
    "queue" : "https://rest.pbx.speakup-telecom.com/queue/270",
    "priority" : "2",
    "callForward" : false
}

>> HTTP/1.1 200 OK
>> Content-Length: 0
```

--------------------------------

### Add User to Queue

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Adds a user to a specified queue with priority and call forwarding options.

```APIDOC
## POST /user/{id}/loginQueue

### Description
Adds a user to a specified queue with priority and call forwarding options.

### Method
POST

### Endpoint
/user/{id}/loginQueue

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the user.

#### Request Body
- **queue** (string) - Required - The absolute URL of the queue to join.
- **priority** (string) - Required - The priority level for the user in the queue.
- **callForward** (boolean) - Required - Whether call forwarding is enabled for this user in the queue.
```

--------------------------------

### Retrieve User Details

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Fetches detailed information for a specific user using their resource URL. The response includes user properties like username and extensions.

```http
GET /user/100 HTTP/1.1
Accept: application/vnd.iperity.compass.v3+json
Host: rest.pbx.speakup-telecom.com

>> HTTP/1.1 200 OK
>> Content-Type: application/vnd.iperity.compass.v3+json

>> {
>>  "username" => "testuser",
>>  "extensions" => [ 201, 202 ],
>>  ...
>> }
```

--------------------------------

### Pubsub Subscription Request

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Subscribe to the company node to receive notifications about platform state changes. The `jid` and `node` attributes should be replaced with appropriate values.

```APIDOC
## POST /pubsub/subscribe

### Description
Subscribes to the company node to receive real-time notifications regarding platform state changes. The `jid` should be the client's JID, and the `node` should be the company ID obtained from a `GET_COMPANY` request.

### Method
SET (XMPP type)

### Endpoint
`pubsub.uc.pbx.speakup-telecom.com` (Target JID for Pubsub)

### Parameters
#### Request Body (XMPP IQ)
- **id** (string) - Required - A unique value to identify the response.
- **to** (string) - Required - The JID of the pubsub service.
- **type** (string) - Required - Set to `set` for subscription requests.
- **pubsub** (object) - Required - Contains the pubsub protocol elements.
    - **subscribe** (object) - Required - Contains subscription details.
        - **jid** (string) - Required - The JID of the client subscribing.
        - **node** (string) - Required - The node to subscribe to (e.g., company ID).

### Request Example
```xml
<iq id="8597:pubsub" to="pubsub.uc.pbx.speakup-telecom.com" type="set" xmlns="jabber:client">
    <pubsub xmlns="http://jabber.org/protocol/pubsub">
        <subscribe jid="user@uc.pbx.speakup-telecom.com/resource" node="15"/>
    </pubsub>
</iq>
```

### Response
#### Success Response (200)
- The server responds with a result indicating the success or failure of the subscription.

#### Response Example
(Response structure depends on XMPP Pubsub specification for subscription results.)
```

--------------------------------

### Get Authenticated User Resource URL

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Requests to the /user endpoint return a 303 See Other status with a Location header pointing to the authenticated user's resource URL.

```http
GET /user HTTP/1.1
Accept: application/vnd.iperity.compass.v3+json
Host: rest.pbx.speakup-telecom.com

>> HTTP/1.1 303 See Other
>> Location: https://rest.pbx.speakup-telecom.com/user/
```

--------------------------------

### Verify XMPP Client SRV Records with dig

Source: https://www.pbx.speakup-telecom.com/docs/user-admin-manual.html

Use the 'dig' command to verify the SRV records for XMPP client connections. This ensures that XMPP clients can correctly connect to your domain's servers.

```bash
$ dig SRV +noall +answer _xmpp-client._tcp.example-domain.ext
_xmpp-client._tcp.example-domain.ext.  7200 IN SRV 100 33 5222 xmpp3.pbx.speakup-telecom.com.
_xmpp-client._tcp.example-domain.ext.  7200 IN SRV 100 33 5222 xmpp1.pbx.speakup-telecom.com.
_xmpp-client._tcp.example-domain.ext.  7200 IN SRV 100 33 5222 xmpp2.pbx.speakup-telecom.com.

```

--------------------------------

### Pubsub Subscribe Request and Response

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

Subscribe to a pubsub node to receive events. The initial request sends a subscribe command, and the response includes a pending subscription status followed by a subscribed event.

```xml
-- Sent:
<iq xmlns="jabber:client" to="pubsub.uc.pbx.speakup-telecom.com" type="set" id="2dab0bb2-0f88-4852-acfc-031499844f35:pubsub">
    <pubsub xmlns="http://jabber.org/protocol/pubsub">
        <subscribe node="8323266" jid="testuser@uc.pbx.speakup-telecom.com/LisaApi_BplUI0bnYj" />
    </pubsub>
</iq>
```

```xml
<iq xmlns="jabber:client" from="pubsub.uc.pbx.speakup-telecom.com" to="testuser@uc.pbx.speakup-telecom.com/LisaApi_BplUI0bnYj" id="2dab0bb2-0
f88-4852-acfc-031499844f35:pubsub" type="result">
    <pubsub xmlns="http://jabber.org/protocol/pubsub">
        <subscription jid="testuser@uc.pbx.speakup-telecom.com/LisaApi_BplUI0bnYj" subscription="pending" node="8323266" />
    </pubsub>
</iq>
<message xmlns="jabber:client" from="pubsub.uc.pbx.speakup-telecom.com" to="testuser@uc.pbx.speakup-telecom.com/LisaApi_BplUI0bnYj">
    <event xmlns="http://jabber.org/protocol/pubsub#event">
        <subscription jid="testuser@uc.pbx.speakup-telecom.com/LisaApi_BplUI0bnYj" node="8323266" subscription="subscribed" />
    </event>
</message>
```

--------------------------------

### Compass REST Interface - Resource Operations

Source: https://www.pbx.speakup-telecom.com/docs/developers-manual.html

The Compass REST API follows standard CRUD operations mapped to HTTP methods. Resources are identified by URIs, and operations are performed using GET, POST, PATCH, and DELETE.

```APIDOC
## Compass REST Interface

### Philosophy
Each resource in Compass is represented by a URI of the format `https://host/type/id`.

- **Create**: Mapped to `POST` method.
- **Retrieve**: Mapped to `GET` method.
- **Update**: Mapped to `PATCH` method.
- **Delete**: Mapped to `DELETE` method.

Operations that do not fall under the CRUD paradigm, such as initiating a call, are mapped to `POST`.
```

--------------------------------

### GetCompanyResult Structure

Source: https://www.pbx.speakup-telecom.com/docs/xsd/requests.xsd

Defines the structure for results when retrieving company information.

```APIDOC
## GetCompanyResult Structure

### Description
This structure represents the detailed information returned for a company.

### Response
#### Success Response (200)
- **result** (object) - The result object, extending the base result.
  - **id** (string) - The unique identifier of the company.
  - **name** (string) - The name of the company.
```
Tokens:
Raw