Group chat

Method available at: /gch.ashx

This method allows you to create, edit and delete a group and send messages to all group participants. This method contains two parameters: gm and pm. The gm parameter describes the name of the method, while the pm parameter describes the parameters of a given method. The following methods are available in group chat: addGroup, editGroup, delGroup, getGroup, joinGroup, leaveGroup, addMember, delMember, sendMessage

Authorization

The method requires authorization using basic authentication. Please use your SIP account login and password.

List of supported methods

Method description:

Adding group

Parameters

{
  "gs": "Group name",
  "dn": "48500100200",
  "gm": [
        {
          "l" : "1000005",
          "dn": "48600500600"
        },
        {
          "l" : "1000001",
          "dn": "vippie ID"
        }
    ]
}

Return value

• If successful, we will receive a JSON object containing the "id" parameter containing the group ID (type integer unsigned), example: {"id":84278}. However, all participants will receive a SIP message with the following content: ~[GC M:'NG' GID:84278 MID:9214] where: in M we have the message type NG - New Group in GID we have the group ID and in MID the ID of the given message is given .

• If an error occurs on the server or any of the parameters contain an incorrect value, the method will return the appropriate 3-digit error code shown below:

  Code	Description
  400	Incorrect parameters - one of the parameters was not provided
  443	Too many participants. (Currently the maximum number of participants is 30)
  500	Internal server error

Group download

Parameters

{
  "id":84278
}

Return value

• If successful, we will receive a JSON object containing the topic of the gs group, the creator of the group go, information whether the group's avatar exists ae (it can take the values "1" - exists or "0" - does not exist), date and time of updating the avatar at, information whether the group's video there is ve, date and time of avatar update vt, date and time of creating the ts group, list of gm participants which includes parameters such as: l - sip login, a - whether the participant is the group administrator, dn - display name, s - current status where: j - joined, w - waiting, l - left and ts - date and time of changing the status and the gg guest list, which contains parameters such as l - login, dn - display name and ts - date and time of joining the group. Example:

  {
    "gs": "Group name2",
    "go": "1377601",
    "ts": "2014-03-17T18:08:20",
    "ae": "0",
    "at": "2015-07-06T10:02:60",
    "ve": "0",
    "vt": "2015-07-06T10:02:60"
    "gm": [
          {
            "l" : "1000685",
            "a" : false,
            "dn": "48600316058",
            "s" : "w",
            "ts": "2014-03-17T18:08:20"
          },
          {
            "l" : "1377601",
            "a" : true,
            "dn": "48502159212",
            "s" : "j",
            "ts": "2014-03-17T18:08:20"
          },
          {
            "l" : "1395611",
            "a" : true,
            "dn": "48500100100",
            "s" : "l",
            "ts": "2014-03-17T22:39:50"
          }
      ],
    "gg": [
           {
            "l" : "48500103102",
            "dn": "48500103102",
            "ts": "2014-03-17T22:39:50"
          }
      ]
  }
  

• If an error occurs on the server or any of the parameters contain an incorrect value, the method will return the appropriate 3-digit error code shown below:

  Code	Description
  400	Incorrect parameters - one of the parameters was not provided
  444	The specified group does not exist or the user is not a member of this group.
  500	Internal server error

Downloading common groups for the selected user

Parameters

{
  "l": string
}

Return value

• If successful, we will receive an array JSON object containing the group topic gs, the creator of the group go, information whether the group avatar exists ae (can take the values "1" - exists or "0" - does not exist), date and time of updating the avatar at, date and time creating a ts group. Example:

  [
   {
    "id": 101,
    "gs": "Tamet grupy 101",
    "ts": "2016-08-01T18:08:20",
    "ae": "0",
    "at": "2015-08-06T10:02:60"
   }
  ]

• If an error occurs on the server or any of the parameters contain an incorrect value, the method will return the appropriate 3-digit error code shown below:

  Kod	Opis
  400	Incorrect parameters - one of the parameters was not provided
  500	Internal server error

Deleting a group

Parameters

{
    "id": 100,
    "dn": "48500100300"
}

Return value

The method will return the appropriate 3 digit shown below:

Changing the group topic

Parameters

{
  "id": 100,
  "gs": "Nowy temat",
  "dn": "48500100300"
}

Return value

The method will return the appropriate 3 digit shown below:

Joining or leaving a group

Parameters

{
  "id": 100
  "dn": "48500100200"
}

Return value

The method will return the appropriate 3 digit shown below:

Sending a message

Parameters

{
  "id": 100
  "dn": "48500100200",
  "mb": "message text here"
}

Return value

The method will return the appropriate 3 digit shown below:

Confirmation of receipt of the message

Parameters

{
  "id" : 100
  "dn" : "48500100200",
  "mid": 123
}

Return value

The method will return the appropriate 3 digit shown below:

Confirmation that the message has been read

Parameters

{
  "id" : 100
  "dn" : "48500100200",
  "mid": 124
}

Return value

The method will return the appropriate 3 digit shown below:

Deleting the message

Parameters

{
  "id" : 100
  "dn" : "48500100200",
  "mid": 124
}

Return value

The method will return the appropriate 3 digit shown below:

Retrieving information about the message

Parameters

{
  "id" : 100
  "mid": 124
}

Return value

• If successful, we will receive a list of JSON objects containing parameters such as: l - login sip, cf - date of receipt of the message and rd - date of reading the message. The cf and rd parameters are optional. Example:

  [
   {
    "l" : "login1",
    "cf": "2014-03-17T18:08:20",
    "rd": "2014-03-17T18:08:20"
   },
   {
    "l" : "login2",
    "cf": "2013-03-17T18:08:20",
    "rd": ""
   },
   {
    "l" : "login3"
    "cf": "",
    "rd": ""
   }
  ] 

• If an error occurs on the server or any of the parameters contain an incorrect value, the method will return the appropriate 3-digit error code shown below:

  Code	Description
  400	Incorrect parameters - one of the parameters was not provided
  444	The specified group does not exist or the user is not a member of this group.
  500	Internal server error

Removing current group participants

Parameters

{
  "id":  100
  "dn": "48500100200",
  "gm": ["1000002","1002142"]
}

Return value

The method will return the appropriate 3 digit shown below:

Adding new group participants

Parameters

{
  "id":  100
  "dn": "48500100200",
  "gm": [
        {
          "l" : "1000005",
          "dn": "48600500600"
        },
        {
          "l" : "1000001",
          "dn": "vippie ID"
        }
      ]
}

Return value

The method will return the appropriate 3 digit shown below:

Adding or removing group administrator permissions

Parameters

{
  "id":  100
  "dn": "48500100200",
  "gm": ["1000002","1002142"]
}

Return value

The method will return the appropriate 3 digit shown below:

~[GC M:'EG' GID:14231 MID:19241]

Uploading an avatar

The method allows you to upload an avatar to the server. It is important to set the enctype="multipart/form-data" attribute when sending via POST.

Parameters

{
  "id": 84278,
  "dn": "48500100200"
}

Return value

• If successful, we will receive a JSON object containing the date and time the avatar was updated at  Example:

  {
    "at": "2015-07-06T10:02:60"
  }
  

  However, all group participants with the joined status will receive a SIP message with information about editing data in the group

  ~[GC M:'EG' GID:84278 MID:19241]

  where:

  • M - indicates the message type - EG - edit group,
  • GID - stands for group identifier (unsigned 32-bit integer),
  • MID - stands for message identifier (unsigned 64-bit integer)

  The recipient of such a message should download the new group settings using the getGroup method.

  
  

• If an error occurs on the server or any of the parameters contain an incorrect value, the method will return the appropriate 3-digit error code shown below:

  Code	Description
  400	Incorrect parameters - one of the parameters was not provided
  407	Invalid Content-Type header. Currently accepted types are: image/jpeg
  411	Invalid file size. Max. file size is 100KB
  444	The specified group does not exist or the user is not a member of this group.
  500	Internal server error

Avatar download

The method allows you to download an avatar for a given group.

Parameters

{
 "id": 84278,
 "t": "image",
}

Return value

• If the file does not exist on the server, the server will return HTTP status 404 - Not Found

• If successful, we will receive an avatar file in the body

• If an error occurs on the server or any of the parameters contain an incorrect value, the method will return the appropriate 3-digit error code shown below:

  Code	Description
  400	Incorrect parameters - one of the parameters was not provided
  444	The specified group does not exist or the user is not a member of this group.
  500	Internal server error

Downloading video - GET method

To download a video for groupchat, send a GET request to the address /groupchat/{id}/video, where {id} should be replaced by the group identifier . The method requires authorization using basic authentication. Please use your SIP account login and password.

In response we will receive:

• when HTTP status = 200 - we will receive a video stream in the body
• when HTTP status = 404 - Not found

To download a thumbnail for a video, send a GET request to the address /groupchat/{id}/video-thumb, where the group identifier should be substituted for {id}. The method requires authorization using basic authentication. Please use your SIP account login and password.

In response we will receive:

• when HTTP status = 200 - we will get a picture in the body
• when HTTP status = 404 - Not fund

Delete Avatar

The method allows to delete avatar on the server.

Parameters

{
  "id": 84278,
  "dn": "48500100200"
}

Return value

• If successful, we will receive a JSON object containing the date and time the avatar was updated  at  Example:

  {
    "at": "2015-07-06T10:02:60"
  }
  

  However, all group participants with the joined status will receive a SIP message with information about editing data in the group

  ~[GC M:'EG' GID:84278 MID:19241]

  where:

  • M - means message type - EG - edit group
  • GID - stands for group identifier (unsigned 32-bit integer)
  • MID - stands for message identifier (unsigned 64-bit integer)

  The recipient of such a message should download the new group settings using the getGroup method.

  
  

• If an error occurs on the server or any of the parameters contain an incorrect value, the method will return the appropriate 3-digit error code shown below:

  Code	Description
  400	Incorrect parameters - one of the parameters was not provided
  444	The specified group does not exist or the user is not a member of this group.
  500	Internal server error