METHOD_PC_CreateRoom

This method creates a group discussion.

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

Parameter	Type	Required	Description
name	String	√	This parameter specifies the discussion group name. Discussion group names can be a maximum of 256 alphanumeric, numeric, special characters or a combination of these. This includes spaces.
description	String	—	This parameter specifies a description of the group discussion and can be a maximum of 256 characters. This includes spaces.
category	String	—	This parameter specifies the ID of the category that the group discussion is placed under. If the category is not specified, a default category must be defined in the BEMS dashboard. The user must be granted Creator role in the group discussion category to create group discussions.
privacy	String	—	This parameter specifies the security level of a group discussion.
managers	String Array	—	This parameter specifies a list of users that can manage the group discussion. Each group discussion must have a minimum of one manager. Managers are automatically added as members to the group discussion. Individual users and Active Directory user groups can be set as managers of a group discussion.
members	String Array	—	This parameter specifies a list of users that have joined the group discussion and can participate in and receive notifications. Individual users and Active Directory user groups can be set as managers of a group discussion.
skipInvitations	Boolean	—	This parameter specifies if an invitation is sent. By default, this parameter is set to False. If true, an invitation is not sent. If false, an invitation is inherited from the category parameter.
follow	Boolean	—	This parameter specifies if a group discussion should be followed. By default, the follow parameter is false. If true, the group discussion should be followed. If false, the group discussion isn't required to be followed.

Notification

The following table describes the notifications that

BEMS

might send to the

BlackBerry Connect

app after it processes the request.

Group discussion creation can succeed while other operations like setting group discussion members, managers and privacy setting can be unsuccessful. The METHOD_PC_CreateRoom API method returns success if the group discussion creation is successful. For more information about subsequent operations and error messages, see InnerError below.

Parameter	Type	Description
roomName	String	This parameter specifies the name of the group discussion.
roomId	String	This parameter specifies the ID of the group discussion.
innerError	Json Array	This parameter specifies an array of error messages that might occur when updating group discussion members, managers, and privacy settings. See InnerError below for more information.

InnerError

InnerError errors might occur when a method is multifunctional (for example, create room and automatically follow the room). The following errors might occur when updating members, managers, and privacy settings for a group discussion:

Name of group discussion is used by another group discussion. Group discussions must be unique.

The manager or member being added is not a valid instant messenger user.

The manager or member specified is not allowed to be a manager or member as per the category specification.

The user does not have permissions to create a group discussion in the category.

The following table describes the parameters that are included for innererrors.

Parameter	Type	Description
type	String	This parameter specifies the error type.
parameter	String	This parameter specifies the parameter name if the error is caused by an input parameter. This is optional.
errorValues	String Array	This parameter specifies a list of invalid values. This is optional.
message	String	This parameter specifies the error message.

Code example

The following example sends a request to

BEMS

to create a group discussion called 'Surprise retirement celebration' and include user1 and user2 as managers and user3 and user4 as members.

{
  "method":"pc.CreateRoom",
  "params":
   {
    "name":"Surprise retirement celebration",
    "managers":[ "sip:user1@example.com", "sip:user2@example.com" ],
    "members":[ "sip:user3@example.com", "sip:user4@example.com" ]
   },
  "id":"c5",
  "jsonrpc":"2.0"
}

If the request is successful,

BEMS

sends the following response to the

BlackBerry Connect

app and processes the request.

{
  "id":"c5",
  "error":null,
  "result":
   {
    "data":
    {
      "method":"pc.CreateRoom",
      "state":"PROCESSING"
    }
   },
  "jsonrpc":"2.0"
}

If there are no errors,

BEMS

sends the following notification to the

BlackBerry Connect

client and creates the group discussion and sends invitations to the contacts.

{
  "id": "c5",
  "sequence": 1018690500000007,
  "result": 
    {
     "data": 
      {
       "roomId":"ma-chan://gems.sw.rim.net/3346c2de-6cc7-4186-ad62-0e5e33b889ed",
       "roomName":"Room@15May2019",
       "method":"pc.CreateRoom",
       "state":"COMPLETE"
      }
    },
   "jsonrpc":"2.0"
}, 
{
  "id": "S12",
  "sequence":1018690500000008,
  "result": 
    {
      "data": 
       {
         "numberOfParticipants":0,
         "roomId":"ma-chan://gems.sw.rim.net/3346c2de-6cc7-4186-ad62-0e5e33b889ed",
         "roomName":"Room@15May2019",
         "roomDescription":"",
         "invitationId":52,
         "method":"pc.InvitationReceived",
         "state":"COMPLETE"
       }
    },
  "jsonrpc":"2.0"
}

If error messages are returned,

BEMS

sends the following notification to the

BlackBerry Connect

client and the group discussion isn't created. In this example an error occurred when the updating the group and an incorrect privacy was specified.

{
  "id":"c5",
  "sequence":1018690500000006,
  "result":
   {
    "data":
    {
      "method":"pc.CreateRoom",
      "roomName":"Surprise retirement celebration",
      "roomId":"ma-chan://gems.sw.rim.net/79b523a6-c78b-4cec-be33-4c2f14ce1438",
          "innerError":[
              {
                "type":"updateError",
                “message”:“Error while updating room +[Exception Message]”
              },
              {
                 "type":"parameterError",
                 "parameter":"privacy"
                 "errorValues":["public"],
                 "message":"Invalid room privacy +[Exception Message]"
              }
           ]
   }
  },
  "jsonrpc":"2.0"
}