Create Channel

Create Channel

POST https://api.talkplus.io/v1.4/api/channels/create

• You can enter up to 5 key-value pairs in data field. The maximum size of key is 128 characters and the maximum size of value is 1024 characters. Both key and value must be strings.

Headers

Name	Type	Description
content-type	string	application/json
app-id*	string	App ID
api-key*	string	App API key

Request Body

Name	Type	Description
name	string	channel name
ownerId	string	channel owner (if unspecified, channel can be modified only through REST API)
type*	string	channel type (private, public, invitationOnly...)
channelId	string	If empty, server will generate a random ID
reuseChannel	boolean	read docs below
invitationCode	string	Required if channel type is 'invitationOnly'
members	array	Array of user IDs (string). Channel owner added by default.
imageUrl	string	Channel image URL
data	object	key-value data
maxMemberCount	integer	maximum number of members allowed. - super channel: default: -1 (unlimited), min: 1, max: 100. - the rest: default: 100, min: 1, max: 100
hideMessagesBeforeJoin	boolean	whether to hide from new member messages that were sent before new member joining
category	string	used as filter during search. max length: 32 characters
subcategory	string	extra filter used along with category. max length: 32 characters

200

{
  "channel": {
    "id": "channel123",
    "name": "MyFirstChannel",
    "ownerId": "user123",
    "type": "private",
    "imageUrl": "image url",
    "invitationCode": "",
    "isFrozen": false,
    "hideMessagesBeforeJoin": false,
    "category": "",
    "subcategory": "",
    "privateTag": "",
    "privateData": "",
    "memberCount": 2,
    "maxMemberCount": 100,
    "data": {
      "someMetaKey1": "someMetaValue1",
      "someMetaKey2": "someMetaValue2"
    },
    "members": [
      {
        "id": "user123",
        "username": "john",
        "profileImageUrl": "http://cnd.test.com/123.jpg",
        "data": {},
        "memberInfo": {},
        "lastReadAt": 1583924400,
        "lastSentAt": 1583924400,
        "updatedAt": 1583924400,
        "createdAt": 1583921400
      },
      {
        "id": "user456",
        "username": "james",
        "profileImageUrl": "http://cnd.test.com/456.jpg",
        "data": {},
        "memberInfo": {},
        "lastReadAt": 1583924400,
        "lastSentAt": 1583924400,
        "updatedAt": 1583924400,
        "createdAt": 1583921400
      }
    ],
    "mutedUsers": [],
    "bannedUsers": [],
    "updatedAt": 1583924400,
    "createdAt": 1583921400,
    "unreadCount": 0,
    "lastReadAt": 0,
    "lastMessage": null
  }
}

500 Error Response

{
  "error": true,
  "code": "1006",
  "message": "Unauthorized"
}

• Supported channel types are follows: private, public, invitationOnly, broadcast, super_broadcast, super_public and super_private.

• type and members fields are required.

• invitationCode field is required for invitationOnly channel type.

Type	Value	Can Join Channel	FCM Support
PRIVATE	private	X	O
PUBLIC	public	O	O
INVITATION ONLY	invitationOnly	O (need Invitation Code)	O
BROADCAST	broadcast	O	O
SUPER_BROADCAST	super_broadcast	O	X
SUPER_PRIVATE	super_private	O	X
SUPER_PUBLIC	super_public	O	X

• For private channel, setting reuseChannel to true allows you to reuse existing channel if channel ID and member IDs match those of existing channel and members. This feature is useful when implementing 1:1 chat.

• Anyone can join a public channel, except for banned users.

• For invitationOnly channel, invitationCode field is required.

• For broadcast and super_broadcast channel:

  • When the channel owner sends a message, the message is sent to all channel members.

  • When a channel member other than the channel owner sends a message, the message is sent only to the channel owner.

• For super_broadcast, super_private and super_public channel:

  • You can set the maximum number of members above 100.

  • Set the maximum member limit to -1 allows unlimited members.

  • super channel returns empty members , bannedUsers and mutedUsers fields

  • unreadCount, invitationCode, lastReadAt fields are not supported.

  • FCM push notifications are not sent since there can be too many users and notifications.

super channel example

{
  "channel": {
    "id": "channel123",
    "name": "MyFirstChannel",
    "ownerId": "user123",
    "type": "private",
    "imageUrl": "image url",
    "invitationCode": "",
    "isFrozen": false,
    "hideMessagesBeforeJoin": false,
    "category": "", 
    "subcategory": "",
    "privateTag": "",
    "privateData": "",
    "memberCount": 2,
    "maxMemberCount": 100,
    "data": {
      "someMetaKey1": "someMetaValue1",
      "someMetaKey2": "someMetaValue2"
    },
    "updatedAt": 1583924400,
    "createdAt": 1583921400,
    "unreadCount": 1,
    "lastReadAt": 1583914400,
    "lastMessage": {
      "id": "sdf2l5s9j",
      "channelId": "channel123",
      "userId": "user456",
      "username": "myUsername",
      "profileImageUrl": "http://cdn.test.com/123.jpg",
      "type": "message",
      "text": "Hello world",
      "data": {
        "customField": "customData"
      },
      "parentMessage": {},
      "reactions": {"happy": ["user1"]},
      "createdAt": 1583921400
    }
  }
}