# SWAN v2

###### 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/[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.

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

All responses have the same result format:
- **error:** can `true` | `false`
- **error-msg:** `null` if no error | string describing the error
- **result:** request response

---

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

{
    "error": false,
    "error-msg": null,
    "result": {
        "extension": user extension,
        "id": user id,
        "name": user name,
        "status": "available" / "unavailable" / "busy" / "ringing" / "pause",
        "description": status user friendly translation (E.g: "Descanso"
    }
}

## 1.2. userStatus/{extension} [POST]
Change status of the user with `{extension}`.
### Params
- **status:** available/busy/pause
- **reason [optional]:** status description
### Result

{
    "error": false,
    "error-msg": null,
    "result": {
        "extension": user extension,
        "id": user id,
        "name": user name,
        "status": "available" / "unavailable" / "busy" / "ringing" / "pause",
        "description": status user friendly translation (E.g: "Descanso"
    }
}

## 1.3. blf-users/{company} [GET]
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

{
    "error": false,
    "error-msg": null,
    "result": [
        {
            "extension": user extension,
            "id": user id,
            "name": user name,
            "status": "available" / "unavailable" / "busy" / "ringing" / "pause",
            "description": status user friendly translation (E.g: "Descanso"),
            "mobile [optional]": user mobile (only if withMobile = true)
        },
        ...
    ]
}

## 1.4. queues-status [GET]
Obtain status of N queues.
### Params
- **queues:** queues to check with format:

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

### Result

{
    "error": false,
    "error-msg": null,
    "result": {
        "queues": statistics of each queue or queueGroup {
            "{queueGroup}": {
                "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
                }
            },
            ...
        }
    }
}

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

{
    "error": false,
    "error-msg": null,
    "result": {
        "username": name associated to the extension | null if not found
    }
}

## 2.2. web-phone-username/{extension} [GET]
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

{
    "error": false,
    "error-msg": null,
    "result": {
        "username": null | mac of user's webphone terminal,
        "is_registered": true | false indicating if another tab/device is already loged in
    }
}

## 2.3 user-unregister/{extension} [POST]
Given an `{extension}`: indicate to the PBX that user has logged out.
### Result

{
    "error": false,
    "error-msg": null,
    "result": {
        "success": true | false
    }
}

## 2.4. user-resume/{extension} [GET]
### 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

{
    "error": false,
    "error-msg": null,
    "result": {
        "waiting-calls": number of waiting calls by queue {
            "{groupName}": number of waiting calls,
            ...
        },
        "queue [optional]": queue resume {
            "completed": number of calls attended,
            "abandoned": number of abandoned calls,
            "totalSpeechTime": speech time formated "mm minutos ss segundos"
        },
        "user [optional]": user resume {
            "completed": number of calls attended,
            "totalSpeechTime": speech time formated "mm minutos ss segundos",
            "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
            }
        }
    }
}

- VERY_BAD: if user is worst in 25 points or more in comparison with queue
- BAD: if user is worst in between 25 and 5 points in comparison with queue
- NORMAL: if user is in between 5 points worst and 5 points better in comparison with queue
- GOOD: if user is better in between 5 and 25 in comparison with queue
- VERY_GOOD: if user is better in 25 points or more in comparison with queue

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

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

## 2.6. current-calls/{extension} [GET]
Obtain a list of current calls where `{extension}` is involved, from recent to oldest.
### Result

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

# 3. PBX
## 3.1. recording/{callID}/{extension} [GET]
Get the audio of a call with identifier `{callID}` only if user with `{extension}` has permissions to access to the audio.
### Result

{
    "error": false,
    "error-msg": null,
    "result": {
        "processing": true | false. true means that the audio does not exists yet,
        "path" [optional]: if the user with `{extension}` is involved in the call: URL of the audio file in order to listen it inside Fedesk,
        "link" [optional]: if is not involved in the call: URL of the audio in the PBX admin. If the user has acces to the platform: he will be able to listen to it inside the PBX admin
    }
}

## 3.2. call/{destination} [POST]
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

{
    "error": false,
    "error-msg": null,
    "result": {
        "success": true | false
    }
}

# 4. AGENDA
## 4.1. delete-phones-agenda [DELETE]
Delete phones in agenda with name `{name}`:
- All records if field `phones` is NOT specified.
- Only records specified in `phones` field.
### Params
- **name:** agenda's name
- **phones [optional]:** array of numbers to delete in the agenda in the format:

    [
        "{number}",
        ...
    ]

### Result

{
    "error": false,
    "error-msg": null,
    "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.
### Params
- **name:** agenda's name
- **phones:** array of numbers to insert in the agenda in the format:

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

### Result

{
    "error": false,
    "error-msg": null,
    "result": {
        "success": true | false
    }
}

# 5. TERMINAL
## 5.1. terminal-register/{mac} [POST]
Given a `{mac}`, register user in all queues and terminals. Must unregister if wasn't previously unregistered.
### Result

{
    "error": false,
    "error-msg": null,
    "result": {
        "success": true | false
    }
}

## 5.2. terminal-register/{mac} [DELETE]
Given a `{mac}`, unregister user in all queues and terminals. Must register if wasn't previously registered.
### Result

{
    "error": false,
    "error-msg": null,
    "result": {
        "success": true | false
    }
}

# 6. COMPANY
## 6.1. company-numbers/{company} [GET]
Get public numbers in `{company}`.
### Params
- **in_use:**
- `false` (or not set) means return all numbers,
- `true` means only numbers in use
### Result

{
    "error": false,
    "error-msg": null,
    "result": [
        {
            "id": identifier of the number,
            "name": name and number (E.g: "primari - 937060370"),
            "alias": alias (E.g: "ONFARMA"),
            "value": number
        },
        ...
    ]
}