MOR API flash calls

Description

Flash call - initiate a call to destination number and receive call status - RINGING, BUSY, ANSWERED, FAILED or TIMEOUT. Call is automatically canceled once RINGING (PROGRESS) is received or the call is answered.

Available from MOR X18

Usage

This API does not follow standard MOR API usage and must be configured manually.

Configuration

Flash calls API must be configured in GUI server /etc/mor/system.conf configuration file.

API settings

General API settings:

• flash_calls_api_enabled - if set to 1, enables flash calls API.
• flash_calls_allowed_users - comma separated list of User IDs who are allowed to use this API. Can be set to "all" to allow all Users to use this API.
• flash_calls_api_default_device_id - default Device ID that will be used when no device_id parameter is passed to the /call endpoint.
• flash_calls_api_default_timeout_ms - default timeout (in milliseconds) when no timeout parameter is passed to the /call endpoint.
• flash_calls_api_max_timeout_ms - the maximum timeout (in milliseconds) allowed to use in /call endpoint via parameter timeout.
• flash_calls_api_allow_to_change_device_id - if set to 1, allows to change default device in /call endpoint via parameter device_id.
• flash_calls_api_allow_to_change_timeout - if set to 1, allows to change default timeout in /call endpoint via parameter timeout.
• flash_calls_api_auth_method - authentication method. Either basic authentication or JWT token authentication (see Authentication section).
• flash_calls_api_jwt_token_expiration - JWT token expiration time in seconds (see Authentication section).
• flash_calls_api_jwt_secret_key - secret key for JWT authentication (see Authentication section).

AMI settings

Flash call are initiated via Asterisk AMI. The following settings should be configured with specific Asterisk server details.

• flash_calls_ami_username - AMI username.
• flash_calls_ami_password - AMI password.
• flash_calls_ami_host - AMI host.
• flash_calls_ami_port - AMI port.

When these settings are configured or changed, the Flash calls API service must be restarted in GUI server:

systemctl restart mor_flash_calls

API

Flash calls API accepts parameters in JSON format. Responses are also returned in JSON format.

There are 3 endpoints related to Flash calls:

• /flash_calls/token - get a token for JWT authentication.
• /flash_calls/call - initiate a Flash call.
• /flash_calls/call_async_response - check Flash call response when the call was initiated with async parameter.

Authentication

Flash calls API require user authentication - either basic authentication (username/password) or JWT token authentication. This is controlled by flash_calls_api_auth_method setting in /etc/mor/system.conf.

For basic authentication, set:

flash_calls_api_auth_method=basic

For JWT authentication, set:

flash_calls_api_auth_method=jwt

In either case, HTTPS should be used to transmit credentials securely.

Basic authentication

Basic authentication uses User's username and password to access /call or /call_async_response endpoints.

Username and password must be provided in HTTP Authorization header, "username:password" string encoded in Base64. For example:

POST http://x.x.x.x/billing/api/flash_calls/call HTTP/1.1
Authorization: Basic cmljYXJkYxM6OWtBWFpadT9yak1iayRSaA==

JWT authentication

JWT authentication uses a token (generated by MOR) with each request to /call or /call_async_response endpoints. The API client must obtain JWT token by calling /token endpoint and then use this token in other endpoints for authentication until token expires. Once the token is expired, a new token must be obtained from /token endpoint.

This is the recommended authentication method as it provides better security and better performance.

JWT token must be provided in HTTP Authorization header when requesting /call or /call_async_response endpoints. For example:

POST http://x.x.x.x/billing/api/flash_calls/call HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhc3NpZ25lZF9kZXZpY2VzIjoiMiw4LDEwLDEyLDE4LDI2LDM2IiwiZXhwIjoxNzUyNTU1Njk4LCJpYXQiOjE3NTI0NjkyOTgsImlzcyI6IkZsYXNoIENhbGxzIEFQSSIsInN1YiI6InJpY2FyZGFzIn0.I3Sy1zrJx0mAsTLthitY8dyZfythsWzJ4V1CVfNJmYU

To use JWT authentication, the following settings must be configured in /etc/mor/system.conf:

flash_calls_api_auth_method=jwt
flash_calls_api_jwt_token_expiration=XXX
flash_calls_api_jwt_secret_key=YYY

Here XXX is a number of seconds for JWT token expiration. For example, to set JWT token expiration to 1 day, the value should be 86400.

A secret key YYY for JWT authentication must be generated. The following command can be used to generate secret key:

head /dev/urandom | tr -dc A-Za-z0-9_.- | head -c 32 | base64

Endpoints

/flash_calls/token

Endpoint to generate JWT token for authentication in other endpoints. Only available if JWT authentication is used. Username and password must be provided in Authorization header.

Method:

POST

Parameters:

None

Returns:

• expires_in - number of seconds for JWT token expiration. Value is integer.
• token - JWT token. Value is string.
• token_type - JWT token type. Value is always "Bearer" indicating that this token should be included in Authorization header. Value is string.

Example request:

POST http://x.x.x.x/billing/api/flash_calls/token HTTP/1.1
Authorization: Basic cmljYXJkYxM6OWtBWFpadT9yak1iayRSaA==

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "expires_in": 86400,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhc3NpZ25lZF9kZXZpY2VzIjoiMiw4LDEwLDEyLDE4LDI2LDM2IiwiZXhwIjoxNzUyNTkzNjc1LCJpYXQiOjE3NTI1MDcyNzUsImlzcyI6IkZsYXNoIENhbGxzIEFQSSIsInN1YiI6InJpY2FyZGFzIn0.dDsxxKIbW2S3uG7uzKskdGkfLEFsApBW5ETOWzuhmG8",
  "token_type": "Bearer"
}

/flash_calls/call

Endpoint to initiate a Flash call.

Method:

POST

Parameters:

• src - source number. Value is string. Required.
• dst - destination number. Value is string. Required.
• timeout_ms - timeout for request in milliseconds. Value is integer. Optional. Only allowed if flash_calls_api_allow_to_change_timeout setting is enabled.
• device_id - device ID to use for calling. Value is integer. Optional. Only allowed if flash_calls_api_allow_to_change_device_id setting is enabled.
• async - execute this request asynchronously. Response will be returned immediately with the URL where to check for the call execution status. Value is boolean. Optional.

Returns:

When async is false (or not present) in the request parameters:

• call_status - status of the Flash calls. Can be: RINGING, BUSY, ANSWERED, FAILED or TIMEOUT. Value is string.
• call_uniqueid - unique ID generated for this specific call. Can be used to find this exact call in CDRs. Value is string.
• call_started_at - time and date when the call was originated. Date format is ISO 8601. Value is string.
• call_ended_at - time and date when the call ended (or request timed out). Date format is ISO 8601. Value is string.

When async is true in the request parameters:

• response_url - URL to actual call response (more info in call_async_response endpoint). Value is string.

Example request when async is false (or not present) in request parameters:

POST http://x.x.x.x/billing/api/flash_calls/call HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhc3NpZ25lZF9kZXZpY2VzIjoiMiw4LDEwLDEyLDE4LDI2LDM2IiwiZXhwIjoxNzUyNTU1Njk4LCJpYXQiOjE3NTI0NjkyOTgsImlzcyI6IkZsYXNoIENhbGxzIEFQSSIsInN1YiI6InJpY2FyZGFzIn0.I3Sy1zrJx0mAsTLthitY8dyZfythsWzJ4V1CVfNJmYU
Content-Type: application/json

{
    "src": "37011111111",
    "dst": "37022222222",
    "timeout_ms": 10000,
    "device_id": 12
}

Example response when async is false (or not present) in request parameters:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 169

{
  "call_status": "RINGING",
  "call_uniqueid": "2c3a8d6c-ded3-4fb5-9888-2a12c943674a",
  "call_started_at": "2025-07-14T21:37:06.876Z",
  "call_ended_at": "2025-07-14T21:37:07.097Z"
}

Example request when async is true:

POST http://x.x.x.x/billing/api/flash_calls/call HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhc3NpZ25lZF9kZXZpY2VzIjoiMiw4LDEwLDEyLDE4LDI2LDM2IiwiZXhwIjoxNzUyNTU1Njk4LCJpYXQiOjE3NTI0NjkyOTgsImlzcyI6IkZsYXNoIENhbGxzIEFQSSIsInN1YiI6InJpY2FyZGFzIn0.I3Sy1zrJx0mAsTLthitY8dyZfythsWzJ4V1CVfNJmYU
Content-Type: application/json

{
    "src": "37011111111",
    "dst": "37022222222",
    "timeout_ms": 10000,
    "device_id": 12,
    "async": true
}

Example response when async is true:

HTTP/1.1 202 Accepted
Content-Type: application/json
Retry-After: 1
Content-Length: 91

{
  "response_url": "http://x.x.x.x/billing/api/flash_call/call_async_response/3f0cd022"
}

/flash_call/call_async_response

Endpoint is used to retrieve the actual call response from /call endpoint when requested with async parameter.
This is the recommended method for initiating Flash calls, as it allows the /call request to complete immediately, avoiding an open HTTP connection during call execution.
When 'async' parameter is set to true in /call endpoint, it will return URL to this endpoint with a short unique ID number. This URL should be periodically checked (for example every 1 or 2 seconds) for the actual call response. If this endpoint returns response with task_status PENDING or RUNNING, the request to call_async_response should be tried again after a short delay. If the response returns task_status COMPLETED or FAILED, the request is finished and there is no need to call this request again. Once the actual call response is returned (task_status COMPLETED or FAILED), it will be removed from internal response storage and requests to call_async_response with the same uniqueid ID will return HTTP 404 - not found.

Method:

GET

Parameters:

None

Returns:

• task_id - unique ID number for this async request (this ID is different than call unique ID and is only for internal purposes). Value is string.
• task_status - status of async call request. Can be: PENDING, RUNNING, COMPLETED or FAILED. Value is string.
• call_details - actual call execution response. Value is JSON. Only present when task_status is COMPLETED.

Example request:

POST http://x.x.x.x/billing/api/flash_call/call HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhc3NpZ25lZF9kZXZpY2VzIjoiMiw4LDEwLDEyLDE4LDI2LDM2IiwiZXhwIjoxNzUyNjQwMTMyLCJpYXQiOjE3NTI1NTQxMzIsImlzcyI6IkZsYXNoIENhbGxzIEFQSSIsInN1YiI6InJpY2FyZGFzIn0.yS9Lj-i33b1odvH9inW0nun24qhQAluJ2dtTsdPj9v4
Content-Type: application/json

{
    "src": "370000000",
    "dst": "370666666",
    "timeout_ms": 2000,
    "device_id": -1,
    "async": true
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 233

{
  "task_id": "564d0411",
  "task_status": "COMPLETED",
  "call_details": {
    "call_status": "RINGING",
    "call_uniqueid": "1442d30e-90bc-49a0-927c-4c51f29b74bf",
    "call_started_at": "2025-07-15T04:14:45.393Z",
    "call_ended_at": "2025-07-15T04:14:45.735Z"
  }
}

Errors

• Username not found in the database:

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: 39

{
  "error": "forbidden - user not found"
}

• Wrong password:

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: 42

{
  "error": "forbidden - password mismatch"
}

• user is not in the list of allowed users (flash_calls_allowed_users setting):

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: 38

{
  "error": "forbidden - access denied"
}

• No Authorization header is present:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Www-Authenticate: Basic realm="Flash Calls API"
Content-Length: 25

{
  "error": "unauthorized"
}

• JWT token is expired and must be obtained again:

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: 41

{
  "error": "forbidden - token is expired"
}

• Invalid JWT token:

HTTP/1.1 403 Forbidden
Content-Type: application/json
Content-Length: 46

{
  "error": "forbidden - token is unauthorized"
}

• Invalid parameters:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 47

{
  "error": "bad request"
}

• General server error - service logs should be checked for specific reason:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Content-Length: 34

{
  "error": "internal server error"
}

• Asynchronous response not found (or already expired)

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 62

{
  "error": "not found - response with UUID xxxxx not found"
}

See also

• MOR API