[COMMAND]

Starting a Session

The session_start command is used to initialise a WebSocket connection between TelXL servers and a client (such as a third-party application).

In almost all cases, this should be the first command you run as part of a WebSocket session. If you need to use other commands to initiate a session, you should already know what they are and how to use them.

Each session will act within the context of a specific operator configuration meaning that the data and resources available to the session will correspond with that configuration. The exact configuration is determined by including either config_id (the unique ID of the configuration) or agent_id (the unique ID of an operator assigned to the intended configuration), but not both.

Parameters

user
required
string

A valid user name with which to log in.

This is equivalent to the u query string parameter.

pass
required
string

The password associated with the chosen user.

This is equivalent to the p query string parameter.

mode
required
string

Defines the data to be sent via the WebSocket. Must be one of the following:

  • "api" for use with the CC4Web WebSocket API.
  • "web" for use with the original CC4Web JavaScript output.
agent_id
optional
number

If you want to act on behalf of a specific operator, specify their unique ID here. The session will use the configuration allocated to this operator, meaning you should not also specify a config_id.

This is equivalent to the opID query string parameter.

If you specify an operator not associated with the chosen user, your connection attempt will fail.

config_id
optional
number

To identify the intended configuration by its own ID instead of an operator's ID, provide it here.

This is equivalent to the configID query string parameter.

If you specify a configuration not associated with the chosen user, your connection attempt will fail.

Example Request

Copy
{"command":{"command_type":"session_start", "user":"Mr Black", "pass":"Mr Black", "mode":"api", "agent_id":"007", "config_id":"01"}}

Responses

On Success:

If successful, this command will open a WebSocket connection, and return a session_start_result event containing information about the new session.

To keep the current session active, you should use the session_ping command at intervals of no more than 30 seconds.

On Failure:

If a new session could not be established, the command will still return a session_start_result, albeit one containing information about what went wrong. There are various reasons this can happen, including connectivity errors, invalid credentials, or lack of permission to access the specified resource.