1. References
  2. Management API
  3. Scenarios
Rate this page:

Scenarios

Methods

AddScenario

Copy URL

Adds a new scenario to the Shared folder, so the scenario is available in all the existing applications. Please use the POST method.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Developer
AddScenario example
Copy

AddScenario example

Add a new scenario: var s='hello';

Parameters

  • application_id:

    number

    Optional

    ID of the application to bind the scenario to

  • application_name:

    string

    Optional

    Name of the application to bind the scenario to

  • rewrite:

    boolean

    Optional
    Defaults on:  false

    Whether to rewrite the existing scenario

  • rule_id:

    number

    Optional

    The rule ID. The new scenario binds to the specified rule. Please note, if you do not bind the scenario to any rule, you cannot execute the scenario

  • rule_name:

    string

    Optional

    The rule name that can be used instead of rule_id

  • scenario_name:

    string

    The scenario name. The length must be less than 30

  • scenario_script:

    string

    Optional

    The scenario text. Use the application/x-www-form-urlencoded content type with UTF-8 encoding. The length must be less than 128 KB

Returns

  • result:

    number

    1

  • scenario_id:

    number

    The new scenario ID

BindScenario

Copy URL

Bind the scenario list to the rule. You should specify the application_id or application_name if you specify the rule_name. Please note, the scenario and the routing rule need to be within the same application.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Developer
BindScenario example
Copy

BindScenario example

Bind the scenarios 1, 2 and 3 with the rule 1.

Parameters

  • application_id:

    number

    The application ID

  • application_name:

    string

    The application name that can be used instead of application_id

  • bind:

    boolean

    Optional
    Defaults on:  true

    Whether to bind or unbind (set true or false respectively)

  • rule_id:

    number

    The rule ID to bind the scenario. The rule and the scenario need to be in the same application

  • rule_name:

    string

    The rule name that can be used instead of rule_id

  • scenario_id:

    intlist

    The scenario ID list separated by semicolons (;)

  • scenario_name:

    stringlist

    The scenario name list separated by semicolons (;). Can be used instead of scenario_id

Returns

  • result:

    number

    1

DelScenario

Copy URL

Deletes the scenario.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Developer
DelScenario example
Copy

DelScenario example

Delete the scenario 1 and 3.

Parameters

  • scenario_id:

    intlist

    The scenario ID list separated by semicolons (;). Use the 'all' value to delete all scenarios in all applications

  • scenario_name:

    stringlist

    The scenario name list separated by semicolons (;). Can be used instead of scenario_id

Returns

  • result:

    number

    1

GetScenarios

Copy URL

Gets the account's scenarios.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Developer
GetScenarios example
Copy

GetScenarios example

Get two scenarios, but skip the first one.

Parameters

  • application_id:

    number

    Optional

    ID of the scenario's application

  • application_name:

    string

    Optional

    Name of the scenario's application

  • count:

    number

    Optional
    Defaults on:  20

    The max returning record count

  • offset:

    number

    Optional
    Defaults on:  0

    The first N records are skipped in the output

  • scenario_id:

    number

    Optional

    The scenario ID to filter

  • scenario_name:

    string

    Optional

    The scenario name to filter. Can be used instead of scenario_id. All scenarios containing this param in their names are returned. The parameter is case insensitive

  • with_script:

    boolean

    Optional
    Defaults on:  false

    Whether to get the scenario text. You must specify the 'scenario_id' too!

Returns

  • application_id:

    number

    ID of the scenario's application

  • application_name:

    string

    Name of the scenario's application

  • count:

    number

    The returned scenario count

  • extended_application_name:

    string

    Application name including the node name

  • result:

    [ScenarioInfoType]

  • total_count:

    number

    The total found scenario count

ReorderScenarios

Copy URL

Configures the order of scenarios that are assigned to the specified rule.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Developer
ReorderScenarios example
Copy

ReorderScenarios example

Set the scenario loading order: 17, 15, 20.

Parameters

  • rule_id:

    number

    The rule ID

  • rule_name:

    string

    The rule name that can be used instead of rule_id

  • scenario_id:

    intlist

    Optional

    The scenario ID list separated by semicolons (;)

Returns

  • result:

    number

    1

SetScenarioInfo

Copy URL

Edits the scenario. You can edit the scenario's name and body. Please use the POST method.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Developer
SetScenarioInfo example
Copy

SetScenarioInfo example

Add a new scenario: var s='hello';

Parameters

  • required_scenario_name:

    string

    The name of the scenario to edit, can be used instead of scenario_id

  • scenario_id:

    number

    The scenario ID

  • scenario_name:

    string

    Optional

    The new scenario name. The length must be less than 30

  • scenario_script:

    string

    Optional

    The new scenario text. Use the application/x-www-form-urlencoded content type with UTF-8 encoding. The length must be less than 128 KB

Returns

  • result:

    number

    1

StartConference

Copy URL

Runs a session for video conferencing or joins the existing video conference session.

When you create a session by calling this method, a scenario runs on one of the servers dedicated to video conferencing. All further method calls with the same conference_name do not create a new video conference session but join the existing one.

Use the StartScenarios method for creating audio conferences.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Developer
CallsSMS
StartConference example
Copy

StartConference example

Start the conference from the account.

Parameters

  • application_id:

    number

    Optional

    The application ID

  • application_name:

    string

    Optional

    The application name that can be used instead of application_id

  • conference_name:

    string

    The conference name. The name length must be less than 50 symbols

  • reference_ip:

    string

    Optional

    Specifies the IP from the geolocation of predicted subscribers. It allows selecting the nearest server for serving subscribers

  • rule_id:

    number

    The rule ID that needs to be launched. Please note, the necessary scenario needs to be attached to the rule

  • script_custom_data:

    string

    Optional

    The script custom data, that can be accessed in the scenario via the VoxEngine.customData() method. Use the application/x-www-form-urlencoded content type with UTF-8 encoding.

  • server_location:

    string

    Optional

    Specifies the location of the server where the scenario needs to be executed. Has higher priority than reference_ip. Request getServerLocations for possible values

  • user_id:

    number

    Optional

    The user ID. Run the scripts from the user if set

  • user_name:

    string

    Optional

    The user name that can be used instead of user_id. Run the scripts from the user if set

Returns

  • call_session_history_id:

    number

    The call session history ID. To search a call session result, paste the ID to the GetCallHistory method's call_session_history_id parameter

  • media_session_access_secure_url:

    string

    The URL to control a created media session. It can be used for arbitrary tasks such as stopping scenario or passing additional data to it. Making HTTPS request on this URL results in the AppEvents.HttpRequest VoxEngine event being triggered for a scenario, with an HTTP request data passed to it

  • media_session_access_url:

    string

    The URL to control a created media session. It can be used for arbitrary tasks such as stopping scenario or passing additional data to it. Making HTTP request on this URL results in the AppEvents.HttpRequest VoxEngine event being triggered for a scenario, with an HTTP request data passed to it

  • result:

    number

    1

StartScenarios

Copy URL

Runs JavaScript scenarios on a Voximplant server. The scenarios run in a new media session. To start a scenario, pass the routing rule ID associated with the necessary scenario. You can use both GET and POST requests, but we recommend using the POST mode if you pass some data in the custom_data field. The maximum number of simultaneous requests is 200. If you exceed this number, you get the 429 error code.

Available for roles

To call this method, make sure your service account has one of the following roles:

See Available Roles
Owner
Admin
Developer
CallsSMS
StartScenarios example
Copy

StartScenarios example

Start the scripts from the account.

Parameters

  • application_id:

    number

    Optional

    The application ID

  • application_name:

    string

    Optional

    The application name that can be used instead of application_id

  • reference_ip:

    string

    Optional

    Specifies the IP from the geolocation of predicted subscribers. It allows selecting the nearest server for serving subscribers

  • rule_id:

    number

    The rule ID that needs to be launched. Please note, the necessary scenario needs to be attached to the rule

  • script_custom_data:

    string

    Optional

    The script custom data, that can be accessed in the scenario via the VoxEngine.customData() method. Use the application/x-www-form-urlencoded content type with UTF-8 encoding

  • server_location:

    string

    Optional

    Specifies the location of the server where the scenario needs to be executed. Has higher priority than reference_ip. Request getServerLocations for possible values

  • user_id:

    number

    Optional

    The user ID. Run the scripts from the user if set

  • user_name:

    string

    Optional

    The user name that can be used instead of user_id. Run the scripts from the user if set

Returns

  • call_session_history_id:

    number

    The call session history ID. To search a call session result, paste the ID to the GetCallHistory method's call_session_history_id parameter

  • media_session_access_secure_url:

    string

    The URL to control a created media session. You can use it for arbitrary tasks such as stopping scenario or passing additional data to it. Making HTTPS request on this URL results in the AppEvents.HttpRequest VoxEngine event being triggered for scenario, with HTTP request data passed to it

  • media_session_access_url:

    string

    The URL to control a created media session. You can use it for arbitrary tasks such as stopping scenario or passing additional data to it. Making HTTP request on this URL results in the AppEvents.HttpRequest VoxEngine event being triggered for scenario, with HTTP request data passed to it

  • result:

    number

    1