User

You can manage user information using the following API.

Endpoint

https://api.sendbird.com/user/{Action}

Content-Type

You should always use the following Content-Type for all requests.

Content-Type: application/json, charset=utf8

Actions

Action Description
create Create a user
update Update a user
auth Retrieve a user
block Block a user
unblock Unblock a user
block_list Return a list of blocked users
deactivate Deactivate a user
get_unread_count Return a total unread count of all messaging channels

Create

POST | https://api.sendbird.com/user/create
Create a new user account using id / nickname / profile image combination.

Request

{
    "auth": API_TOKEN,
    "id": string,                 // User ID
    "nickname": string,           // User nickname
    "image_url": string,          // User profile image URL
    "issue_access_token": boolean // Default is false. Use only if you want to create an access token for this user
}

Response

{
    "id": string,               // User ID
    "user_id": long,            // *Deprecated* Shouldn't be used for anything.
    "nickname": string,         // User nickname
    "picture": string,          // User profile image URL
    "access_token": string,     // Access token value
}

Update

POST | https://api.sendbird.com/user/update
Update user account information. You can update id, nickname, profile image.

Request

{
    "auth": API_TOKEN,
    "id": string,                 // User ID for updating
    "nickname": string,           // User nickname
    "image_url": string,          // User profile image URL
    "issue_access_token": boolean // True if re-issue a new access token
}

Response

{
    "id": string,           // User ID
    "user_id": long,        // *Deprecated* Shouldn't be used for anything.
    "nickname": string,     // User nickname
    "picture": string,      // User profile image URL
    "access_token": string, // Access token value
}

Auth

POST | https://api.sendbird.com/user/auth
Retrieve a user information.

Request

{
    "auth": API_TOKEN,
    "id": string,                 // User ID
    "issue_access_token": boolean // Re-issue a new access token for this user
}

Response

{
    "id": string,           // User ID
    "user_id": long,        // *Deprecated* Shouldn't be used for anything.
    "nickname": string,     // User nickname
    "picture": string,      // User profile image URL
    "access_token": string, // Access token value
    "is_active" : boolean, // Whether a user is deactivated or not
}

Block

POST | https://api.sendbird.com/user/block
Block a target user.

Request

{
    "auth": API_TOKEN,
    "id": string,             // User ID
    "target_id": string       // Blocking User ID
}

Response

{}

Unblock

POST | https://api.sendbird.com/user/unblock
Unblock a target user.

Request

{
    "auth": API_TOKEN,
    "id": string,             // User ID
    "target_id": string       // Unblocking User ID
}

Response

{}

Block List

POST | https://api.sendbird.com/user/block_list
Return a list of blocked users

Request

{
    "auth": API_TOKEN,
    "id": string,             // User ID
}

Response

{
'block_list': 
  [
    {
        "id": string,           // User ID
        "user_id": long,        // *Deprecated* Shouldn't be used for anything.
        "nickname": string,     // User nickname
        "picture": string,      // User profile image URL
    }  
  ]
}

Deactivate

POST | https://api.sendbird.com/user/deactivate
User will leave all channels and can't sign in.

Please note that the user will lose all channels and it won't be recovered again

Request

{
    "auth": API_TOKEN,
    "id": string,             // User ID
}

Response

{}

Reactivate

POST | https://api.sendbird.com/user/reactivate
Deactivated user can sign in again but channels won't be restored.

Request

{
    "auth": API_TOKEN,
    "id": string,             // User ID
}

Response

{}

Get unread counts

POST | https://api.sendbird.com/user/get_unread_count
Total a unread count from all messaging channels

Request

{
    "auth": API_TOKEN,
    "id": string,             // User ID
}

Response

{
    "unread_message_count" : 3 
}

Open Chat Channel

You can use Open Chat Channels to operate public chat rooms. The following API can help you manage the channels from the server side.

Open Chat

This type of channel is suitable for running public chat rooms where people can join freely. The room can be scaled to host even thousands of users at once.

Use cases: Twitch-like chat rooms, interest-based communities, game lobbies, clan/guild chats, etc.

Endpoint

https://api.sendbird.com/channel/{Action}

Content-Type

You should always use the following Content-Type for all requests.

Content-Type: application/json, charset=utf8

Actions

Action Description
create Create a channel
list List all channels
update Update channel property
delete Delete a channel
view Show information of the channel
send Send a message to the channel
get_metadata Get values of metadata keys
set_metadata Set values of metadata keys
get_metacounter Get values of metacounter keys
set_metacounter Set values of metacounter keys
incr_metacounter Increase values of metacounter keys
decr_metacounter Decrease values of metacounter keys
message_count Get message count of the channel

Create

POST | https://api.sendbird.com/channel/create

Create a channel using channel URL / name.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,  // Channel Url
    "name": string,         // Topic
    "cover_url": string,    // Cover Image Url
    "data": string,         // Custom Channel Data
}

Response

{
    "id": int,
    "name": string,
    "channel_url": string,
    "member_count": int,
    "cover_img_url": string,
    "data": string,
    "created_at": long
    "ops": list,
}
  • created_at : Epoch timestamp in milliseconds.
  • ops : A list of operator ids. Operators are special users who can delete any messages in the channel. Operators will get all messages coming to the channel without any filtering or throttling.

List

POST | https://api.sendbird.com/channel/list

Retrieve channel list.

Request

{
    "auth": API_TOKEN
}

Response

[
    {
        "id": int,
        "name": string,
        "channel_url": string,
        "member_count": int,
        "cover_image_url": string,
        "data": string,
        "created_at": long // Epoch timestamp in milliseconds
    },
    ...
]

Update

POST | https://api.sendbird.com/channel/update

Update a channel's information.

Request

{
    "auth": API_TOKEN,
    "target_channel_url": string, // Target Channel Url
    "name": string, // New Name - Optional
    "channel_url": string, // New Channel Url - Optional
    "cover_url": string, // New Cover Image Url
    "data": string,         // New Custom Data,
    "ops" : list, // a list of operators ex) ["user_id_1", "user_id_2"]
}

Response

{
    "id": int,
    "name": string,
    "channel_url": string,
    "member_count": int,
    "cover_img_url": string,
    "data": string,
    "ops" : list, // a list of operators
    "created_at": long // Epoch timestamp in milliseconds
}

Delete

POST | https://api.sendbird.com/channel/delete

Delete the channel that matches the URL.

Request

{
    "auth": API_TOKEN,
    "channel_url": string // Target Channel Url
}

Response

{}

View

POST | https://api.sendbird.com/channel/view

View the channle information and its online members.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,
}

Response

{
    {
      "channel_url": string,        // Channel URL
      "name": string,               // Topic of the channel
      "created_at": int,            // Channel creation timestamp
      "cover_image_url", string,    // Cover Image Url
      "data", string,               // Custom Data
      "members": [
        {
          "id": string,               // User ID
          "image": string,            // User profile image URL
          "name": string,             // User nickname
        },
        ...
      ]
    },
}

Send

POST | https://api.sendbird.com/channel/send

Send a message to the given channel.

Request

{
    "auth": API_TOKEN,
    "id": string,             // Sender User ID
    "channel_url": string,    // (Optional) Channel URL
    "message": string,        // Message to be sent
    "data": string,           // (Optional) Custom data field
}

Response

{}

Metadata

POST | https://api.sendbird.com/channel/get_metadata

Get values of metadata keys.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,      // Channel URL     
    "keys": ["key1", "key2"]   //  Key names
}

Response

{ "key1": "value1",
  "key2": "value2"
}

POST | https://api.sendbird.com/channel/set_metadata

Set values of metadata keys. All values should be string.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,      // Channel URL     
    "data": {"key1":"value1", "key2":"value2"}
}

Response

{ "key1": "value1",
  "key2": "value2"
}

Metacounter

POST | https://api.sendbird.com/channel/get_metacounter

Get values of metacounter keys.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,      // Channel URL     
    "keys": ["key1", "key2"],   //  Key names
}

Response

{ "key1": value1,
  "key2": value2
}

POST | https://api.sendbird.com/channel/set_metacounter

Set values of metacounter keys. All values should be integer.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,      // Channel URL     
    "data": {"key1":value1, "key2":value2}
}

Response

{ "key1": value1,
  "key2": value2
}

POST | https://api.sendbird.com/channel/incr_metacounter

Increase values of metacounter keys. All deltas should be integer.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,      // Channel URL     
    "data": {"key1":delta1, "key2":delta2}
}

Response

{ "key1": updated_value1,
  "key2": updated_value2
}

POST | https://api.sendbird.com/channel/decr_metacounter

Decrease values of metacounter keys. All deltas should be integer.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,      // Channel URL     
    "data": {"key1":delta1, "key2":delta2}
}

Response

{ "key1": updated_value1,
  "key2": updated_value2
}

Message Count

POST | https://api.sendbird.com/channel/message_count

Get message count of the channel.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,    // Channel URL     
}

Response

{
  "message_count": int
}

Messaging Channel

You can manage group messaging channels using the API below.

(Please note that you cannot manage 1on1 messaging through the server API as of now.)

Group Messaging

  • Group messaging is suitable for small group communication.
  • Only users who have been added/invited to the channel can read the messages.
  • The users can also access the list of group messaging channels they are participating.
  • When a user leaves (or is removed from) the channel, the channel disappears from the user's list.

Endpoint

https://api.sendbird.com/messaging/{Action}

Content-Type

You should always use the following Content-Type for all requests.

Content-Type: application/json, charset=utf8

Actions

Action Description
create Create a group messaging channel
update Update a group messaging channel
delete Delete a group messaging channel
invite Invite users to the channel
hide Hide a messaging channel from the user list
leave Make users leave from the channel
view Show information of the channel
get_metadata Get values of metadata keys
set_metadata Set values of metadata keys
get_metacounter Get values of metacounter keys
set_metacounter Set values of metacounter keys
incr_metacounter Increase values of metacounter keys
decr_metacounter Decrease values of metacounter keys
message_count Get message count of the channel

Create

POST | https://api.sendbird.com/messaging/create

Create a group messaging channel using given name.

Request

{
    "auth": API_TOKEN
    "name": string,        // (Optional) Topic
    "is_group": boolean,   // weather 1 on 1 or Group chat
    "cover_url" : string,  // (Optional) channel cover image url
    "data": string,        // (Optional) custom data
}

Response

{
    "channel": {
        "channel_url": string,
        "data": string,
        "name": string,
        "is_group": boolean,
        "cover_url": string
    }
}

Update

POST | https://api.sendbird.com/messaging/update

Update a group messaging channel using given channel_url.

Request

{
    "auth": API_TOKEN
    "channel_url": string,
    "name" : string,
    "cover_url" : string,
    "data": string
}

Response

{
    "channel": {
        "channel_url": string,
        "data": string,
        "name": string,
        "is_group": boolean,
        "cover_url": string
    }
}

Delete

POST | https://api.sendbird.com/messaging/delete

Delete a group messaging channel using given channel_url.

Request

{
    "auth": API_TOKEN,
    "channel_url": string
}

Response

{
    "channel": {
        "channel_url": string
    }
}

Invite

POST | https://api.sendbird.com/messaging/invite

Invite users to the channel.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,
    "user_ids": [string, ...]
}

Response

{
    "channel": {
        "channel_url": string
    }
}

Hide

POST | https://api.sendbird.com/messaging/hide

Hide a messaging channel from the user messaging channel list.

Request

{
    "auth": API_TOKEN,
    "id": string,               // User ID
    "channel_url": string       // Channel URL
}

Response

{
    "channel": {
        "channel_url": string
    }
}

Leave

POST | https://api.sendbird.com/messaging/leave

Request

{
    "auth": API_TOKEN,
    "channel_url": string,
    "user_ids": [string, ...]
}

Response

{
    "channel": {
        "channel_url": string
    }
}

View

POST | https://api.sendbird.com/messaging/view

View information of the channel.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,
}

Response

{
    "channel_url": string,        // Channel URL
    "name": string,               // Channel name
    "last_message": string,       // Last message
    "last_message_ts": int,       // Last message timestamp
    "cover_url": string,          // Cover Image Url
    "data": string,               // Custom data
    "is_group": boolean,          // Weather 1 on 1 or Group chat
    "created_at": int,            // Channel creation timestamp
    "members": [
      {
        "id": string,               // User ID
        "image": string,            // User profile image URL
        "name": string,             // User nickname
      },
      ...
    ]
}

Metadata

POST | https://api.sendbird.com/messaging/get_metadata

Get values of metadata keys.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,      // Channel URL     
    "keys": ["key1", "key2"]    //  Key names
}

Response

{ "key1": "value1",
  "key2": "value2"
}

POST | https://api.sendbird.com/messaging/set_metadata

Set values of metadata keys. All values should be string.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,      // Channel URL     
    "data": {"key1":"value1", "key2":"value2"}
}

Response

{ "key1": "value1",
  "key2": "value2"
}

Metacounter

POST | https://api.sendbird.com/messaging/get_metacounter

Get values of metacounter keys.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,      // Channel URL     
    "keys": ["key1", "key2"],   //  Key names
}

Response

{ "key1": value1,
  "key2": value2
}

POST | https://api.sendbird.com/messaging/set_metacounter

Set values of metacounter keys. All values should be integer.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,      // Channel URL     
    "data": {"key1":value1, "key2":value2}
}

Response

{ "key1": value1,
  "key2": value2
}

POST | https://api.sendbird.com/messaging/incr_metacounter

Increase values of metacounter keys. All deltas should be integer.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,      // Channel URL     
    "data": {"key1":delta1, "key2":delta2}
}

Response

{ "key1": updated_value1,
  "key2": updated_value2
}

POST | https://api.sendbird.com/messaging/decr_metacounter

Decrease values of metacounter keys. All deltas should be integer.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,      // Channel URL     
    "data": {"key1":delta1, "key2":delta2}
}

Response

{ "key1": updated_value1,
  "key2": updated_value2
}

Message Count

POST | https://api.sendbird.com/messaging/message_count

Get message count of the channel.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,    // Channel URL     
}

Response

{
  "message_count": int
}

Admin

This API is for running administrative features.

For example, you can broad cast messages to certain channels, mute abusive users, etc.

Endpoint

https://api.sendbird.com/admin/{Action}

Content-Type

You should always use the following Content-Type for all requests.

Content-Type: application/json, charset=utf8

Actions

Action Description
broadcast_message Send an admin message
read_messages Read messages from the channel
delete_message Delete a messsage from the application
mute Mute a user
unmute Unmute a user
mute_list List muted users
ccu_count Returns a number of concurrent users on channels

Broadcast Messages

POST | https://api.sendbird.com/admin/broadcast_message
Broadcast an admin message to the channels.

  • Please note that this feature is not available on Free and Sprout plans.

Request

{
    "auth": API_TOKEN,
    "channel_urls": [string, ...],    // List of channel urls
    "message": string,        // Message to be sent
    "persistent": boolean,    // Save the message if True
    "data": string,           // Custom data field
}

Response

{}

Read Messages

POST | https://api.sendbird.com/admin/read_messages
Read messages from the target channel.
Either channel_url or target_user_ids must be set

Request

{
    "auth": API_TOKEN,
    "channel_url": string,               // (Optional) Channel url
    "target_user_ids": [string, string]  // (Optional) Target messaging channel with given two users.
    "limit": int,                        // A number of messages to read (default: 50)
    "message_id": long                   // Read a given limit of messages before this id. Set to zero to read messages from the last.

}

Response

[
    {
        "id": string,       // Sender's ID
        "nickanme": string, // Sender's name
        "message_id": long, // Message ID
        "timestamp": long,  // Epoch timestamp in milliseconds
        "message": string,  // Chat message
        "file": { }         // Empty file info object when message is text message
    },
    {
        "id": string,       // Sender's ID
        "nickanme": string, // Sender's name
        "message_id": long, // Message ID
        "timestamp": long,  // Epoch timestamp in milliseconds
        "message": "",      // Empty string when message is file message
        "file": {
          "url": string,    // File url
          "custom": string, // User custom field
          "type": string,   // File type
          "name": string,   // File name
          "size": long      // File size
        },                  // File info object
    },
    ...
]

Delete a Message

POST | https://api.sendbird.com/admin/delete_message
Delete a message from your application.

Request

{
    "auth": API_TOKEN,
    "msg_id": MESSAGE_ID
}

Response

{
   "app_id": APP_ID,
   "msg_id": MESSAGE_ID
}

Mute a User

Mute a user in all channels in your application.
Prohibit a user from sending messages at all.

POST | https://api.sendbird.com/admin/mute

Request

{
    "auth": API_TOKEN,
    "id": string           // User ID
}

Response

{}

Mute a user in some channels. Channel mute has two modes; hard mute and soft mute. In hard mute mode, messages from muted users are blocked in server. In soft mute mode, messages from muted users are sent to "onMuteMessagesReceived" callback in Client SDK. In most cases, what you need is "hard mute" mode.
is_soft_mute is false by default.

POST | https://api.sendbird.com/admin/mute

Request

{
    "auth": API_TOKEN,
    "id": string,           // User ID
    "channel_urls": ["channel_1","channel_2"],
    "is_soft_mute" : false    
}

Response

["channel_1", "channel_2"]

Unmute

Unmute a user to start sending messages in your application.
This doesn't unmute channel-wide mute.
POST | https://api.sendbird.com/admin/unmute

Request

{
    "auth": API_TOKEN,
    "id": string           // User ID
}

Response

{}

Unmute a user to start sending messages in some channels.
This doens't unmute application-wide mute.

POST | https://api.sendbird.com/admin/unmute

Request

{
    "auth": API_TOKEN,
    "id": string,           // User ID
    "channel_urls": ["channel_1","channel_2"]
}

Response

["channel_1","channel_2"]

Mute List

POST | https://api.sendbird.com/admin/mute_list
Get the list of muted user ids in application-wide mute

Request

{
    "auth": API_TOKEN
}

Response

[
    "user_id",         // User ID, id: string
    ...
]

POST | https://api.sendbird.com/admin/mute_list
Get the list of muted user ids in channel-wide mute

Request

{
    "auth": API_TOKEN,
    "channel_urls": ["channel_1", "channel_2"]
}

Response

[
    {
     "channel_url" : "channel_1",
     "mute_list" : [{"id":"user1","is_soft_mute":false}]
    }
]

Concurrent User Count

POST | https://api.sendbird.com/admin/ccu_count

Returns the number of concurrent users on all channels.

Request

{
    "auth": API_TOKEN
}

Response

{
    "count": int,         // Concurrent chatting user count
}

Member Count in Channel

POST | https://api.sendbird.com/admin/member_count

Returns the number of concurrent users on all channels.

Request

{
    "auth": API_TOKEN,
    "channel_url": CHANNEL_URL
}

Response

{
  "accumulated_member_count": 4, // number of members joined the channel at least once
  "online_member_count": 1, // number of members currently online in the channel
  "member_count": 2,        // number of members in the channel
}

Migration

Switching from an in-house (or another) solution to SendBird? No problem! We got you covered. :)

You can migrate your previous chat messages to SendBird using the following API.

Endpoint

https://api.sendbird.com/migration/{Action}

Content-Type

You should always use the following Content-Type for all requests.

Content-Type: application/json, charset=utf8

Actions

Action Description
create Create a messaging channel with the given users
invite Invite users to the channel
record Record your old messages into the channel

Create

POST | https://api.sendbird.com/migration/create

Create a messaging channel with the given users.
Users will be created automatically if they do not exist.

Request

{
    "auth": API_TOKEN,
    "ids": [string, ...],         // User IDs
    "hide": true                  // Hide all messaging channels on channel list(default: true)
}

Response

{
    "channel": {
        "channel_url": string     // Newly created messaging channel URL
    }
}

Invite

POST | https://api.sendbird.com/migration/invite

Invite users to the given channel.
Create a default user with a given id if the user does not exist.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,       // Channel URL
    "ids": [string, ...],        // Invitee user IDs
    "hide": true                 // Hide all messaging channels on channel list to invited users(default: true)
}

Response

{
    "channel": {
        "channel_url": string
    }
}

Record

POST | https://api.sendbird.com/migration/record

Record your old messages into the created channel.

Request

{
    "auth": API_TOKEN,
    "channel_url": string,     // Channel URL
    "messages": [             // Array of Message Data
        {
            "sender_id": string,    // Member ID
            "message": string,      // Message
            "data": string,         // (Optional)
            "timestamp": long       // Epoch timestamp in milliseconds
        }
        , ...
    ]
}

Response

{
    "channel": {
        "channel_url": string
    }
}

SendBird Bot Interface

Bots are special users in SendBird to receive/send messages automatically. Bots can exchange messages with normal users in 1:1 Messaging or Group Messaging. Open Chat is not supported yet. Bot Interface is designed to be RESTful.

You can build interesting features with Bot API. Here are some examples.

  • Helper Bot
    • Users can ask Helper Bot any questions and get answers immediately.
  • Gif Search Bot
    • Users can search Gifs with a magic verb. ex) /gif cats
  • Assistant Bot
    • Assistant Bot hears all messages in chat rooms and automatically suggests nearby restaurants or venues related to chat contexts .

1. How do bots work?

Bot API provides an interface between normal users and bots.
Making bots process incoming messages and generate replies is on your plate.

The interface consists of two main parts.

  • Users -> Bots : Bot Callback URL ( 4.3. Bot Callback URL )
    • SendBird calls a Bot Callback URL when there is a new message for a bot.
  • Bots -> Users : REST API ( 4.4. Send a message from a bot )
    • Your server can send any messages to users in the name of a bot via SendMessage REST API.

2. How do I create a bot?

You can create a bot by using 4.1. Create a bot REST API.

bot_userid should be unique and it's used as an unique key of the boot in other Server APIs.
You should register bot_callback_url and decide privacy_mode when you create the bot.

When privacy_modeis True, messages only start with "/" or mentioned bot_userid will be forwarded to bot_callback_url. When it's False, all messages exchanged in a channel will be forwarded to bot_callback_url.

3. How do I make bots communicate with users?

Bots and users must be in a same channel to interact.
There are multiple scenarios possible.

Client SDK can use bot accounts in the same way it does for normal users.

Users start 1:1 messaging with a bot

iOS example

[SendBird startMessagingWithUserId:bot_userid];

Users invite a bot to an existing channel

iOS example

[SendBird inviteMessagingWithChannelUrl:[self.currentMessagingChannel getUrl] andUserId:bot_userid];

Bots can start private messaging channels or invite users to an existing channel with SendBird Server API.

Bots start private messaging with users

First, you should create a new messaging channel.

curl -H "Accept: application/json"
    -H "Content-type: application/json"
    -X POST -d '{"auth":*API_TOKEN*, "name": *CHANNEL_NAME*}'
    https://api.sendbird.com/messaging/create

Then, you can invite a bot and users into the channel.

curl -H "Accept: application/json"
    -H "Content-type: application/json"
    -X POST -d '{"auth":*API_TOKEN*, "channel_url":*CHANNEL_NAME*, "user_ids": [*bot_userid*,*USER_ID1*,*USER_ID2*] }'
    https://api.sendbird.com/messaging/invite

Bots invite an user to an existing channel

You can invite an user to a channel your bot already joined.

curl -H "Accept: application/json"
    -H "Content-type: application/json"
    -X POST -d '{"auth":*API_TOKEN*, "channel_url":*CHANNEL_NAME*, "user_ids": [*USER_ID1*] }'
    https://api.sendbird.com/messaging/invite

When a bot creates a channel with Server API, bot should send greeting messages to the channel to make it visible on users' side. Channels that never had any messages are hidden to users by default.

curl -H "Accept: application/json"
    -H "Content-type: application/json"
    -X POST -d '{"api_token":*API_TOKEN*, "channel_url":*CHANNEL_NAME*, "message": "Hello! Nice to meet you!""data": "" }'
    https://api.sendbird.com/v2/bots/:bot_userid/send

4. Bot API Reference

4.1. Bot Object

Parameters Type Description
bot_userid String Unique username. You should provide this when you create a bot.
bot_nickname String Display name.
bot_profile_url String Profile image url.
bot_callback_url String SendBird forwards all data, events related to this bot to bot_callback_url. We highly recommend using SSL URL for security reasons.
is_privacy_mode Boolean When privacy_modeis True, messages only start with "/" or mentioned bot_userid will be forwarded to bot_callback_url. When it's False, all messages exchanged in a channel will be forwarded to bot_callback_url.
bot_token String We add bot_token to every request goes to bot_callback_url so you can verify that each request is came from SendBird.

4.2. Create a bot

Method Content Type URL
POST application/json, charset=utf8 https://api.sendbird.com/v2/bots

Example Request Body

{
    "api_token" : "<YOUR_API_TOKEN>",
    "bot_userid" : "helper_bot",
    "bot_nickname" : "Helper Bot",
    "bot_profile_url" : "<profile url>",
    "bot_callback_url" : "https://yourdomain.com/sendbird_bot",
    "is_privacy_mode" : true
}
Parameters Type Required Description
api_token String Yes It's your secret token that allows you to make all kinds of Server APIs. This token should not be leaked and should be used only in your server not in your client.
bot_userid String Yes See 4.1. Bot Object Section
bot_nickname String Yes See 4.1. Bot Object Section
bot_profile_url String Yes See 4.1. Bot Object Section
bot_callback_url String Yes See 4.1. Bot Object Section
is_privacy_mode Boolean Yes See 4.1. Bot Object Section

Response : 201 CREATED

{
    "bot_token": "<BOT_TOKEN>",
    "bot_userid": "helper_bot",
    "bot_nickname": "Helper Bot",
    "bot_profile_url" : "<profile url>",
    "bot_callback_url": "https://yourdomain.com/sendbird_bot",
    "is_privacy_mode": true
}

4.3. Bot Callback URL

  • Your URL should be able to handle POST requests with application/json, charset=utf8 type.
  • Your URL should return 200 OK HTTP code if you successfully get a callback. Otherwise SendBird server will call your URL several times until it gets 200 OK.
  • We highly recommend using SSL for security reasons.

JSON body format

{
 "category":"bot_message_notification",
 "ts":1455010270350,
 "bot_token":"fc3d963c6990be8410133b21dfff1cfea23144f0",
 "bot_userid":"hello_bot",
 "bot_nickname":"HELLOBOT",
 "sender_username":"normal_user1",
 "sender_nickname":"SendBird",
 "message":"how are you feeling today?",
 "data":"",
 "mentioned":[],
 "channel_type":"messaging",
 "channel_url":"sendbird_messaging_4852157_1f0136fbbcee9612440bfa82d97b66a81c4a465d",
 "files":[]
}
Fields Type Description
category String Type of bot notification. For now, there's only one type available. "bot_message_notification"
ts long UNIX timestamp of this message. You could use this field to sort messages sent to your bot.
bot_token String This is a secret token return to you when you create your bot. You can use the bot_token to verify that a callback is sent from SendBird.
bot_userid String Recipient bot's username
bot_nickname String Recipient bot's nickname
sender_username String Sender's username. This is equivalent to id field in Server API.
sender_nickname String Sender's nickname
message String Message sent from a sender
data String Additional data field sent from a sender
mentioned Array A list of usernames mentioned in this message
channel_type String Type of channel. Two types are available. 'messaging' for 1on1 channel, 'group_messaging' for group messaging channel.
channel_url String Unique url of each channel

4.4. Send a message from a bot

Method Content Type URL
POST application/json, charset=utf8 https://api.sendbird.com/v2/bots/:bot_userid/send

Example Request Body

{
    "api_token" : "<YOUR_API_TOKEN>",
    "message" : "Hello John, here's an answer for your question",
    "data" : "",
    "channel_url" : "<CHANNER_URL>"
}
Parameters Type Required Description
api_token String Yes api_token
message String Yes message
data String Yes data
channel_url String Yes channel_url

Response : 200 OK

{
    "bot_userid": "hello_bot",
    "channel_url": "<CHANNER_URL>",
    "message" : "Hello John, here's an answer for your question",
    "data" : ""
}

4.5. Get a list of bots in your application

Method Content Type URL
GET application/json, charset=utf8 https://api.sendbird.com/v2/bots?api_token=:api_token
Parameters Type Required Description
api_token String Yes api_token

Response : 200 OK

[
    {
        "bot_token": "<BOT_TOKEN1>",
        "bot_userid": "helper_bot",
        "bot_nickname": "Helper Bot",
        "bot_profile_url" : "<profile url>",
        "bot_callback_url": "https://yourdomain.com/sendbird_bot",
        "is_privacy_mode": true
    },
    {
        "bot_token": "<BOT_TOKEN2>",
        "bot_userid": "helper_bot2",
        "bot_nickname": "Helper Bot2",
        "bot_profile_url" : "<profile url2>",
        "bot_callback_url": "https://yourdomain.com/sendbird_bot",
        "is_privacy_mode": true
    }
]

4.6. Retrieve a bot

Method Content Type URL
GET application/json, charset=utf8 https://api.sendbird.com/v2/bots/:bot_userid?api_token=:api_token
Parameters Type Required Description
api_token String Yes api_token

Response : 200 OK

{
    "bot_token": "<BOT_TOKEN1>",
    "bot_userid": "helper_bot",
    "bot_nickname": "Helper Bot",
    "bot_profile_url" : "<profile url>",
    "bot_callback_url": "https://yourdomain.com/sendbird_bot",
    "is_privacy_mode": true
}

4.7. Update a bot

Method Content Type URL
POST application/json, charset=utf8 https://api.sendbird.com/v2/bots/:bot_userid

Example Request Body

{
    "api_token" : "<YOUR_API_TOKEN>",
    "bot_nickname" : "Helper Bot",
    "bot_profile_url" : "<profile url>",
    "bot_callback_url" : "https://yourdomain.com/sendbird_bot",
    "is_privacy_mode" : true
}
Parameters Type Required Description
api_token String Yes api_token
bot_nickname String NO bot_nickname
bot_profile_url String NO bot_profile_url
bot_callback_url String NO bot_callback_url
is_privacy_mode Boolean NO is_privacy_mode

Response : 200 OK

{
    "bot_token": "<BOT_TOKEN>",
    "bot_userid": "helper_bot",
    "bot_nickname": "Helper Bot",
    "bot_callback_url": "https://yourdomain.com/sendbird_bot",
    "is_privacy_mode": true
}

4.8. Delete a bot

Method Content Type URL
DELETE application/json, charset=utf8 https://api.sendbird.com/v2/bots/:bot_userid

Example Request Body

{
    "api_token" : "<YOUR_API_TOKEN>"
}
Parameters Type Required Description
api_token String Yes api_token

Response : 200 OK

{
    "bot_userid": "helper_bot"
}

Miscellaneous

Using cURL

curl -H "Accept: application/json" -H "Content-type: application/json, charset=utf8" -X POST -d '{"auth":"xxxx-xxxx-xxxx-xxxx"}' https://api.sendbird.com/category/action

Using PHP

<?php
function sendbird_api($url, $params = array())
{
    $context_params = array(
        'http' => array(
            'method' => 'POST',
            'header' => "Content-Type: application/json\r\n",                                                           
            'ignore_errors' => true
        )
    );

    $context_params['http']['content'] = json_encode($params);

    $context = stream_context_create($context_params);
    $fp = fopen($url, 'rb', false, $context);
    $res = false;

    if($fp)
    {
        $res = stream_get_contents($fp);
    }

    if ($res === false) {
        return array(
            'error' => true,
            'message' => 'Connection failed.',
        );
    }

    return json_decode($res);
}


$response = sendbird_api("http://api.sendbird.com/category/action",
    array(
      'auth' => 'xxxx-xxxx-xxxx-xxxx',
    )
);

print_r($response);

Using Python

import urllib2
import json

def sendbird_api(url, params):
  req = urllib2.Request(url)
  req.add_header('Content-Type', 'application/json, charset=utf8')
  try:
    response = urllib2.urlopen(req, json.dumps(params))
  except:
    return {'error': True, 'message': 'Connection failed.'}

  if response.getcode() / 100 != 2:
    return {'error': True, 'message': 'Connection failed.'}

  return json.loads(response.read())


url = 'https://api.sendbird.com/category/action'
params = {
  'auth': 'xxxx-xxxx-xxxx-xxxx',
}

sendbird_api(url, params)