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

Configuration from GUI

Device (and User) should be created for Flash calls and the ID of this Device should be set in flash_calls_api_default_device_id setting. This Device will be used for initiating Flash calls when no specific Device is requested via parameters.

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 - empty request body.

Returns (JSON response body):

• 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.

HTTP status on success:

HTTP/1.1 200 OK

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 (JSON request body):

• src (string, required) - Source number.
• dst (string, required) - Destination number.
• timeout_ms (integer, optional) - Timeout for request in milliseconds. Only allowed if flash_calls_api_allow_to_change_timeout setting is enabled.
• device_id (integer, optional) - Device ID to use for calling. Only allowed if flash_calls_api_allow_to_change_device_id setting is enabled.
• async (boolean, optional) - Execute this request asynchronously. Response will be returned immediately with the URL where to check for the call execution status.

Returns (JSON response body) - when async is false:

• 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.

Returns (JSON response body) - when async is true:

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

HTTP status on success - when async is false:

HTTP/1.1 200 OK

HTTP status on success - when async is true:

HTTP/1.1 202 Accepted

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_calls/call_async_response/3f0cd022"
}

/flash_calls/call_async_response/{task_id}

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/{task_id} 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/{task_id} with the same uniqueid ID will return HTTP 404 - not found. The response is valid for 5 minutes - after that, the response will expire and attempts to retrieve it will return HTTP 404 - not found.

Method:

GET

Parameters:

None - empty request body

Returns (JSON response body):

• task_id - unique ID number for this async request. 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.

HTTP status on success:

HTTP/1.1 200 OK

Example request:

GET http://x.x.x.x/billing/api/flash_calls/call_async_response/5f3aa202 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhc3NpZ25lZF9kZXZpY2VzIjoiMiw4LDEwLDEyLDE4LDI2LDM2IiwiZXhwIjoxNzUyNTU1Njk4LCJpYXQiOjE3NTI0NjkyOTgsImlzcyI6IkZsYXNoIENhbGxzIEFQSSIsInN1YiI6InJpY2FyZGFzIn0.I3Sy1zrJx0mAsTLthitY8dyZfythsWzJ4V1CVfNJmYU

Example response:

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

{
  "task_id": "5f3aa202",
  "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 401 Unauthorized
Www-Authenticate: Basic realm="Flash Calls API"

{
  "code": "FORBIDDEN_ACCESS_USER_NOT_FOUND",
  "message": "Access to this resource is forbidden - user not found",
  "timestamp": "2025-07-15T10:14:49.253Z"
}

• Wrong password

HTTP/1.1 401 Unauthorized
Www-Authenticate: Basic realm="Flash Calls API"

{
  "code": "FORBIDDEN_ACCESS_USER_WRONG_PASSWORD",
  "message": "Access to this resource is forbidden - wrong password",
  "timestamp": "2025-07-15T10:15:18.764Z"
}

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

HTTP/1.1 403 Forbidden

{
  "code": "FORBIDDEN_ACCESS",
  "message": "Access to this resource is forbidden",
  "timestamp": "2025-07-15T09:02:23.016Z"
}

• No Authorization header is present

HTTP/1.1 401 Unauthorized
Www-Authenticate: Basic realm="Flash Calls API"

{
  "code": "AUTHENTICATION_REQUIRED",
  "message": "Authentication is required",
  "timestamp": "2025-07-15T10:15:55.482Z"
}

• JWT token is expired and must be obtained again

HTTP/1.1 401 Unauthorized
Www-Authenticate: Bearer realm="Flash Calls API"

{
  "code": "TOKEN_EXPIRED",
  "message": "The provided authentication token has expired, please re-authenticate",
  "timestamp": "2025-07-15T08:11:24.239Z"
}

• Invalid JWT token

HTTP/1.1 401 Unauthorized
Www-Authenticate: Bearer realm="Flash Calls API"

{
  "code": "INVALID_TOKEN",
  "message": "The provided authentication token is invalid or malformed",
  "timestamp": "2025-07-15T08:13:54.932Z"
}

• Invalid parameters

HTTP/1.1 400 Bad Request

{
  "code": "INVALID_PARAMETERS",
  "message": "One or more parameters are invalid",
  "timestamp": "2025-07-15T10:20:53.637Z"
}

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

HTTP/1.1 500 Internal Server Error

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred on the server",
  "timestamp": "2025-07-15T10:24:41.897Z"
}

• Asynchronous response not found (or already expired)

HTTP/1.1 404 Not Found

{
  "code": "NOT_FOUND",
  "message": "The requested resource was not found",
  "timestamp": "2025-07-15T10:25:14.201Z"
}

Debugging

In case of errors, the following logs should be checked:

• /var/log/mor/mor_flash_calls.log
• /var/log/asterisk/messages

See also

• MOR API