METHOD_BeginSession

This method notifies BEMS that the BlackBerry Connect app wants to start a chat session. This method replaces the login method because it is using single sign-on. Make sure to use the appropriate parameters based on the version of API you are using.

The following table describes the parameters that you can include in this method.

Parameter

Type

Required

Description

userId

String

√*

This parameter is deprecated in API version 2.3 or later.

If you are using API version 2.2 or earlier, this parameter specifies the authoring BlackBerry Dynamics user ID in the BlackBerry Dynamics framework.

gdAuthToken

* Use this parameter if you are using the API version 2.3 or later.

String

√
This parameter specifies the BlackBerry Dynamics authToken that the BlackBerry Connect app retrieves from getGDAuthToken and presents it to BEMS for authentication.
Note: BEMS uses the user identity extracted from the gdAuthToken only.

gdToken

* Use this parameter if you are using the API version 2.2 or earlier.		Strong √This parameter specifies the BlackBerry Dynamics token that the BlackBerry Connect app retrieves from the proxy server and presents it to BEMS for authentication.

deviceToken

String

—

This parameter specifies a unique identifier for the BlackBerry Connect app. If the BlackBerry Connect app doesn't create a deviceToken, the BEMS server creates a GUID token and adds it to the Cookie (deviceToken) on the response to the BlackBerry Connect app.

presence

String

—

This parameter specifies the presence status that is used when the session is initiated (for example, available).

personalMessage

String

—

This parameter specifies the personal message that is set when the session is initiated.

gnpTokenString—This parameter specifies the value of the GNP token. The BlackBerry Connect app retrieves the token from the BlackBerry Dynamics client API and sends it to the BEMS-Connect server for use in push notifications. The BEMS-Connect server confirms the validity of the token with the BlackBerry Proxy server.
pushMaxLengthInteger—This parameter specifies the maximum payload size for the FCM and APNs notifications.
sequenceInteger—This parameter specifies the unique sequence number for tracking purposes.
lastPersistentChatInvitationIdInteger—This parameter specifies the ID of the last persistent chat invitation that was received.

BEMS response and notification

The following table describes the parameters that BEMS returns and the notification sent to the BlackBerry Connect app when a chat session is started.

Parameter

Type

Description

method

String

This parameter returns the invoked method (for example, BeginSession).

stateString This parameter specifies the state of the request to BEMS (for example, Processing or Complete).
sessionidStringThis parameter specifies the session ID for the user.

Code example

The following example sends a request to begin BEMS to begin an instant messaging chat session.

{
 "id":"c12",
 "method":"BeginSession",
 "params":
  {
    "userId":"user1@example.com",
    "gdAuthToken":"thegdauthtokengeneratedbybd",
    "deviceToken":"thetokengeneratedbydevice",
    "presence":"available",
    "personalMessage":"I am available"
  },
 "jsonrpc":"2.0"
}

If the request is successful, BEMS sends the following response to the BlackBerry Connect app and processes the request.

{
 "id":"c12",
 "error":null,
 "result":
 {
   "data":
   {
    "method":"BeginSession",
    "state":"PROCESSING"
   }
 },
"jsonrpc":"2.0",
"background":false
}

If there are no errors, BEMS sends the following notification to the BlackBerry Connect app and the session starts.

{
 "id":"c12",
 "sequence":1018528500000011,
 "result":
  {
    "data":
     {
      "sessionId":"af949a36-b61d-43d7-bb44-aa4c003ddc1a",
      "method":"BeginSession",
      "state":"COMPLETE"
     }
  },
 "jsonrpc":"2.0"
}