Desk / Platform API
Home
/
Desk
/
Platform API

Bot

With Bot API, you can retrieve or update information related to a bot.


Requirements

  • Bot API can be used after setting up a bot in Settings > Desk > Bots of your dashboard.
  • When sending a bot’s message to the Desk server from your server, the bot_webhook_event_id property should be included in the request body to notify the Desk server of which message the bot is responding to.
  • When sending an HTTP request to the Desk server, API key should be included as a request header. You can generate an API key in Settings > Desk > Credentials of your dashboard.

Resource representation

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

Property nameTypeDescription

id

int

A unique identifier of the bot.

name

string

The name of the bot.

type

string

The type of the bot. Valid values are CUSTOM and FAQ.

project

int

The unique ID of a Desk project where the bot belongs. Desk projects have their own corresponding Sendbird application on a one-to-one basis.

key

string

The unique key of the bot in a project.

status

string

Indicates whether the bot’s account is activated in Sendbird Desk. Valid values are ACTIVE and INACTIVE.

photoUrl

string

The profile image URL of the bot.

webhookUrl

string

The webhook URL on your server where the Desk server sends webhook events when the bot receives a message from a customer.

createdAt

string

The date and time when the bot was created, in ISO 8601 format.

updatedAt

string

The date and time when any of the bot’s properties was last updated, in ISO 8601 format.

isTicketTransferByAgentEnabled

boolean

Indicates whether to allow the bot to receive tickets transferred from other agents.

isUnreadError

boolean

Indicates whether there is any unchecked error in the webhook logs.

welcomeMessage

string

The bot’s welcome message sent to a customer when a ticket is assigned to the bot. If a new ticket is directly assigned to the bot during the ticket creation using either Platform API or assignment rules, this message is sent to the customer instead of default welcome or away messages.

fallbackRetryTimes

int

The maximum number of total fallback messages to send to your customer. When the sum of server and timeout fallback messages reaches the limit, the ticket is unassigned from the bot and its status changes to Pending.

serverErrorMessage

string

The fallback message to send to your customer when the Desk server fails to receive an HTTP 200 OK response from your server. The Desk server sends an HTTP request to your server when receiving a customer’s message.

timeoutMessage

string

The fallback message for timeout, which is sent to your customer when the Desk server successfully delivered the webhook event for a customer’s message to your server but there isn’t any reply message for time limit set by the timeoutSeconds property.

timeoutSeconds

int

Time limit in seconds to send a timeout fallback message. Valid value is from 10 to 300, and can be set in increments of 10.

handoverMessage

string

The message sent when ticket status is changed to Pending or when a ticket is transferred to other agents.

agent

object

An agent resource that represents the bot in Sendbird Desk.


Actions

  • API endpoints are relative to the base URL allocated to your application. In this page, the /bots endpoint refers to https://desk-api-{application_id}.sendbird.com/platform/v1/bots.

Note: If you want to know your application ID, sign in to your dashboard, go to the Settings > Application > General, and then check the Application ID.

  • It's recommended that the parameter values in API URLs be urlencoded, such as {agent_id}.

List of actions

ActionHTTP request

List bots

GET /bots
Retrieves a list of bots registered in the application.

View a bot

GET /bots/{bot_id}
Retrieves information on a specific bot.

Update a bot

PATCH /bots/{bot_id}
Updates information on a bot.

Send a bot’s message

POST /bots/{bot_id}/send
Sends a bot’s message to a customer.

Get a bot’s webhook logs

GET /bots/{bot_id}/webhook_logs
Retrieves a bot’s webhook logs.


List bots

Retrieves a list of bots registered in the application.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Optional
Parameter nameTypeDescription

limit

int

Specifies the number of results to return per page. Acceptable values are 1 to 500, inclusive. (Default: 50)

offset

int

Specifies the number of results to skip before retrieving the next page in the result set. This is used to adjust the starting index of the next page. (Default: 0)

Query string example
Light Color Skin
Copy
?limit=10&offset=20

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "count": 23,
    "next": "https://desk-api-{app_id}.sendbird.com/platform/v1/bots/?limit=1&offset=2",
    "previous": "https://desk-api-{app_id}.sendbird.com/platform/v1/bots/?limit=1",
    "results": [
        {
            "id": 11,
            "name": "cindybot",
            "type": "CUSTOM",
            "project": 89,
            "key": "cindy",
            "status": "ACTIVE",
            "photoUrl": "https://www.sendbird.com/profile_images/cindybot.png",
            "webhookUrl": "https://example.com/",
            "createdAt": "2021-02-06T06:03:23.288649Z",
            "updatedAt": "2021-02-16T15:47:08.880800Z",
            "isTicketTransferByAgentEnabled": true,
            "isUnreadError": true,
            "welcomeMessage": "Welcome to Sendbird! Is there anything I can help with? :)",
            "fallbackRetryTimes": 2,
            "serverErrorMessage": "Something went wrong. Can you please try again?",
            "timeoutSeconds": 20,
            "timeoutMessage": "Sorry for the delay. Could you try again in a moment?",
            "handoverMessage": "Another agent will be with you in a moment. Thanks for your patience.",
            "agent": {
                "id": 3102,
                "displayName": "cindybot",
                "project": 89,
                "user": null,
                "sendbirdId": "sendbird_desk_agent_id_bot_e15649c3-1242-4484-a66e-79e446736e42",
                "role": "AGENT",
                "createdAt": "2021-02-06T06:03:23.294188Z",
                "status": "ACTIVE",
                "connection": "ONLINE",
                "email": "",
                "photoThumbnailUrl": "https://www.sendbird.com/profile_images/cindybot.png",
                "connectionUpdatedAt": null,
                "tier": "INTERMEDIATE",
                "groups": [
                    {
                        "name": "TW team",
                        "key": "tw",
                        "id": 185
                    }
                ]
            }
        },
        ... # More bots
    ]
}

List of response properties

Property nameTypeDescription

count

int

The total count of agents registered in the application.

previous

string

The URL to retrieve the previous page in the result set.

next

string

The URL to retrieve the next page in the result set.

results[]

list

A list of bots.


View a bot

Retrieves information on a specific bot.

HTTP request

Light Color Skin
Copy
GET https://desk-api-{application_id}.sendbird.com/platform/v1/bots/{bot_id}

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

bot_id

int

Specifies the unique ID of the target bot.

Response

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


Update a bot

Retrieves a list of bots registered in the application.

HTTP request

Light Color Skin
Copy
PATCH https://desk-api-{application_id}.sendbird.com/platform/v1/bots/{bot_id}

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

bot_id

int

Specifies the unique ID of the target bot.

Request body

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

Optional
Property nameTypeDescription

name

string

Specifies the name of a bot.

photoUrl

string

Specifies the profile image URL of a bot.

profileFile

file

Uploads the file of the bot's profile image. An acceptable image is up to 5 MB.

webhookUrl

string

Specifies the webhook URL on your server where the Desk server sends webhook events when a bot receives a message from a customer.

isTicketTransferByAgentEnabled

boolean

Determines whether to allow a bot to receive tickets transferred from other agents.

welcomeMessage

string

Specifies a bot’s welcome message sent to a customer when a ticket is assigned to the bot. If a new ticket is directly assigned to the bot during the ticket creation using either Platform API or assignment rules, this message is sent to the customer instead of default welcome or away messages.

fallbackRetryTimes

int

Specifies the maximum number of total fallback messages to send to your customer. When the sum of server and timeout fallback messages reaches the limit, the ticket is unassigned from the bot and its status changes to Pending.

serverErrorMessage

string

Specifies the fallback message to send to your customer when the Desk server fails to receive an HTTP 200 OK response from your server. The Desk server sends an HTTP request to your server when receiving a customer’s message.

timeoutMessage

string

Specifies the fallback message for timeout, which is sent to your customer when the Desk server successfully delivered the webhook event for a customer’s message to your server but there isn’t any reply message for time limit set by the timeoutSeconds property.

timeoutSeconds

int

Specifies time limit in seconds to send a timeout fallback message. Valid value is from 10 to 300, and can be set in increments of 10.

handoverMessage

string

Specifies the message sent when ticket status is changed to Pending or when a ticket is transferred to other agents.

Note: If you want to upload a profile picture by passing an image file instead of a URL, reference the Multipart requests section.

Request body example
Light Color Skin
Copy
{
    "name": "jeff_bye",
    "webhookUrl": "https://example.com/",
    "isTicketTransferByAgentEnabled": true,
    "welcomeMessage": "Hi! How can I help you?",
    "fallbackRetryTimes": 3,
    "serverErrorMessage": "Something went wrong :(",
    "timeoutMessage": "Sorry for the delay. Please wait a moment.",
    "timeoutSeconds": 10,
    "handoverMessage": "Another agent will support you in a moment."
}

Response

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


Send a bot's message

Sends a bot’s message to a customer.

HTTP request

Light Color Skin
Copy
POST https://desk-api-{application_id}.sendbird.com/platform/v1/bots/{bot_id}/send

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

bot_id

int

Specifies the unique ID of the target bot.

Request body

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

Properties
RequiredTypeDescription

botWebhookEventId

int

Specifies the ID of a bot’s webhook event that a bot’s message is responding to.

message

string

Specifies a bot’s message to send.

Request body example
Light Color Skin
Copy
{
    "botWebhookEventId": 20,
    "message": "It's my pleasure! Need anything else?"
}

Response

If successful, this action returns the information about the sent message in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "id": 20,
    "bot": 37,
    "createdAt": "2021-02-06T06:06:56.895713Z",
    "updatedAt": "2021-02-06T06:07:12Z",
    "status": "RECEIVED",
    "webhookUrl": "https://example.com/",
    "chatMessage": {
        "id": 167620,
        "ticket": 154510,
        "userSendbirdId": "tree",
        "userType": "CUSTOMER",
        "createdAt": "2021-02-06T06:06:56.658000Z",
        "message": "Thanks, Cindy! Very helpful."
    }
}

List of response properties

Property nameTypeDescription

id

int

The webhook event ID of the customer’s message that the bot’s message responded to.

bot

int

The unique ID of the bot that sent the message.

createdAt

string

The date when a webhook event is created, in ISO 8601 format.

updatedAt

string

The date when a webhook event is updated, in ISO 8601 format.

status

string

The status of the webhook log. Valid values are limited to the following:
- SENT: Logs indicating that the webhook event is successfully sent from the Desk server to your server, which contains a customer’s message the bot received.
- RECEIVED: Logs indicating that the Desk server successfully received the webhook event from your server, which contains the bot’s answer to a customer’s messages.
- ERROR: Logs indicating that the Desk server failed to receive an HTTP 200 OK response from your server.
- TIMEOUT: Logs indicating that your server hasn’t replied for the time limit set by the timeoutSeconds property.

webhookUrl

string

The webhook URL of when the bot’s message was sent.

chatMessage

nested object

An object that represents a customer’s message that the bot’s message responded to.


Get a bot's webhook logs

Retrieves a custom bot’s webhook logs.

HTTP request

Light Color Skin
Copy
GET https://desk-api-{application_id}.sendbird.com/platform/v1/bots/{bot_id}/webhook_logs

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

bot_id

int

Specifies the unique ID of the target bot.

OptionalTypeDescription

limit

int

Specifies the number of results to return per page. Acceptable values are 1 to 500, inclusive. (Default: 50)

offset

int

Specifies the number of results to skip before retrieving the next page in the result set. This is used to adjust the starting index of the next page. (Default: 0)

start_date

date

Specifies a starting date that restricts the search scope to retrieve webhook logs created between start_date and end_date, in YYYY-MM-DD format.

end_date

date

Specifies an ending date that restricts the search scope to retrieve webhook logs created between start_date and end_date, in YYYY-MM-DD format.

order

string

Specifies the method to sort a list of results. Acceptable values are limited to the following:
- created_at: sorts by the time of webhook log creation in ascending order.
- -created_at (default): sorts by the time of webhook log creation in descending order.
- id: sorts by webhook log ID in an ascending order.
- -id: sorts by webhook log ID in a descending order.

status

string

Specifies one or more statuses of webhook logs to retrieve with a query string like status=SENT&status=RECEIVED. Acceptable values are limited to the following:
- SENT: Logs indicating that the webhook event is successfully sent from the Desk server to your server, which contains a customer’s message the bot received.
- RECEIVED: Logs indicating that the Desk server successfully received the webhook event from your server, which contains the bot’s answer to a customer’s messages.
- ERROR: Logs indicating that the Desk server failed to receive an HTTP 200 OK response from your server.
- TIMEOUT: Logs indicating that your server hasn’t replied for the time limit set by the timeoutSeconds property.

Query string example
Light Color Skin
Copy
?limit=10&offset=20&start_date=2021-02-01&end_date=2021-02-25&order=created_at&status=SENT

Response

If successful, this action returns a list of webhook logs with their information in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "count": 15,
    "previous": "https://desk.sendbird.com/platform/v1/bots/37/webhook_logs?limit=1&order=created_at",
    "next": "https://desk.sendbird.com/platform/v1/bots/37/webhook_logs?limit=1&offset=2&order=created_at",
    "results": [
        {
            "id": 89,
            "bot": 37,
            "createdAt": "2021-02-06T06:05:07.173079Z",
            "updatedAt": "2021-02-06T06:05:07.276804Z",
            "status": "RECEIVED",
            "webhookUrl": "https://desk.sendbird.com/sendbird_bot_answer/AE384FCA-0B5B-4BD5-A5A8-457EC1BE29FE/",
            "chatMessage": {
                "id": 167605,
                "ticket": 154510,
                "userSendbirdId": "Mike Oh",
                "userType": "CUSTOMER",
                "createdAt": "2021-02-06T06:05:06.818000Z",
                "message": "Hi, I want to reset my password."
            }
        },
        ... # More webhook logs
    ]
}

List of response properties

Property nameTypeDescription

count

int

The total count of agents registered in the application.

previous

string

The URL to retrieve the previous page in the result set.

next

string

The URL to retrieve the next page in the result set.

results[]

array

An array of the bot’s webhook logs created between start_date and end_date.

(botWebhookEvent).id

int

The unique ID of the webhook event.

(botWebhookEvent).bot

string

The unique ID of the bot related to the webhook event.

(botWebhookEvent).chatMessage

nested object

An object that represents a customer’s message related to the webhook event.

(botWebhookEvent).status

string

The status of the webhook log. Valid values are limited to the following:
- SENT: Logs indicating that the webhook event is successfully sent from the Desk server to your server, which contains a customer’s message the bot received.
- RECEIVED: Logs indicating that the Desk server successfully received the webhook from your server, which contains the bot’s answer to a customer’s messages.
- ERROR: Logs indicating that the Desk server failed to receive an HTTP 200 OK response from your server.
- TIMEOUT: Logs indicating that your server hasn’t replied for the time limit set by the timeoutSeconds property.

(botWebhookEvent).webhookUrl

string

The webhook URL of your server to receive a webhook event from the Desk server.

(botWebhookEvent).updatedAt

string

The date and time when the webhook event was updated, in ISO 8601 format.

(botWebhookEvent).createdAt

string

The date and time when the webhook event was created, in ISO 8601 format.