Platform API
Bot Interface

Bot Interface

Bots are special users in the SendBird system who send and receive messages autonomously in group channels only. The bots can exchange messages with normal users in the channels. The bot interface is designed on the basis of the RESTful principles.

You can build interesting features for your users with the bot API. The following 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 command. (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.

The SendBird system doesn't provide AI (artificially intelligent) bots that can chat with your users without any further operations from your server-side. Rather, the system provides an interface that you can do two things within it: 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.

This is one of SendBird's premium features, contact our sales team for further assistance.

Resource representation

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_token

string

An opaque string that identifies the bot. This token should be added to all requests sent to the bot_callback_url for verifying that they comes from SendBird server.

bot.bot_metadata

array

An array of key-value pair items which store additional bot information like a user metadata. For more information, see the User Metadata section.

bot_callback_url

string

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

is_privacy_mode

boolean

In the group channels of where the bot is a member, indicates whether to forward all messages to the bot or only forward the messages that meet the specific conditions, for privacy concerns. A value of true indicates that only messages that start with a '/' or mention the bot_userid are forwarded to the bot. A value of false indicates that all messages are forwarded.

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. A value of 1 indicates the automatic entrance, a value of 0 indicates the latter. (Default: 0)

Bot callback URL requirements

  • 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 a bot notification. A value of bot_message_notification is available only.

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 the messages sent to the bot.

sender

nested object

The user who sent the message.

bot

nested object

The bot who received the message.

members[]

list

A list of users who are the members of the channel.

mentioned[]

array

An array of the 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.

Callback body example
Light Color Skin
Copy
{
    "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_token": "753afa86d980feea00657f040535fe4f73755e05",
        "bot_profile_url": "https://mealadvisor.com/bots/img/sendbird_03_512px.png",
        "bot_userid": "helper_bot_for_dinner",
        "bot_nickname": "Dinner helper",
        "metadata": {
            "location": "Meal Advisor",
            "marriage": "N" 
        } 
    },
    "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

  • API endpoints are relative to the base URL allocated to your 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 your dashboard, select the application, open the Overview, and then check the App credentials > App ID, API request URL.

  • It is recommended that the values of the parameters in API URLs, such as {bot_user_id} and {channel_url}, are urlencoded.
ActionHTTP request

List bots

GET /bots
Retrieves a list of all bots.

View a bot

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

Create a bot

POST /bots
Creates a new bot.

Update a bot

PUT /bots/{bot_user_id}
Updates information on the bot.

Join channels

POST /bots/{bot_user_id}/channels
Makes the bot join one or more group channels.

Send a bot's message

POST /bots/{bot_user_id}/send
Sends the bot's message to a group channel.

Leave channels

DELETE /bots/{bot_user_id}/channels or .../channels/{channel_url}
Makes the bot leave one or more group channels.

Delete a bot

DELETE /bots/{bot_user_id}
Deletes the bot from an application.


List bots

Retrieves a list of all bots within an application.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/bots

Parameters

The following table lists the parameters that this action supports.

Parameters
OptionalTypeDescription

token

string

Specifies a token that indicates the starting index of a chunk of results to retrieve. If not specified, the index is set as 0.

limit

int

Specifies the number of bots to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

Response

If successful, this action returns a list of bot resources in the response body like the following.

Status: 200 OK
Light Color Skin
Copy
{
    "bots": [
        {
            "bot": {
                "bot_token": "753afa86d980feea00657f040535fe4f73755e05",
                "bot_profile_url": "https://mealadvisor.com/bots/img/sendbird_03_512px.png",
                "bot_userid": "helper_bot_for_lunch",
                "bot_nickname": "Lunch Helper",
                "metadata": {}
            },
            "bot_callback_url": "https://mealadvisor.com/bots/sendbird/lunch/",
            "enable_mark_as_read": true,
            "is_privacy_mode": false,
            "show_member": false,
            "channel_invitation_preference": 0
        },
        ... # More bots
    ],
    "next": "FdW6RsFRQ1ArRafXA1RcE2d0FUZSUlkJFdeRHB863DAgNn8eDRS3dBNFX11fUlsDRs3E"
}
Property nameTypeDescription

bots[]

list

A list of bots.

next

string

The value for the token parameter to retrieve the next page in the result set.


View a bot

Retrieves information on a bot.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/bots/{bot_user_id}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

bot_user_id

string

Specifies the ID of the bot to retrieve.

Response

If successful, this action returns a bot resource in the response body.


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 group channel first to interact with users. In group channels, you can invite a bot through the invite members action instead.

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.sendbird.com/v3/bots

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

bot_userid

string

Specifies the unique ID of the bot. The length is limited to 80 bytes.

bot_nickname

string

Specifies the bot's nickname. The length is limited to 80 bytes.

bot_profile_url

string

Specifies the URL of the bot's profile image. The size is limited to 2,048 bytes.

bot_callback_url

string

Specifies the server URL where bot is located to receive all events, requests, and data forwarded from an application. For security reasons, it is highly recommended that you use an SSL server. The length is limited to 1,024 bytes.

is_privacy_mode

boolean

In the channels of where the bot is a member, determines whether to only forward the messages with the specific conditions to the bot or forword all messages to the bot, for privacy concerns. 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.

OptionalTypeDescription

enable_mark_as_read

boolean

Determines whether to mark the bot's message as read upon sending it. (Default: true)

show_member

boolean

Determines whether to include information about the members of each channel in a callback response. (Default: false)

channel_invitation_preference

int

Determines whether the bot automatically joins the channel when invited or joins the channel after manually accepting an invitation using the API. If set to 1, it automatically joins the channel. If set to 0, the latter takes place. (Default: 0)

Request body example
Light Color Skin
Copy
{
    "bot_userid": "helper_bot_for_dinner",
    "bot_nickname": "Dinner Helper",
    "bot_profile_url": "https://mealadvisor.com/bots/img/sendbird_03_512px.png",
    "bot_callback_url": "https://mealadvisor.com/bots/sendbird/dinner/",
    "is_privacy_mode": false
}

Response

If successful, this action returns a bot resource in the response body like the following.

Status: 200 OK
Light Color Skin
Copy
{
    "bot": {
        "bot_token": "712afa86d980feea00657f040535fe4f7373e329",
        "bot_profile_url": "https://mealadvisor.com/bots/img/sendbird_06_512px.png",
        "bot_userid": "helper_bot_for_dinner",
        "bot_nickname": "Dinner Helper",
        "metadata": {}
    },
    "bot_callback_url": "https://mealadvisor.com/bots/sendbird/dinner/",
    "enable_mark_as_read": true,
    "is_privacy_mode": false,
    "show_member": false,
    "channel_invitation_preference": 0
}

Update a bot

Updates information on a bot.

HTTP request

Light Color Skin
Copy
PUT https://api-{application_id}.sendbird.com/v3/bots/{bot_user_id}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

bot_user_id

string

Specifies the ID of the bot to update.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
OptionalTypeDescription

bot_nickname

string

Specifies the bot's nickname. The length is limited to 80 bytes.

bot_profile_url

string

Specifies the URL of the bot's profile image. The size is limited to 2,048 bytes.

bot_callback_url

string

Specifies the server URL where bot is located to receive all events, requests, and data forwarded from an application. For security reasons, it is highly recommended that you use an SSL server. The length is limited to 1,024 bytes.

is_privacy_mode

boolean

In the channels of where the bot is a member, determines whether to only forward the messages with the specific conditions to the bot or forword all messages to the bot, for privacy concerns. 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.

enable_mark_as_read

boolean

Determines whether to mark the bot's message as read upon sending it. (Default: true)

show_member

boolean

Determines whether to include information about the members of each channel in a callback response. (Default: false)

channel_invitation_preference

int

Determines whether the bot automatically joins the channel when invited or joins the channel after manually accepting an invitation using the API. If set to 1, it automatically joins the channel. If set to 0, the latter takes place. (Default: 0)

Response

If successful, this action returns a bot resource in the response body.


Join channels

Makes a bot join one or more channels.

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.sendbird.com/v3/bots/{bot_user_id}/channels

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

bot_user_id

string

Specifies the ID of the bot to join the channels.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

channel_urls

array

Specifies an array of one or more URLs of the channels to join.

Request body example
Light Color Skin
Copy
{
    "channel_urls": ["sendbird_group_channel_24896181_cd8b2c7208536b61895fff76ab6649d76302ee81", "sendbird_group_channel_24896191_8c75a3fd58f77fa3ab4aa256a9bf83a536b43ec7"]
}

Response

If successful, this action returns a list of joined group channel resources in the response body.


Send a bot's message

Sends a bot's message to a channel.

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.sendbird.com/v3/bots/{bot_user_id}/send

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

bot_user_id

string

Specifies the ID of the bot to send a message.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

message

string

Specifies the content of the message sent by the bot.

channel_url

string

Specifies the URL of the channel where the message is sent to.

OptionalTypeDescription

custom_type

string

Specifies a custom message type which is used for message grouping. The length is limited to 128 bytes.

data

string

Specifies additional data to store for the message. This can be structured data such as a JSON object.

send_push

boolean

Determines whether to send a push notification for the message to the members of the channel (Default: true)

mentioned

array

Specifies an array of one or more IDs of the users who get a notification for the message.

mark_as_read

boolean

Determines whether to mark the message as read for the bot. If set to false, the bot's unread_count and read_receipt remain unchanged after the message is sent. (Default: true)

Request body example
Light Color Skin
Copy
{
    "message": "Hi John, here is an answer to your question.",
    "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
    "custom_type": "auto_answer_introduction"
}

Response

If successful, this action returns a message resources in the response body.


Leave channels

Makes a bot leave one or more group channels.

HTTP request

Light Color Skin
Copy
// When leaving all channels
DELETE https://api-{application_id}.sendbird.com/v3/bots/{bot_user_id}/channels

// When leaving a channel by its channel URL
DELETE https://api-{application_id}.sendbird.com/v3/bots/{bot_user_id}/channels/{channel_url}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

bot_user_id

string

Specifies the ID of the bot to leave the channel(s).

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

channel_url

string

Specifies the URL of the channel to leave.

Response

If successful, this action returns an empty response body.


Delete a bot

Deletes a bot from an application.

HTTP request

Light Color Skin
Copy
DELETE https://api-{application_id}.sendbird.com/v3/bots/{bot_user_id}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

bot_user_id

string

Specifies the ID of the bot to delete.

Response

If successful, this action returns an empty response body.