Chat / Platform API
Current version: v3
    Chat Platform API v3
    Chat Platform API
    Chat
    Platform API
    Home
    /
    Chat
    /
    Platform API
    /
    Channel

    Invite as members

    Invites one or more users as members to a group channel. Users can join a group channel immediately 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. See this page to learn more about channel types.

    Note: By default, blocked users are included when sending invitations. If you wish to exclude blocked users, contact our sales team.


    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 nameTypeDescription

    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
    RequiredTypeDescription

    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.

    OptionalTypeDescription

    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.

    {
        "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.