Platform HTTP API

Interaction format

API requests are made over the HTTP protocol. Input and output data structures are transmitted in the request and response body in JSON format.

Authorization

To do this, each request must contain a header or an X-Authorization argument with a connection token in the AccessKey token format,

For example, the title

POST /apps/activate HTTP/1.1

Host: api.unibell.tech

X-Authorization: AccessKey d8ac9959r12b43545da9034,

either by parameter

POST api.unibell.tech/apps/activate?X-Authorization=AccessKey d8ac9959r12b43545da9034

Response format

The JSON scheme of any response contains a string type status parameter with the following values:

Status Value	Description
ok	No errors
invalidAccessKeyError	Invalid AccessKey
requiredJsonError	The request body requires JSON
invalidSchemeError	Invalid JSON scheme
invalidDataError	Input data error
prohibitedForAppError	Prohibited for this application
prohibitedForServiceError	Prohibited for this service
rpcError	Communication error

For example:

    {
        …
        “status”: “ok”
        ....
    }

Some GET requests support paginated output. The following parameters are used to control the paginated output

Parameter	Description
page	Requested page number
per_page	Number of elements per page
disable_pagination	Disable paginated output

For example,

GET api.unibell.tech/media?page=1&per_page=10

The response to such a request will contain a pagination json object

    {
        …
        "pagination": {
            "totalItems": 2,
            "currentPage": 1,
            "totalPages": 1
        }
        ....
    }

Where

Parameter	Description
totalItems	Total number of elements
currentPage	Page sequence number
totalPages	Total number of pages

Request format

Media Library Management

A media library is a hierarchical storage of various user files, resembling a file system. Media library storage objects are files and folders. Files can be divided into folders. The library is accessed using Personal Account or this API.

Parameter	Description
totalItems	Total number of elements
currentPage	Page sequence number
totalPages	Total number of pages

Getting a list of all objects

Request

GET api.unibell.tech/media

Response

    {
        "status":  "ok",
        "pagination": {
            "totalItems":  2,
            "currentPage":  1,
            "totalPages":  1
        },
        "media": [
            {
                "createdDateTime":  "2020-02-12 18:09:10",
                "id":  65,
                "name":  "Hymns",
                "isFolder":  1
            },
            {
                "createdDateTime":  "2020-03-04 13:17:47",
                "id":  74,
                "name":  So young.mp3",
                "isFolder":  0
            }
        ]
    }

media — an array of media library objects containing the following parameters:

Parameter	Description
id	Unique identifier of the media resource
name	Name
createdDateTime	Date\time of upload
isFolder	Indicates that this object is a folder. 1 — yes, 0 — no

Getting a specific object

Request

GET api.unibell.tech/media/id, where id is the unique identifier of the media resource

Response

A list of attached files is returned for folders

    {
        "status": "ok",
        "pagination": {
            "totalPages": 1,
            "totalItems": 2,
            "currentPage": 1
        },
        "media": [
            {
                "isFolder": 0,
                "name": "Audio1.mp3",
                "createdDateTime": "2020-02-12 18:19:05",
                "id": 67
            },
            {
                "isFolder": 0,
                "name": "Audio2.mp3",
                "createdDateTime": "2020-02-12 18:19:18",
                "id": 68
            }
        ]
    }

For files, the requested file is returned.

Folder creation

Request

POST api.unibell.tech/media

    {
        "name": "asdasd"
    }

Parameter	Description
name	Folder name

Response

   {
        "status": "ok",
        "media": {
            "name": "asdasd2",
            "createdDateTime": "2020-04-06 18:44:45",
            "isFolder": 1,
            "id": 111
        }
    }

File Upload

Request

POST api.unibell.tech/media – places the file in the root folder
POST api.unibell.tech/media/folder_id – places the file in the specified folder

The file is passed in the request body via Content-Type: multipart/form-data

Response

    {
        "status": "ok",
        "media": {
            "name": "test",
            "createdDateTime": "2020-04-06 18:44:45",
            "isFolder": 0,
            "id": 112
        }
    }

Object rename

Request

PUT api.unibell.tech/media/id, where id is the unique identifier of the media resource

    {
        "name": "asdasd"
    }

Response

    {
        "status": "ok",
        "media": {
            "name": "asdasd",
            "createdDateTime": "2020-04-06 18:44:45",
            "isFolder": 1,
            "id": 111
        }
    }

Deleting an object

Request

DELETE api.unibell.tech/media/id – where id is the unique identifier of the media resource

Response

    {
        “status”: “ok”
    }

Application Management

Application activation

Performs activation of a pre-created application.

Request

POST api.unibell.tech/apps/activate

    {
"reference": "123456789",
"sourceAddr": "XXXXXXXXXXX",
"destAddr": "XXXXXXXXXXX",
"sex": 1,
"volume": 1,
"language": "xx-XX",
"rate": 1,
"scenarioData": "text=Hello, how are you?"
    }

Parameter	Type	Description
reference	string	The user parameter with which the callback will be called based on the results of the application execution
sourceAddr	string	Outgoing number
destAddr	string	Recipient’s phone number
scenarioData	string	Script variables for this application. It is a set of parameter=value pairs separated by — &.
sex	int	Gender. 0 — female, 1 — male
volume	int	Voice volume (0-2)
rate	int	The speed of speaking the text (0-4). (0 is the slowest)
language	string	The synthesis language. Available languages: en-US – English (US) en-IN – English (Indian) en-IE – English (Ireland) en-UA – English (Australian) en-GB-WLS – English (Welsh) en-NZ – English (New Zealand) en-ZA – English (South African) ar-AE – Arabic (gulf) nl-NL – Dutch nl-BE – Dutch (Belgain) da-DK – Danish is-IS – Icelandic es-ES – Spanish (European) es-US – Spanish (US) es-MX – Spanish (Mexican) it-IT – Italian ca-ES – Catalan cmn-CN – Chinese (Mandarin) yue-CN – Chinese (Cantonese) ko-KR – Korean de-DE – German de-AT – German (Austrian) nb-NO – Norwegian pl-PL – Polish pt-PT – Portuguese (European) pt-BR – Portuguese (Brazillian) ro-RO – Romanian ru-RU – Russian tr-TR – Turkish cy-GB – Welsh fi-FI – Finnish fr-FR – French fi-CA – French (Canadian) fr-BE – French (Belgian) sv-SE – Swedish ja-JP – Japanese

Response

    {
        “status”: “ok”
    }

During application execution, callbacks can be configured over the HTTP/HTTPS protocol. Callback is configured for two types of events — Start of execution (Start callback) and end of execution (End callback). Basic authorization is supported. Parameters are passed to the request URL.

See the callback versions and what methods are used in them here.

Example,
GET www.host.ru?type=startCallback&reference=324234

Parameters passed to the startCallback

Parameter	Description
reference	User parameter passed in the activation request
type	The type of callback request, in this case — startCallback

Parameters passed to endCallback

Parameter	Description
reference	User parameter passed in the activation request
type	The type of callback request, in this case — endCallback
state	Application execution result
error	Error code, or 0 — in case of successful execution
duration	Duration of the call

where, state is the result of script execution

	Value	Description
STATE_OK	2	Application completed successfully
STATE_ERR	5	Error as a result of execution

error — error code

	Value	Description
ERR_NO_ANSWER	16	The subscriber did not pick up the phone, attempts to dial are exhausted
ERR_BUSY	17	The subscriber is busy, dial-up attempts have been exhausted
ERR_ALERTING	19	The subscriber is unavailable
ERR_CONGESTION	34	Overload of communication channels
ERR_PLAY	1001	File playback error, file not found, invalid format
ERR_TTS	1002, 1017	TTS Conversion Error
ERR_ASR	1003	ASR Conversion error

Balance check

Request

GET api.unibell.tech/balance

Displays a personal account and its balance in JSON format. The personal account is displayed as the one on which the application is located, the key for which is specified in the request authorization

Response

     {
        "personalAccountId": "0000000000",
        "balance": "100.0"
     }

On this page