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

    Overview

    Bots are automated users in Sendbird Chat that can interact with normal users in group channels. The bot interface is designed on the basis of RESTful principles.

    The Bot API allows you to create a bot with a callback URL to monitor events from users. You can make the bot join channels and send messages to add convenience to users' chat experience. Sendbird Chat doesn't provide artificially intelligent (AI) bots that can function independently of your server-side operations. Processing incoming data and generating relevant responses are under your control.

    You can configure your bot to build helpful, engaging features for your users. The following are some examples:

    • Helper bot: users can ask a helper bot questions and receive immediate answers.
    • GIF search bot: users can search GIFs with a command. For example, typing "/gif cats" returns a list of cat GIFs.
    • Assistant bot: an assistant bot monitors messages in chat rooms and automatically suggests nearby restaurants or venues related to the context of the chat.

    Note: To implement chatbots with Google Dialogflow, see this tutorial.


    Resource representation

    The following table shows the list of properties in a bot resource.

    Property nameTypeDescription

    bot

    nested object

    The information on the bot.

    bot.bot_userid

    string

    The unique ID of the bot.

    bot.bot_nickname

    string

    The bot's nickname.

    bot.bot_profile_url

    string

    The URL of the bot's profile image.

    bot.bot_type

    string

    The bot's type that indicates its category.

    bot.bot_token

    string

    An opaque string that identifies the bot. This token should be added to all requests sent to bot_callback_url to verify that they come from Sendbird server.

    bot.bot_metadata

    object

    One or more key-value pair items which store additional bot information like a user metadata. For more information, see user metadata and channel metadata.

    bot_callback_url

    string

    The server URL where the bot is located to receive all events, requests, and data forwarded from an application.

    is_privacy_mode

    boolean

    Indicates whether to only forward messages that meet specific conditions or forward all messages to the bot. If set to true, only messages that start with a "/" or mention the bot_userid are forwarded to the bot. If set to false, all messages are forwarded. This property, which is usually used for privacy concerns, applies to group channels joined by the bot.

    enable_mark_as_read

    boolean

    Indicates whether to mark the bot's message as read upon sending it.

    show_member

    boolean

    Indicates whether to include information about the members of each channel in a callback response.

    channel_invitation_preference

    int

    Indicates whether the bot automatically joins the channel when invited or joins the channel after manually accepting an invitation using the API. The value of 0 indicates an automatic entrance, while the value of 1 indicates an entrance upon accepting an invitation. (Default: 0)


    Bot callback URL requirements

    The following are the requirements for your bot callback URL:

    • Your URL is required to handle POST requests with application/json; charset=utf8 type.
    • Your URL is required to return a 200 OK HTTP code if you successfully receive a callback. Otherwise, Sendbird server calls your URL several times until it gets a 200 OK.
    • For security reasons, we recommend that you use an SSL server.

    Bot callback JSON body

    Property nameTypeDescription

    category

    string

    The type of the bot notification. The only valid value is bot_message_notification.

    app_id

    string

    The unique App ID of the application where the message was sent.

    ts

    long

    The time that the message was sent in Unix milliseconds format. You can use this property to sort messages sent to the bot.

    sender

    nested object

    The user who sent the message.

    bot

    nested object

    The bot that received the message.

    members[]

    array of objects

    An array of users who are members of the channel.

    mentioned[]

    array of strings

    An array of unique IDs of the users mentioned in the message.

    message

    nested object

    The sent message that triggered the callback.

    channel

    nested object

    The group channel where the event occurred.

    {
        "category": "bot_message_notification",
        "ts": 1484623059030,
        "sender": {
            "user_id": "Danielle",
            "nickname": "Zelda",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_42_512px.png",
            "metadata": {
                "location": "Los Angeles",
                "marriage": "N"
            }
        },
        "bot": {
            "bot_userid": "dinner_helper_bot",
            "bot_nickname": "Dinner helper",
            "bot_type": "marketer",
            "bot_profile_url": "https://mealadvisor.com/bots/img/sendbird_03_512px.png",
            "bot_token": "753afa86d980feea00657f040535fe4f73755e05",
            "bot_metadata": {
                "area": "South Korea",
            }
        },
        "members": [
            {
                "user_id": "Leslie",
                "nickname": "Crystal",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_14_512px.png",
                "is_active": true,
                "is_online": true,
                "state": "joined",
                "is_push_enabled": true,
                "unread_message_count": 0,
                "total_unread_message_count": 12,
                "channel_unread_message_count": 4,
                "metadata": {
                    "location": "San Francisco",
                    "marriage": "Y"
                }
            },
            ... # More members of the channel
        ],
        "mentioned": ["Leslie", "Jenna", "Grace", "Jay"],
        "message": {
            "message_id": 273653769,
            "type": "MESG",
            "custom_type": "vote",
            "files": [],
            "text": "Where should we have dinner?",
            "translations": {},
            "data": "",
            "created_at": 1543228763476
        },
        "channel": {
            "name": "Let's ask to Free Meal Advisor!",
            "channel_url": "sendbird_group_channel_24901438_067b75db946bda8b7843617b1f189fbdfd86b768",
            "cover_url": "https://sendbird.com/main/img/cover/cover_05.jpg",
            "channel_type": "group_messaging",
            "custom_type": "chat_with_bot"
        },
        "app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
    

    Actions

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

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

    • It's recommended that the parameter values in API URLs be urlencoded, such as {botuser_id} and {channel_url}.
    ActionHTTP request

    List bots

    GET /bots
    Retrieves a list of all bots within an application.

    View a bot

    GET /bots/{bot_userid}
    Retrieves information on a bot.

    Create a bot

    POST /bots
    Creates a new bot within an application.

    Send a bot message

    POST /bots/{bot_userid}/send
    Sends a bot message to a group channel.

    Update a bot

    PUT /bots/{bot_userid}
    Updates information on a bot.

    Join channels

    POST /bots/{bot_userid}/channels
    Makes a bot join one or more group channels.

    Leave channels

    DELETE /bots/{bot_userid}/channels or bots/{bot_userid}/channels/{channel_url}
    Makes a bot leave one or more group channels.

    Delete a bot

    DELETE /bots/{bot_userid}
    Deletes a bot from an application.