Skip Navigation
  1. BlackBerry Docs
  2. BlackBerry Enterprise Mobility Server 3.8
  3. BlackBerry Connect messaging APIs
  4. Instant messaging methods
  5. METHOD_BeginSession

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.
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 
Good Proxy
 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.
gnpToken
String
—
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.
pushMaxLength
Integer
—
This parameter specifies the maximum payload size for the FCM and APNs notifications. 
sequence
Integer
—
This parameter specifies the unique sequence number for tracking purposes. 
lastPersistentChatInvitationId
Integer
—
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).
state
String 
This parameter specifies the state of the request to 
BEMS
 (for example, Processing or Complete).
sessionid
String
This 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"
}