Bot Interface

Bots are special users in SendBird who send and receive messages autonomously. The bots can exchange messages with normal users in Group Channel (but not supported in Open Channel yet). The bot interface is designed to be RESTful.

You can build interesting features for your users with the Bot API. Below are some examples:

  • Helper Bot: users can ask a Helper Bot questions to receive immediate answers.
  • GIF Search Bot: users can search GIFs with a magic verb. (for example, "/gif cats")
  • Assistant Bot: an Assistant Bot monitors all messages in chat rooms and automatically suggests nearby restaurants or venues related to chat contexts.

Our bot API does not provide artificially intelligent bots that can chat with your users. Rather, it provides an interface that largely does two things within SendBird: first, it allows you to create a bot with a Callback URL to monitor events from users; and second, it allows you to have bots join channels and send messages. It is up to you to process incoming data and generate relevant responses.

As this is one of SendBird's Premium Features, please contact our sales team for further assistance.

  • 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, the SendBird server calls your URL several times until it gets a 200 OK.
  • For security reasons, we recommend you to use SSL.
Property name Type Description
category string The type of bot notification. Currently, only "bot_message_notification" is available.
sender nested object The user who sent the message.
bot nested object The bot who received the message.
ts long The timestamp of this message, in Unix milliseconds format. You can use this field to sort messages sent to your bot.
app_id string The App ID of the application in which the message was sent.
members list A list of the user who are members of the channel.
mentioned list A list of usernames mentioned in this message.
message nested object The sent message that triggered the callback.
channel nested object The channel in which the event occurred.
Callback body example
{
    "category": "bot_message_notification",
    "sender": {
        "nickname": "Kevin",
        "user_id": "kev@email.com",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png"
    },
    "bot": {
        "bot_token": "753afa86d980feea00657f040535fe4f73755e05",
        "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
        "bot_nickname": "Helper Bot",
        "bot_userid": "helper_bot"
    },
    "ts": 1484623059030,
    "app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "members": [
        {
            "unread_message_count": 0,
            "user_id": "kev@email.com",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
            "is_online": true,
            "nickname": "Kevin",
            "is_push_enabled": true
        },
        {
            "unread_message_count": 2,
            "user_id": "helper_bot",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
            "is_online": false,
            "nickname": "Helper Bot",
            "is_push_enabled": true
        }
    ],
    "mentioned": [],
    "message": {
        "files": [],
        "text": "Where should we have dinner?",
        "data": "",
        "translations": {}
    },
    "channel": {
        "channel_type": "group_messaging",
        "channel_url": "sendbird_group_channel_24901438_067b75db946bda8b7843617b1f189fbdfd86b768",
        "name": "Chat with Kevin",
        "cover_url": "https://sendbird.com/main/img/cover/cover_05.jpg"
    }
}
Property name Type Description
bot_userid string The unique ID of the bot.
bot_nickname string The bot's nickname.
bot_profile_url string The URL of the bot's profile image.
bot_callback_url string The bot server URL to which all events, requests, and data from an application are forwarded. For security reasons, it is highly recommended that you use an SSL URL.
is_privacy_mode boolean If true, only messages that start with a '/' or mention the bot_userid is forwarded to the bot. When false, all messages in the channel are forwarded.
enable_mark_as_read boolean Whether the bot marks a message as read upon sending it.
show_member boolean Whether to include member information in the callback response body.
bot_token string A bot_token is added in all requests sent to bot_callback_url to help you verify that each request is from SendBird.
  • API endpoints are relative to the allocated base URL for your app. In this section, the /bots endpoint refers to https://{regi_identifier}.sendbird.com/v3/bots.

Note: If you want region_identifier for your app, sign in to the SendBird Dashboard, select the application, open the Overview, and see the App Credentials > API URL.

Action HTTP request Description
Create a bot POST /bots Creates a new bot.
List bots GET /bots Returns a list of all bots.
View the bot GET /bots/{bots_userid} Returns the information of a bot.
Update the bot PUT /bots/{bots_userid} Updates the information of a bot.
Delete the bot DELETE /bots/{bot_userid} Deletes the bot.
Join channels POST /bots/{bot_userid}/channels Makes the bot join group channels.
Send message from bot POST /bots/{bots_userid}/send Sends a message from the bot to a group channel.
Leave channels DELETE /bots/{bot_userid}/channels or DELETE /bots/{bot_userid}/channels/{channel_url} Makes the bot leave joined group channels.

Create a bot

Creates a new bot within the application. Creating a bot is similar to creating a normal user, except that a callback URL is specified in order for the bot to receive events.

Note: The bot must join a channel first to interact with users. An alternative method is to invite a bot through the Group Channel API.

POST https://{region_identifier}.sendbird.com/v3/bots
Property name Type Description
bot_userid string The unique ID of the bot. The length is limited to 80 bytes.
bot_nickname string The bot's nickname. The length is limited to 80 bytes.
bot_profile_url string The URL of the bot's profile image. The size is limited to 2,048 bytes.
bot_callback_url string The bot server URL to which all events, requests, and data from an application are forwarded. For security reasons, it is highly recommended that you use an SSL URL. The length is limited to 1,024 bytes.
is_privacy_mode boolean If true, only messages that start with a '/' or mention the bot_userid is forwarded to the bot. When false, all messages in the channel are forwarded.
enable_mark_as_read (optional) boolean Whether the bot marks a message as read upon sending it. (Default: true)
show_member (optional) boolean Whether to include member information in the callback response body. (Default: false)
Request body example
{
    "bot_userid": "helper_bot",
    "bot_nickname": "Helper Bot",
    "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
    "bot_callback_url": "https://yourdomain.com/sendbird_bot",
    "is_privacy_mode": false
}

Returns a bot representation.

Status: 200 OK
{
    "bot_callback_url": "https://yourdomain.com/sendbird_bot",
    "bot": {
        "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
        "bot_token": "753afa86d980feea00657f040535fe4f73755e05",
        "bot_nickname": "Helper Bot",
        "bot_userid": "helper_bot"
    },
    "enable_mark_as_read": true,
    "is_privacy_mode": false,
    "show_member": false
}

List bots

Returns a list of all bots within an application.

GET https://{region_identifier}.sendbird.com/v3/bots
Status: 200 OK
{
    "bots": [
        {
            "bot_callback_url": "https://yourdomain.com/sendbird_bot",
            "bot": {
                "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_2_512px.png",
                "bot_token": "ec3111475090bee6aa87afcfcfb6797d2cfa60df",
                "bot_nickname": "Gif Bot",
                "bot_userid": "gif_bot"
            },
            "enable_mark_as_read": true,
            "is_privacy_mode": false,
            "show_member": false
        },
        {
            "bot_callback_url": "https://yourdomain.com/sendbird_bot",
            "bot": {
                "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
                "bot_token": "753afa86d980feea00657f040535fe4f73755e05",
                "bot_nickname": "Helper Bot",
                "bot_userid": "helper_bot"
            },
            "enable_mark_as_read": true,
            "is_privacy_mode": false,
            "show_member": false
        },
        {
            "bot_callback_url": "http://a048c842.ngrok.io/",
            "bot": {
                "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
                "bot_token": "b42dc24c568715507b4a21ebf04bbaa1979e6c55",
                "bot_nickname": "Happy Bot",
                "bot_userid": "happy_bot"
            },
            "enable_mark_as_read": true,
            "is_privacy_mode": false,
            "show_member": true
        }
    ],
    "next": ""
}
Property name Type Description
bots[] list A list of bots.
next string The token for the next chunk of results.

View the bot

Returns the bot's information.

GET https://{region_identifier}.sendbird.com/v3/bots/{bot_userid}

Returns a bot representation.

Status: 200 OK
{
    "bot_callback_url": "https://yourdomain.com/sendbird_bot",
    "bot": {
        "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
        "bot_token": "753afa86d980feea00657f040535fe4f73755e05",
        "bot_nickname": "Helper Bot",
        "bot_userid": "helper_bot"
    },
    "enable_mark_as_read": true,
    "is_privacy_mode": false,
    "show_member": false
}

Update the bot

Updates the bot's information.

PUT https://{region_identifier}.sendbird.com/v3/bots/{bot_userid}
Property name Type Description
bot_nickname (optional) string The bot's nickname. The length is limited to 80 bytes.
bot_profile_url (optional) string The URL of the bot's profile image. The length is limited to 2,048 bytes.
bot_callback_url (optional) string The bot server URL to which all events, requests, and data from an application are forwarded. For security reasons, it is highly recommended that you use an SSL URL. The length is limited to 1,024 bytes.
is_privacy_mode (optional) boolean If true, only messages that start with a '/' or mention the bot_userid is forwarded to the bot. When false, all messages in the channel are forwarded.
enable_mark_as_read (optional) boolean Whether the bot marks a messages as read upon sending it.
show_member (optional) boolean Whether to include member information in the callback response body.
Request body example
{
    "is_privacy_mode": false,
    "enable_mark_as_read": false,
    "show_member": true
}

Returns a bot representation.

Status: 200 OK
{
    "bot_callback_url": "https://yourdomain.com/sendbird_bot",
    "bot": {
        "bot_profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
        "bot_token": "753afa86d980feea00657f040535fe4f73755e05",
        "bot_nickname": "Helper Bot",
        "bot_userid": "helper_bot"
    },
    "enable_mark_as_read": false,
    "is_privacy_mode": false,
    "show_member": true
}

Delete the bot

Deletes the bot from the application.

DELETE https://{region_identifier}.sendbird.com/v3/bots/{bot_userid}
Status: 200 OK
{}

Join channels

Makes the bot join group channel(s).

POST https://{region_identifier}.sendbird.com/v3/bots/{bot_userid}/channels
Property name Type Description
channel_urls list A list of the URLs of the channels to join. Multiple URLs are separated with commas.
Request body example
{
    "channel_urls": ["sendbird_group_channel_24896181_cd8b2c7208536b61895fff76ab6649d76302ee81", "sendbird_group_channel_24896191_8c75a3fd58f77fa3ab4aa256a9bf83a536b43ec7"]
}

Returns the newly joined channels.

Status: 200 OK
{
    "channels": [
        {
            "name": "Engineering Team",
            "custom_type": "",
            "channel_url": "sendbird_group_channel_24896181_cd8b2c7208536b61895fff76ab6649d76302ee81",
            "created_at": 1484036619,
            "cover_url": "",
            "data": ""
        },
        {
            "name": "Sales Team",
            "custom_type": "",
            "channel_url": "sendbird_group_channel_24896191_8c75a3fd58f77fa3ab4aa256a9bf83a536b43ec7",
            "created_at": 1484036640,
            "cover_url": "",
            "data": ""
        }
    ]
}

Send message from bot

Sends a message from the bot to a channel.

POST https://{region_identifier}.sendbird.com/v3/bots/{bot_userid}/send
Property name Type Description
message string The message sent by the bot.
data data Additional data stored within a message. This can be structured data such as a JSON object.
channel_url string The channel in which the message is sent.
Request body example
{
    "message":"Hello John, here is an answer to your question.",
    "channel_url":"sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
    "data":""
}

Returns a message.

Status: 200 OK
{
    "message": {
        "created_at": 1484615590526,
        "user": {
            "nickname": "Happy Bot",
            "user_id": "happy_bot",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png"
        },
        "custom_type": "",
        "data": "",
        "message": "Hello John, here is an answer to your question.",
        "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
        "type": "MESG",
        "message_id": 645633580
    }
}

Leave channels

Makes the bot leave joined group channel(s).

// When leaving all joined group channels.
DELETE https://{region_identifier}.sendbird.com/v3/bots/{bot_userid}/channels

// When leaving a joined group channel by channel url.
DELETE https://{region_identifier}.sendbird.com/v3/bots/{bot_userid}/channels/{channel_url}
Status: 200 OK
{}