/ Platform API
Platform API
    Chat Platform API v3
    Chat Platform API
    Chat Platform API
    Version 3

    Invite as members

    Copy link

    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

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

    Parameters

    Copy link

    The following table lists the parameters that this action supports.

    Required
    Parameter nameTypeDescription

    channel_url

    string

    Specifies the URL of the channel.


    Request body

    Copy link

    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.

    inviter_id

    string

    Specifies the ID of a user who invites other users to the channel. The inviter isn't automatically registered to the channel as a member, so you should specify the ID of the inviter in the user_ids property if needed.

    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"
        },
        "inviter_id": "Jeff"
    }
    

    Response

    Copy link

    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,
        "inviter": "Jeff",
        "member_count": 4,
        "joined_member_count": 3,
        "members": [
            {
                "user_id": "Chris",
                "nickname": "Sportsman",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_23_512px.png",
                "is_active": true,
                "is_online": true,
                "last_seen_at": 0,
                "state": "invited",
                "role": "",             // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
                "metadata": {
                    "font_preference": "times new roman",
                    "font_color": "black"
                }
            },
            {
                "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": {
                    "font_preference": "times new roman",
                    "font_color": "black"
                }
            },
            {
                "user_id": "Jeff",
                "nickname": "OldBoy",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_22_512px.png",
                "is_active": true,
                "is_online": true,
                "last_seen_at": 0,
                "state": "",
                "role": "operator",     // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
                "metadata": {
                    "font_preference": "times new roman",
                    "font_color": "black"
                }
            },
            {
                "user_id": "Justin",
                "nickname": "Knight",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_08_512px.png",
                "is_active": true,
                "is_online": false,
                "last_seen_at": 1530237133254,
                "state": "invited",
                "role": "",             // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
                "metadata": {
                    "font_preference": "times new roman",
                    "font_color": "black"
                }
            }
        ],
        "operators": [
            {
                "user_id": "Jeff",
                "nickname": "OldBoy",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_22_512px.png",
                "is_active": true,
                "is_online": true,
                "last_seen_at": 0,
                "state": "",
                "metadata": {}
            }
        ],
        "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.