Desk Platform API v1

Desk Platform API

Version 1

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 on your dashboard.
When sending a custom 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 on your dashboard.

Resource representation

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

Property name	Type	Description
id	int	The unique ID 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. If the `bot.type` property is FAQ, the value returned is null.
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.
canReceiveTransferredTickets	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.
fallbackRetryLimit	int	The maximum number of total fallback messages a custom bot can 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 a custom bot sends to your customer when the Desk server fails to receive an HTTP 200 OK response from your server.
timeoutMessage	string	The fallback message for timeout. A custom bot sends the message to your customer when the Desk server doesn’t receive a response from your server within a specified time limit set by the `timeoutSeconds` property after successfully delivering the webhook event for a customer’s message.
timeoutSeconds	int	Time limit in seconds to send a timeout fallback message. Valid value ranges 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.
noResultsMessage	string	The message sent by an FAQ bot when there isn't a question and answer that corresponds to a customer's request.
questionSelectedMessage	string	The system message showing a selected question, which is displayed only to agents when a customer selects a question.
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 {bot_id}.

List of actions

Action	HTTP 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 custom 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

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

Parameters

The following table lists the parameters that this action supports.

Optional

Parameter name	Type	Description
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 when receiving a response. The value of `offset` is also used as the starting index of each page. (Default: 0)

Query string example

?limit=10&offset=20

Response

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

Status: 200 OK

{
    "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",
            "canReceiveTransferredTickets": true,
            "isUnreadError": true,
            "welcomeMessage": "Welcome to Sendbird! Is there anything I can help with? :)",
            "fallbackRetryLimit": 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.",
            "noResultsMessage": null,
            "questionSelectedMessage": null,
            "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 name	Type	Description
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

Updates information on a bot.

HTTP request

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 name	Type	Description
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

Updates information on a specific bot.

HTTP request

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 name	Type	Description
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 name	Type	Description
name	string	Specifies the name of a bot.
photoUrl	string	Specifies the profile image URL of a bot.
profileFile	file	Uploads the file of a 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 custom bot receives a message from a customer.
canReceiveTransferredTickets	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.
fallbackRetryLimit	int	Specifies the maximum number of total fallback messages a custom bot can 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 a custom bot sends to your customer when the Desk server fails to receive an HTTP 200 OK response from your server.
timeoutMessage	string	Specifies the fallback message for timeout. A custom bot sends the message 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 for the time limit set by the `timeoutSeconds` property.
timeoutSeconds	int	Specifies time limit in seconds to send a timeout fallback message. Acceptable value ranges 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

{
    "name": "bot_mike",
    "webhookUrl": "https://example.com/",
    "canReceiveTransferredTickets": true,
    "welcomeMessage": "Hi! How can I help you?",
    "fallbackRetryLimit": 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 custom bot’s message to a customer.

HTTP request

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 name	Type	Description
bot_id	int	Specifies the unique ID of a custom bot.

Request body

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

Properties

Required	Type	Description
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.

Optional	Type	Description
data	array of objects	Specifies a `JSON` object or an array of `JSON` objects that hold additional message information.

Request body example

{
    "botWebhookEventId": 20,
    "message": "It's my pleasure! Need anything else?",
    "data": [
        {
            "fontStyle": "Arial",
            "fontSize" : 10
        }
    ]
}

Response

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

Status: 200 OK

{
    "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 name	Type	Description
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

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

Required	Type	Description
bot_id	int	Specifies the unique ID of the target bot.

Optional	Type	Description
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 a bot received. - RECEIVED: Logs indicating that the Desk server successfully received the webhook event from your server, which contains a 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

?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

{
    "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 name	Type	Description
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.

On this page

Requirements Resource representation Actions List bots View a bot Update a bot Send a bot's message Get a bot's webhook logs