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

    Polls

    The polls feature provides an easier way to gather feedback from members in a channel. To post a poll in a channel, you must send a message that contains the poll you created. Polls can only be sent with text messages in certain group channels. See the limitations section below to learn more about which type of channels and messages support polls.

    The following are some of the ways that polls can be customized.

    • Allow users to vote for a single option or multiple options.
    • Allow users other than the creator of the poll to add new options.
    • Display a partial list of voters for each option.
    • Add data which can contain additional information such as a supplementary explanation for each poll option in a key-value pair.

    Using polls

    Prerequisite

    To use polls in your Sendbird application, you must activate the feature on Sendbird Dashboard. Go to Settings > Chat > Features and turn on the Polls feature.

    Limitations

    Refer to the following limitations when using polls.

    • The maximum number of options that can be added to a poll differs depending on your Sendbird plan. For further information, contact our sales team.
    • Polls can't be sent in the following message types: file messages, admin messages, and scheduled text messages.
    • Polls are only available in group channels except for ephemeral and Supergroup channels. See channel types to learn more about the different types of group channels.
    • Information on polls isn't included in the export result of the message data that contain polls.

    Resource representation

    The following tables show the list of properties in a poll resource and a poll option resource.

    List of properties in a poll

    Property nameTypeDescription

    id

    integer

    The unique ID of a poll.

    title

    string

    The text of a poll's title.

    options

    array of objects

    An array of options that a user can vote for.

    voter_count

    integer

    The number of voters who casted a vote on a poll.

    created_by

    string

    The unique ID of the user who created a poll.

    status

    string

    The status of a poll. The value can be removed, open, or closed.

    allow_user_suggestion

    boolean

    Indicates whether to allow users other than the creator of the poll to add new options to the poll.

    allow_multiple_votes

    boolean

    Indicates whether to allow users to vote for multiple options.

    created_at

    long

    The time when a poll is created in Unix seconds.

    updated_at

    long

    The time when a poll is updated in Unix seconds.

    close_at

    long

    The time when a poll was closed or will be closed in Unix seconds. If the value of this property is -1, the poll status remains open.

    data

    object

    A JSON object of one or more key-value items to store additional information related to a poll.

    List of properties in a poll option

    Property nameTypeDescription

    poll_id

    integer

    The unique ID of a poll that a poll option belongs to.

    id

    integer

    The unique ID of a poll option. This value is unique within a poll.

    text

    string

    The text that describes a poll option.

    vote_count

    integer

    The number of votes casted on a poll option.

    created_by

    string

    The unique ID of the user who created a poll option.

    created_at

    long

    The time when a poll option is created in Unix seconds.

    updated_at

    long

    The time when a poll option is updated in Unix seconds.

    partial_voter_list

    array of objects

    An array of users who voted for this poll option. Up to ten users can be shown.


    Actions

    The following table shows a list of actions supported for polls. API endpoints are relative to the base URL allocated to your Sendbird application. In this page, the base URL for the following endpoints is https://api-{application_id}.sendbird.com/v3.

    Note: If you want to know the ID and base URL of your application, sign in to Sendbird Dashboard, go to Settings > Application > General, and check the Application ID and API request URL.

    List of actions

    ActionHTTP request

    List polls

    GET /polls
    Retrieves both open and closed polls in the client app.

    Get a poll

    GET /polls/{poll_id}
    Retrieves information on a poll.

    Create a poll

    POST /polls
    Creates a poll.

    Update a poll

    PUT /polls/{poll_id}
    Updates information of a poll.

    Close a poll

    PUT /polls/{poll_id}/close
    Closes a poll.

    Delete a poll

    DELETE /polls/{poll_id}
    Deletes a poll.

    Get a poll option

    GET /polls/{poll_id}/options/{option_id}
    Retrieves an option of a poll.

    Add a poll option

    POST /polls/{poll_id}/options
    Adds an option to a poll.

    Update a poll option

    PUT /polls/{poll_id}/options/{option_id}
    Updates an option in a poll.

    Delete a poll option

    DELETE /polls/{poll_id}/options/{option_id}
    Deletes an option from a poll.

    Cast or cancel a vote

    POST /polls/{poll_id}/vote
    Allows users to cast or cancel their vote.

    List voters of a poll option

    GET /polls/{poll_id}/options/{option_id}/voters
    Retrieves a list of users who voted for an option.