Invite as members

Invites one or more users as members to a group channel. See this page to learn more about channel types.

Note: Users can join a group channel right after receiving an invitation, without having to accept it. To give users an option to accept or decline an invitation, see update default channel invitation preference or update channel invitation preference.

HTTP request

POST https://api-{application_id}.sendbird.com/v3/group_channels/{channel_url}/invite

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
channel_url	string	Specifies the URL of the channel.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Required	Type	Description
user_ids[]	array of strings	Specifies an array of one or more user IDs to invite to the channel. Up to 100 users can be invited at a time. The `users` property can be used instead of this property.
users[]	array of objects	Specifies a list of one or more `JSON` objects containing the `user_id` property to invite to the channel. Up to 100 users can be invited at a time. The `user_ids` property can be used instead of this property.

Optional	Type	Description
invitation_status	object	Specifies one or more `key-value` pair items which set the invitation status of each user invited to the channel. Each key-value pair should be specified with the invited user's ID, a colon (:), and the user’s invitation status (for example, `user_id_1: invitation status`). Acceptable values are joined, invited_by_friend, and invited_ by_non_friend. (Default: joined)
hidden_status	object	Specifies one or more `key-value` pair items which set the channel's hidden status for each user. The value in `hidden_status` determines whether to hide the channel from the user's channel list. Each key-value pair should be specified with the invited user's ID, a colon (:), and the channel's hidden status (for example, `user_id_1: channel hidden status`). Acceptable values are the following: - unhidden (default): the channel is shown when a user's channel list is retrieved. - hidden_allow_auto_unhide: if a new message is sent to a hidden channel, the channel automatically reappears on a user's channel list. - hidden_prevent_auto_unhide: the channel doesn't reappear on a user's channel list even when a new message is sent to that channel.

user_idsusers

# Request body example
{
    "user_ids": ["Fluo", "Justin", "Chris"],
    "invitation_status": {
        "Fluo": "invited_by_friend",
        "Justin": "invited_by_non_friend"
    },
    "hidden_status": {
        "Chris": "hidden_allow_auto_unhide"
    }
}

Response

If successful, this action returns a group channel resource in the response body.

Status: 200 OK

{
    "name": "Saturday soccer members",
    "channel_url": "private_chat_room_424",
    "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
    "custom_type": "sports",
    "unread_message_count": 0,
    "data": "",
    "is_distinct": true,
    "is_public": false,
    "is_super": false,
    "is_ephemeral": false,
    "is_access_code_required": false,
    "hidden_state": "hidden_allow_auto_unhide", // This shows the channel hidden status of the inviter.
    "member_count": 3,
    "joined_member_count": 3,
    "members": [
        {
            "user_id": "Fluo",
            "nickname": "Rooster",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
            "is_active": true,
            "is_online": false,
            "friend_discovery_key": ["543-098-4567", "010-4567-6543"],
            "last_seen_at": 1530232836311,
            "state": "joined",
            "role": "",         // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "location": "New York",
                "marriage": "Y"
            }
        },
        {
            "user_id": "Justin",
            "nickname": "Knight",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_08_512px.png",
            "is_active": true,
            "is_online": false,
            "friend_discovery_key": ["789-012-7834", "010-1245-3658"],
            "last_seen_at": 1530237133254,
            "state": "invited",     // 'invited_by_friend'
            "role": "",             // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "location": "Tokyo",
                "marriage": "N"
            }
        },
        {
            "user_id": "Chris",
            "nickname": "Sportsman",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_23_512px.png",
            "is_active": true,
            "is_online": true,
            "friend_discovery_key": ["357-642-1369", "010-4030-1357"],
            "last_seen_at": 0,
            "state": "invited",     // 'invited_by_non_friend'
            "role": "",             // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "location": "Chicago",
                "marriage": "N"
            }
        }
    ],
    "operators": [
        {
            "user_id": "Jeff",
            "nickname": "OldBoy",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_22_512px.png",
            "metadata": {
                "location": "Seoul",
                "marriage": "Y"
            }
        }
    ],
    "max_length_message": 500,
    "last_message": null,
    "created_at": 1543468122,
    "freeze": false,
    "channel": {
        ...  # This key has been deprecated and only exists for backward compatibility.
    }
}

In the case of an error, an error object is returned. A detailed list of error codes is available here.