# SWAN

###### tags: `active`

The requests will be made to a web server with the URL followed by the request that you want to make: https://10.1.1.87/-5 request]. For example: https://10.1.1.87/userStatus/200.

The data is sent by `GET`,` POST` or `DELETE`. Each request has a different method as indicated in square brackets.

Requests marked as ==[JWT format]==, must be encrypted with JWT. `GET` or `POST` data becomes `{ 'jwt': <encrypted requests> }`.
Response is also encrypted with JWT `{ 'jwt': <encrypted response> }`.
- **Header:**

{
    alg: 'HS256',
    typ: 'JWT'
}

- **Payload:**

{
    iss: <path to api, for exaple: http://10.1.1.6/api/>,
    aud: <path to api>,
    iat: <current time in seconds>,
    exp: <expiration time in seconds, for example: iat + 60 seconds>,
    data: <GET or POST parameters>
}

- **Key secret:** 7S\`\\>g&)]h9Qx2E5

:::info
JWT for PHP: https://github.com/firebase/php-jwt
More libraries for other languages: https://jwt.io/
:::

The response will always be in JSON format: header `Content-Type: application / json`.

All responses have the same result format (once decrypted):
- **error:**: can have two formats
- boolean: `true` | `false`
- string: error message
- **result:** request response

---

# 1. STATUS
## 1.1. userStatus/{extension} [GET]==[JWT format]==
Obtain the status of the user with `{extension}`.
### Result

{
    "extension":     user extension,
    "id":            user id,
    "name":          user name,
    "status":        available/unavailable/busy/ringing/pause,
    "successStatus": available/unavailable/pause,
    "description":   status user friendly translation
}

## 1.2. userStatus/{extension} [POST]==[JWT format]==
Change status of the user with `{extension}`.
### Params
- **status:** available/busy/pause
- **reason [optional]:** status description
### Result
Same as [`userStatus/{extension} [GET]`](https://hackmd.io/s0eQlY7BQUmH9dLGth1T-g#11-userStatusextension-GET)

## 1.3. blf-users/{company} [GET]==[JWT format]==
List of users in `{company}` specifying the user extension's status.
### Params
- **departments [optional]:** array of departments to look into
- **withMobile [optional]:** `true` | `false` if user's mobile should be obtained
### Result

[
    {
        "extension":         user extension,
        "id":                user id,
        "name":              user name,
        "status":            available/unavailable/busy/ringing,
        "successStatus":     available/unavailable/pause,
        "description":       status user friendly translation,
        "mobile [optional]": user mobile (only if withMobile = true)
    },
    ...
]

## 1.4. queuesStatus [GET]==[JWT format]==
Obtain status of N queues.
Same as [`call-center/queues/{company} [GET]`](https://hackmd.io/s0eQlY7BQUmH9dLGth1T-g#71-call-centerqueuescompany-GET) but `{company}`parameter is not defined in order to ignore users status.

## 1.5. calendarStatus/{company}/{calendar} [GET]==[JWT format]==
Obtain `{calendar}` status of `{company}`.
### Result
- **contestador:**
- **desviament:**
- **locucio:**
- **numero_desviament:**
- **prioritat:**
- **status:** `open` | `close` | `forward`

## 1.6. terminalStatus/{mac} [GET]==[JWT format]==
Check if the terminal with `{mac}` is registered and beening used by some user.
### Result

{
    "registered": `true` | `false`
}

---

# 2. USER
## 2.1. username/{extension} [GET]
Given an `{extension}`: get the user's name.
### Result
- **username:** `null` | name of the user

## 2.2. web-phone-username/{extension} [GET]==[JWT format]==
Given an `{extension}`: get the mac of the terminal of type `webphone`, that allows the login on a webphone. ==Returns an error if the user cannot login because terminal is already registered.==
### Result
- **username:** `null` | mac of user's webphone terminal
- **is_registered:** `true` | `false` indicatinc if another tab/device is already loged in

## 2.3. user-resume/{extension} [GET]==[JWT format]==
### Params
- **company:** name of the user's company
- **queues [optional]:** queues groups to load waiting calls `array('groupName' => array('queue1', 'queue2', ...), ...)`
- **department [optional]:** department name to load waiting times and compare `{extension}` statistics with this department
### Result
- **waiting-calls:** number of waiting calls of queues

    {
        "{groupName}": number of waiting calls,
        ...
    }

- **queue [optional]:** queue resume

    {
        "completed":         number of calls attended,
        "abandoned":         number of abandoned calls,
        "totalSpeechTime":   speech time formated
    }

- **user [optional]:** user resume

    {
        "completed":         number of calls attended,
        "totalSpeechTime":   speech time formated,
        "lastCall":          last called phone number,
        "stats_complete":    {
            "percentage":    percentage of completed calls compared to queue
            "state":         1 = VERY_BAD | 2 = BAD | 3 = NORMAL | 4 = GOOD | 5 = VERY_GOOD
        },
        "stats_time":    {
            "percentage":    percentage of speech time calls compared to queue
            "state":        1 = VERY_BAD | 2 = BAD | 3 = NORMAL | 4 = GOOD | 5 = VERY_GOOD
        }
    }

## 2.4. last-calls/{extension} [GET]
Obtain a list of calls made in the last 24hours by the `{extension}`, from more recent to more old.
### Params
- **hours [optional]:** specify last amount of hours (default 24)
### Result

[
    {
        "uniqueid":     call id,
        "calldate":     yyyy-mm-dd hh:mm:ss,
        "duration":     duration in seconds,
        "number":       opponent phone number,
        "direction":    "outgoing" | "incoming"
    },
    ...
]

## 2.5. current-calls/{extension} [GET]
Obtain a list of current calls by the `{extension}`, from more recent to more old.
### Result
Same as [`last-calls/{extension} [GET]`](https://hackmd.io/s0eQlY7BQUmH9dLGth1T-g#24-last-callsextension-GET)

---

# 3. PBX
## 3.1. recording/{callID}/{extension} [GET]
Get the audio of a call with identifier `{callID}`.
### Result
- **processing:** `true` | `false` to know if the audio file already exists or not
- **path [optional]:** if the `{extension}` is in the call: URL of the audio file
- **link [optional]:** if is not in the call: URL of the link to Swan to listen to the audio

## 3.2. call/{destination} [POST]==[JWT format]==
Place a call to `{private_source}` in `{company}` and connects call (when answered) to `{destination}`. `{private_source}` should exist in `{company}` for this feature to work
### Params
- **private_source:** extension that will receive the first call.
- **company:** that will receive the first call.
### Result
- **success:** `true` | `false`

---

# 4. AGENDA
## 4.1. delete-phones-agenda [DELETE]
Delete phones in agenda with name `{name}`:
- All phones if field `phones` is NOT specified.
- Only phones specified in `phones` field.
- If all goes well: changes to the agendas are applied.
### Params
- **name:** agenda's name
- **phones [optional]:** array of phones to delete in the agenda in the format:

    [
        "{number}",
        ...
    ]

### Result
- **success:** `true` | `false`

## 4.2. update-agenda [POST]
Add new phones in an agenda:
- If there is no agenda with that name: it creates it.
- New phones are created, repeated ones are updated.
- If all goes well: changes to the agendas are applied.
### Params
- **name:** agenda's name
- **phones:** array of phones to insert in the agenda in the format:

    [
        {
            "name": name of the phone,
            "number": number of the phone
        },
        ...
    ]

### Result
- **success:** `true` | `false`

---

# 5. TERMINAL
## 5.1. terminal-register/{mac} [POST]
Log terminal registration on database. Must unregister if wasn't previously unregistered.
### Result
- **success:** `true` | `false`

## 5.2. terminal-register/{mac} [DELETE]
If it wasn't previously unregistration: log terminal unregistration on database.
### Result
- **success:** `true` | `false`

---

# 6. COMPANY
## 6.1. company-departments/{company} [GET]
Get departments in `{company}`.
### Result
- **items:** array of departments:

    [
        {
            "id": identifier of the department,
            "name": name of the department
        },
        ...
    ]

## 6.2. company-incoming-agenda/{company} [GET]
Get phones of incoming-agenda in `{company}`. If icoming agenda is "all": all phones are loaded.
### Result
- **items:** array of phones:

    [
        {
            "id": identifier of the phone,
            "name": number of the phone
        },
        ...
    ]

## 6.3. company-ivrs/{company} [GET]
Get ivrs in `{company}`.
### Result
- **items:** array of ivrs:

    [
        {
            "id": identifier of the ivr,
            "name": name of the ivr
        },
        ...
    ]

## 6.4. company-numbers/{company} [GET]
Get numbers in `{company}`.
### Params
- **in_use:** `false` or not set means all, `true` means only in use
### Result
- **items:** array of numbers:

    [
        {
            "id": identifier of the numbers,
            "name": name and number,
            "alias": alias,
            "value": number
        },
        ...
    ]

## 6.5. company-queues/{company} [GET]
Get queues in `{company}`.
### Result
- **items:** array of queues:

    [
        {
            "id": identifier of the queues,
            "name": name of the queue
        },
        ...
    ]

## 6.6. company-users/{company} [GET]
Get users in `{company}`.
### Result
- **items:** array of users:

    [
        {
            "id": identifier of the user,
            "name": name of the user + extension
        },
        ...
    ]

---

# 7. CALL CENTER
## 7.1. call-center/queues | call-center/queues/{company} [GET]==[JWT format]==
Obtain status of users and queues / queues specified.
### Params
- **queues:** queues to check with format:

    {
        '{queueGroup}': ['{queue1}', '{queue2}', ...],
        ...
    }

### Result
- **queues:** statistics of each queue or queueGroup

    {
        '{alias}': {
            'members': array of extensions of the users logged on this queue,
            'alarm': `true`|`false` is alarm should sound,
            'status': {
                'abandoned': number of missed calls,
                'abandonedRatio': 100 - (abandoned * 100 / (completed + abandoned)),
                'avgRingTime': average ring time in seconds,
                'avgRingTimeRatio': avgRingTime * 100 / maxRingTime,
                'completed': number of completed calls,
                'currentCalls': number of current calls in queue,
                'maxRingTime': maximum ring time in seconds,
                'ringTimeOK': number of calls with ring time < 20 seconds,
                'serviceRatio': ringTimeOK * 100 / completed
            }
        },
        ...
    }

- **users:** status of users (only if `{company}` is defined)

    [
        {
            'id': identifier of the user,
            'extension': extension of the user,
            'name': name of the user,
            'status': status of the user,
            'successStatus': sub status of the user (pause),
            'description': status description
        },
        ...
    ]

## 7.2. call-center/calls/{company} [GET]==[JWT format]==
Obtain calls by hour of queues / queues specified.
### Params
- **queues:** queues to check with format:

    {
        '{alias}': ['{queue1}', '{queue2}', ...],
        ...
    }

- **timeRange [optional only for /queueStatus]:** hours to check completed and abandonded calls. For example [9, 10, 11, 12, 13, 14, 15, 16, 17, 18]
- **hour [optional]:** obtain calls of specific hour
### Result
- **calls:** completed and abandoned calls of queues

    {
        '{alias}': {
            'completed': array of completed calls divided by hour with same order as {timeRange}
            'abandoned': array of abandoned calls divided by hour with same order as {timeRange}
        },
        ...
    }