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: https://cpaas.mittoapi.net/api

X-Authorization: AccessKey d8ac9959r12b43545da9034,

either by parameter

POST https://cpaas.mittoapi.net/api/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 https://cpaas.mittoapi.net/api/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 https://cpaas.mittoapi.net/api/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 https://cpaas.mittoapi.net/api/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 https://cpaas.mittoapi.net/api/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 https://cpaas.mittoapi.net/api/media – places the file in the root folder
POST https://cpaas.mittoapi.net/api/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 https://cpaas.mittoapi.net/api/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 https://cpaas.mittoapi.net/api/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 https://cpaas.mittoapi.net/api/apps/activate

{
  "reference": "123456789",
  "sourceAddr": "XXXXXXXXXXX",
  "destAddr": "XXXXXXXXXXX",
  "gender": 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 — &.
gender	int	Gender. 2 — 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”
}

Launching the application with repeats

Starting the application with repeats is a process that initiates a call, automatically retrying in case of an unsuccessful outcome, such as a busy line, no answer, failed call, or successful response. The repeat settings allow you to define conditions and parameters for each scenario.

Example

If a call to the subscriber fails due to a busy line (repeatBusy), the system automatically retries after the set interval (repeatBusyInt) until the number of attempts (repeatBusyCount) is exhausted.

Request

POST https://cpaas.mittoapi.net/api/apps/activate

Request body

{
  "reference": "123456789",
  "sourceAddr": "XXXXXXXXXXX",
  "destAddr": "XXXXXXXXXXX",

  "scenarioData": "text=Hello, how are you?",

  "isRepeat": 1,
  "repeatBusy": 1,
  "repeatBusyCount": 10,
  "repeatBusyInt": 30,
  "repeatAnswered": 1,
  "repeatAnsweredCount": 10,
  "repeatAnsweredInt": 35,
  "repeatFailed": 1,
  "repeatFailedCount": 10,
  "repeatFailedInt": 1,
  "repeatNoAnswer": 1,
  "repeatNoAnswerCount": 10,
  "repeatNoAnswerInt": 150
}

Parameters	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 — &.
isRepeat	int	Repeat permission: _{^{0 — repeats are not made 1 — repeats are made}}
repeatBusy	int	Repeat on busy number
repeatAnswered	int	Repeat on successful answer
repeatFailed	int	Repeat on failed call
repeatNoAnswer	int	Repeat on no answer
repeatBusyCount, repeatAnsweredCount, repeatFailedCount, repeatNoAnswerCount	int	Number of repeats
repeatBusyInt, repeatAnsweredInt, repeatFailedInt, repeatNoAnswerInt	int	Repeat call interval (in seconds)

Response

{
    "status": "ok",
    "requestId": "37b873131de218352d63f980cb71b41b"
}

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
appKey	The API key of the application

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

Script execution error codes

Error value	Error	Description
1001	SCENARIO_NOT_FOUND	An internal script execution error _{indicates that the script that should have been executed does not exist or cannot be found}
1002	SCENARIO_JSON_PARSER_ERROR	An internal Json script parsing error _{can occur if the script has incorrect syntax or structure}
1003	SCENARIO_VAR_ID_ERROR	An internal error in parsing script variables _{may indicate problems with variable identification (not used)}
1004	SCENARIO_VAR_NAME_ERROR	Indicates problems with variable names in the script _{may be caused by an incorrect or missing variable name (not used)}
1005	TRUNK_NOT_FOUND	The trunk cannot be found according to the specified routing rules _{may be caused by incorrect routing settings or the absence of the required trunk}
1006	REDIRECT_TRUNK_NOT_FOUND	The trunk cannot be found according to the specified routing rules when forwarding a call _{may occur due to errors in the forwarding settings}
1007	MODIFIERS_ERROR	The error of the call modifiers _{indicates that the values of sourceAddr, destAddr, trunk Data were incorrectly changed for this call}
1008	REDIRECT_MODIFIERS_ERROR	Call modifiers error during forwarding _{the values of source Addr, dest Addr, trunk Data were incorrectly changed for call forwarding}
1009	CHANNEL_CREATION_ERROR	An error that occurs when creating a communication channel transmitted from Asterisk _{may be caused by problems with the configuration or resources of the system}
1010	REDIRECT_CHANNEL_CREATION_ERROR	An error when creating a forwarding channel _{indicates problems with creating a channel for a forwarded call}
1011	REDIRECT_BRIDGE_CREATION_ERROR	An error creating a conference bridge during forwarding transmitted from Asterisk _{a bridge cannot be created to connect multiple call participants}
1012	REDIRECT_ADDING_SOURCE_CHANNEL_TO_BRIDGE_ERROR	Error when adding a forwarded call channel to the bridge, transmitted from Asterisk the original channel cannot be correctly added to the bridge
1013	REDIRECT_ADDING_DEST_CHANNEL_TO_BRIDGE_ERROR	Error when adding the channel to which calls are forwarded to the bridge transmitted from Asterisk
1014	INCOMING_CALL_ANSWER_ERROR	Occurs if the call was dropped before the script execution started, because the channel no longer existed _{when the incoming call was answered with an error from Asterisk}
1015	PLAYBACK_START_ERROR	The error when playing to the channel comes from Asterisk
1016	RECORD_START_ERROR	The error when writing from the channel comes from Asterisk
1017	TTS_FAULT	A speech synthesis error transmitted from the app-TTS application _{may be caused by problems with speech synthesis or incorrect data for synthesis}
1018	WRONG_DATA_IN_REQUEST	Request data parsing error _{indicates incorrect or missing data in the request}
1019	NUMBER_NOT_FOUND_IN_POOL_BY_ENDING	Selecting a number from the pool at the end of the number for FlashCall _{it may be caused by the absence of the corresponding number in the pool}
1020	INTERFACE_NAME_EMPTY_ERROR	Error when selecting a trunk _{indicates incorrect or missing trunk configuration data}
1021	REDIRECT_INTERFACE_NAME_EMPTY_ERROR	An error when selecting a trunk for forwarding due to the absence of an interface name _{indicates incorrect or missing trunk configuration data}
0	Call sent to void	The completion of a normal scenario _{indicates that the call has completed normally, without any problems or errors}
1	Unallocated	It can happen when the requested resource does not exist or is currently unavailable
4-5	Vendor specific 4-5	Vendor-specific error _{the specific error value depends on the hardware or service provider}
6	Channel unaccessible	The channel is unavailable _{indicates that the communication channel required for the call is unavailable}
9-13	Vendor specific 9-13	Vendor-specific error _{the specific error value depends on the hardware or service provider}
16	Normal Clearing	Normal termination _{the call is completed on the initiative of one of the parties (subscriber or operator) without errors}
17	Line busy	The user is busy _{the number of the called party is busy and the call cannot be completed}
18	No user response	No response from the user _{the called party does not answer the call during the set waiting time}
19	No answer	The user was notified, but did not answer _{the subscriber was notified of an incoming call (for example, the phone rang), but did not accept it}
20	Subscriber absent	Missing subscriber _{indicates that the called subscriber is temporarily unavailable}
21	Call Rejected	The call is rejected _{the called party intentionally rejected the incoming call}
22	Number changed	The number has been changed
27	Destination out of order	The purpose of the call is out of service _{the end equipment or network of the called party is not working or unavailable}
28	Invalid number format	Incorrect number format _{the entered phone number has an incorrect format and cannot be recognized by the network}
29	Facility rejected	Feature rejected _{the requested service or feature is not supported or rejected by the network}
31	Normal unspecified	The usual unspecified _{the call ended for the usual reason, which was not explicitly stated}
32	(Reserved)	Reserved for future use
34	No circuit available	Circuit/channel overload _{there is an overload in the network and the call cannot be processed}
36	Out of order	Faulty _{indicates that the equipment or line is not working properly}
38	Network out of order	The network is not working _{there has been a network outage, which makes it impossible to end the call}
43	Access disconnect	Disabling access _{indicates that network access has been disabled}
58	Bearer capability not available	Load-bearing capacity is not available
98	Blacklist	Indicates that the call was blocked because the number is on the blacklist
99	Vad avtoinformator error	Indicates that the call was processed by the auto-informer
100	InvalidIe contents	Invalid IE content (Information Element) _{indicates an error in the information passed in the element}
102	Recover on timer expiry	Recovery after the timer expires
127	Failure	Interaction/not specified
199	Transaction abort	Abort a transaction _{the transaction was aborted for some reason}
200	No translation for address of such nature	It may be due to the fact that the address is invalid, non-existent or not recognized by the system
201	No translation for this specific address	There is no conversion for this particular address _{indicates that there is no routing or conversion for the specified address}
212	Hop counter violation	Violation of the traffic counter _{indicates that the allowed number of clicks in the network has been exceeded}

Balance check

Request

GET https://cpaas.mittoapi.net/api/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