Skip to main content
POST

​
Recipes

1

1. Set a private dialog type

Use a type parameter to set a dialog type. Set it to 3 to create a private dialog.
2

2. Set the ID of the opponent

Use an occupants_ids parameter to set the ID of the opponent who is going to participate in the dialog.
3

3. As a result, the API returns a newly created private dialog.

1

1. Set a public dialog type

Use a type parameter to set a dialog type. Set it to 1 to create a public dialog.
2

2. Set a name of the public dialog

Use a name parameter to set a name for the group dialog.
3

3. Set an avatar for the dialog

You can set an avatar for a public dialog. Just set the ID of the file in the photo field.
4

4. As a result, the API returns a newly created public dialog.

1

1. Set a group dialog type

Set a type parameter to 2 to create a group dialog.
2

2. Set a name of the group dialog

Use a name parameter to set a name for the group dialog.
3

3. Set IDs of opponents

Use an occupants_ids parameter to set a list of opponents IDs who are going to participate in the dialog.
4

4. As a result, the API returns a newly created group dialog.

1

1. Set a type of the dialog

You can set a type of dialog using a type parameter. Here, a group dialog is created since the type is set to 2.
2

2. Set a name of the dialog

Use a name parameter to set a name for the group dialog.
3

3. Set IDs of opponents

Use an occupants_ids parameter to set a list of opponents IDs who are going to participate in the dialog.
4

4. Use a `data` parameter to refer to a custom object that should be added

You need to refer to the specific custom object in the request. See this section to learn how to create a custom object class.The data stores a set of unique keys each having an associated value parameter.
5

5. Set a name of the class

Here, we refer to the ScoreTable custom object class.
6

6. Set custom object fields

Here, we refer to custom object fields of the ScoreTable class.
7

7. As a result, the API returns a newly created dialog with the specified custom parameters.

1

1. Use 'Authorization' header to pass API key

2

2. Use 'On-Behalf-Of' header to pass user id

To execute a request on behalf of a specific user.
3

3. Set a group dialog type

Set a type parameter to 2 to create a group dialog.
4

4. Set a name of the group dialog

Use a name parameter to set a name for the group dialog.
5

5. Set IDs of opponents

Use an occupants_ids parameter to set a list of opponents IDs who are going to participate in the dialog.
6

6. As a result, the API returns a newly created group dialog.

1

1. Use 'Authorization' header to pass API key

2

2. Use 'On-Behalf-Of' header to pass user_id

To execute a request on behalf of a specific user.
3

3. Set a private dialog type

Use a type parameter to set a dialog type. Set it to 3 to create a private dialog.
4

4. Set the ID of the opponent

Use an occupants_ids parameter to set the ID of the opponent who is going to participate in the dialog.
5

5. As a result, the API returns a newly created private dialog.

1

1. Use 'Authorization' header to pass API key

2

2. Use 'On-Behalf-Of' header to pass user_id

To execute a request on behalf of a specific user.
3

3. Set a public dialog type

Use a type parameter to set a dialog type. Set it to 1 to create a public dialog.
4

4. Set a name of the public dialog

Use a name parameter to set a name for the group dialog.
5

5. Set an avatar for the dialog

You can set an avatar for a public dialog. Just set the ID of the file in the photo field.
6

6. As a result, the API returns a newly created public dialog.

1

1. Set dialog type

Use the type parameter to define the dialog type. type=2 creates a GROUP dialog.
2

2. Set dialog name

Use the name parameter to define the name of the group dialog.
3

3. Set occupants IDs

Use the occupants_ids parameter to define users who will participate in the dialog.
4

4. Disable join requirement

Set "is_join_required": 0 to allow users to send and receive messages via XMPP without performing a join operation.
5

5. Result

The API returns a newly created group dialog with is_join_required set to 0.
1

1. Set a group dialog type

Set a type parameter to 2 to create a group dialog.
2

2. Set a name of the group dialog

Use a name parameter to set a name for the group dialog.
3

3. Set IDs of opponents

Use an occupants_ids parameter to set a list of opponents IDs who are going to participate in the dialog.
4

4. Set IDs of admins

Use the admin_ids parameter to set a list of admin IDs who will moderate the dialog.
5

5. As a result, the API returns a newly created group dialog.

1

1. Set a public dialog type

Use a type parameter to set a dialog type. Set it to 1 to create a public dialog.
2

2. Set a name of the public dialog

Use a name parameter to set a name for the group dialog.
3

3. Set an avatar for the dialog

You can set an avatar for a public dialog. Just set the ID of the file in the photo field.
4

4. Set IDs of admins

Use the admin_ids parameter to set a list of admin IDs who will moderate the dialog.
5

5. As a result, the API returns a newly created public dialog.

1

1. Use 'Authorization' header to pass API key

2

2. Use 'On-Behalf-Of' header to pass user id

To execute a request on behalf of a specific user.
3

3. Set a group dialog type

Set a type parameter to 2 to create a group dialog.
4

4. Set a name of the group dialog

Use a name parameter to set a name for the group dialog.
5

5. Set IDs of opponents

Use an occupants_ids parameter to set a list of opponents IDs who are going to participate in the dialog.
6

6. Set IDs of admins

Use the admin_ids parameter to set a list of admin IDs who will moderate the dialog.
7

7. As a result, the API returns a newly created group dialog.

1

1. Use 'Authorization' header to pass API key

2

2. Use 'On-Behalf-Of' header to pass user_id

To execute a request on behalf of a specific user.
3

3. Set a public dialog type

Use a type parameter to set a dialog type. Set it to 1 to create a public dialog.
4

4. Set IDs of admins

Use the admin_ids parameter to set a list of admin IDs who will moderate the dialog.
5

5. Set a name of the public dialog

Use a name parameter to set a name for the group dialog.
6

5. Set an avatar for the dialog

You can set an avatar for a public dialog. Just set the ID of the file in the photo field.
7

6. As a result, the API returns a newly created public dialog.

Use type=1 (PUBLIC_GROUP) to create a public dialog. All users from your application will be able to join it. The server will create a public chat and return a detailed information about the newly created dialog. Field xmpp_room_jid will contain a Chat room JID to which you should connect to start chatting. Use type=2 (GROUP) to create a group dialog only for specific users provided in occupants_ids. The server will create a group chat (involving only members of this chat) and return a detailed information about the newly created dialog. Field xmpp_room_jids will contain a Chat room JID to which you should connect to start chatting. Use type=3 (PRIVATE) to create a private dialog between 2 users. The server will return a detailed information about the newly created dialog. If a user sends a chat message to some user and the private dialog wasn’t created, it will be created automatically with the first chat message. Custom parameters Dialogs can store additional parameters. These parameters can be used to store additional data. Also, these parameters can be used in dialogs retrieval requests. To start using additional parameters, create an additional schema of your parameters. This is a custom objects class. Just create an empty class with all fields that you need. These fields will be your dialog’s additional parameters. Next, to set additional parameters to a dialog, use next additional parameters in a creation request: data[class_name] - should contain Custom Objects class name created above.
data[...]
data[{field_name_N}] - field N from Custom Object class. Admin role overview (added in v2.52.0)
  • Admins are like occupants, but with elevated permissions.
  • Only supported in public and group dialogs (type: 1, type: 2).
  • Users in admin_ids must also be in occupants_ids(group dialog). If not — they will be automatically added.
  • Ignored in private dialogs (type: 3).
Permissions:
  • Rename the dialog
  • Change the photo
  • Edit and delete any messages
  • Remove other occupants (except the owner)
  • Remove themselves from admin_ids

​
Body Parameters

​
integer
required
Type of a new dialog.Possible values are:
1 - PUBLIC_GROUP
2 - GROUP
3 - PRIVATE
​
string
Name of a new dialog.Ignored when type=3 (PRIVATE).The maximum length is 200 symbols.
​
string
Photo of a new dialog.
​
string
IDs of dialog occupants (users who will be able to chat in this dialog). Don’t need to pass current user ID, it will be added automatically. Can be a String or Array of Integers.
​
string
IDs of users with admin permissions in the dialog. Ignored when type=3 (PRIVATE). Admins can update the name and photo, edit or delete any messages, and manage occupants. (added in v2.52.0)
​
integer
Defines whether a user must perform a join operation before sending and receiving messages via XMPP. Applies only to type=2 (GROUP).Possible values:
0 - join not required,
1 - join required.
Default for GROUP dialogs is 0 when the field is not provided. The default value can be configured in the Dashboard → Settings.
Ignored for type=1 (PUBLIC_GROUP) and type=3 (PRIVATE) — if provided in the request, the value is not stored (added in v2.34.0).
​
object

​
Headers

​
string
required
A user or application session token. See our Authentication page to learn more about session tokens. Must be used either QB-Token or Authorization.
​
string
default:"ApiKey {your_api_key}"
API key from Dashboard. Expected format: ApiKey {your_api_key}. Must be used either QB-Token or Authorization.
​
string
User ID. The user ID of the user on whose behalf the request is being made.

​
Responses

A successful response
​
string
​
string
​
string
​
integer
​
string
​
integer
​
string
​
array of integers
​
array of integers (added in v2.52.0)
​
string
​
integer
​
string
​
integer
​
string
​
string
​
integer
An error response
​
array of strings
An error response
​
array of strings
An error response
​
array of strings