Desk Platform API v1

Desk Platform API

Desk

Platform API

Home

Desk

Platform API

Ticket

Chat message

Chat message refer to conversations between agents and customers in the application or tickets.

Resource representation

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

Property name	Type	Description
id	int	The unique ID of a message.
messageId	int	The unique ID of a chat message in a ticket.
ticket	int	The unique ID of a ticket where the message belongs.
userSendbirdId	string	The Sendbird ID of a customer or agent who sent the message. A value of event indicates that the message was sent from Desk platform.
userType	string	The sender of the message. Valid values are AGENT, CUSTOMER, and EVENT. EVENT signifies all messages except messages sent from users.
createdAt	string	The time and date when the message was sent, in ISO 8601 format.
deletedAt	string	The time and date when the message was deleted, in ISO 8601 format.
requestedFrom	string	The method through which a message deletion was requested. Valid values are DASHBOARD and PLATFORM_API.
requestedBy	nested object	The information about the user who made a message deletion request.
message	string	The content of the message.
data	string	Additional information about the message such as custom font size, font type, or JSON formatted string.

Actions

API endpoints in this page are relative to the base URL allocated to your application as below:

List of endpoints

Endpoint	Refers to ...
/chat_messages	`https://desk-api-{application_id}.sendbird.com/platform/v1/chat_messages`
/tickets	`https://desk-api-{application_id}.sendbird.com/platform/v1/tickets`

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 {ticket_id}.

List of actions

Action	HTTP request
List chat messages	`GET` /chat_messages Retrieves a list of all chat messages in the application.
Retrieve a list of chat messages within a ticket	`GET` /tickets/{ticket_id}/chat_messages Retrieves a list of chat messages within a specific ticket.
Delete a chat message	`DELETE` /chat_messages/{chatmessage_id} Deletes a chat message in a ticket.
List message deletion logs	`GET` /chat_messages/delete_logs Retrieves a list of logs for deleted messages.

List chat messages

Retrieves a list of all chat messages in the application.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Properties

Required	Type	Description
created_at__gte	string	Restricts the search scope to only retrieve chat messages whose `createdAt` is equal to or greater than the specified value, in ISO 8601 format.
created_at__lt	string	Restricts the search scope to only retrieve chat messages whose `createdAt` is less than the specified value, in ISO 8601 format.

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 when receiving a response. The value of `offset` is also used as the starting index of each page. (Default: 0)
ticket_channel_type	string	Searches for chat messages with a specified channel type. Acceptable values are limited to SENDBIRD, SENDBIRD_IOS, SENDBIRD_ANDROID, SENDBIRD_JAVASCRIPT, FACEBOOK_CONVERSATION, FACEBOOK_FEED, TWITTER_STATUS, TWITTER_DIRECT_MESSAGE_EVENT, INSTAGRAM_COMMENT, and WHATSAPP_MESSAGE.

Query string example

?created_at__gte=2021-10-13T10:00:00&created_at__lt=2021-10-13T10:00:00&limit=50&offset=100

Response

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

Status: 200 OK

{
    "count": 20492,
    "previous": "https://desk-api-xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx.sendbird.com/platform/v1/chat_messages?limit=50&offset=50",
    "next": "https://desk-api-xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx.sendbird.com/platform/v1/chat_messages?limit=50&offset=150",
    "results": [
        {
            "id": 10933,
            "ticket": 3351,
            "userSendbirdId": "Jeff",
            "userType": "AGENT",
            "createdAt": "2019-03-12T05:25:41.032000Z",
            "message": "You'll get a 50% refund and the credit card request will be canceled in 3~5 business days."
        },
        ... # More chat messages
    ]
}

List of response properties

Property name	Type	Description
count	int	The total count of chat messages 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 chat messages.

Retrieve a list of chat messages within a ticket

Retrieves a list of chat messages within a specific ticket.

HTTP request

GET https://desk-api-{application_id}.sendbird.com/platform/v1/tickets/{ticket_id}/chat_messages

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
ticket_id	int	Specifies the unique ID of a ticket.

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)

Query string example

?limit=10&offset=20

Response

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

Status: 200 OK

{
    "count": 43,
    "previous": "https://desk-api-xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx.sendbird.com/platform/v1/tickets/3351/chat_messages?limit=10&offset=10",
    "next": "https://desk-api-xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx.sendbird.com/platform/v1/tickets/3351/chat_messages?limit=10&offset=30",
    "results": [
        {
            "id": 38763,
            "ticket": 3351,
            "userSendbirdId": "event",
            "userType": "EVENT",
            "createdAt": "2020-05-11T14:25:54.189000Z",
            "message": "Welcome to Sendbird!",
            "data": "Summer special"
        },
        ... # More chat messages
    ]
}

List of response properties

Property name	Type	Description
count	int	The total count of chat messages within the ticket.
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 chat messages.

Delete a chat message

Deletes a chat message in a ticket.

HTTP request

DELETE https://desk-api-{application_id}.sendbird.com/platform/v1/tickets/{ticket_id}/chat_messages/{chatmessage_id}

Parameters

The following table lists the parameters that this action supports.

Required

Property name	Type	Description
ticket_id	int	Specifies the unique ID of a ticket.
chatmessage_id	int	Specifies the unique ID of a chat message to delete.

Response

If successful, this action returns the ID of the deleted message in the response body.

Status: 200 OK

{
    "id": 51
}

Error

In the case of an error, an error object like below is returned. See the error code table for more details.

Status: 400 Bad Request

{
    "message": "The ticket is not closed yet.",
    "code": 400600,
    "error": true
}

Error code	Error message	Description
deskp400105	The ticket_id parameter is required. The chatmessage_id parameter is required.	One or more required parameters are missing.
deskp400111	The value of id should be integer.	The specified ID is in incorrect format.
deskp400201	The specified message doesn’t exist.	The message with the specified `chatmessage_id` doesn't exist.
deskp400500	The message was already deleted.	The message with the specified `chatmessage_id` was already deleted.
deskp400600	The ticket is not closed yet.	A chat message can't be deleted as the ticket isn't closed yet.
deskp400601	The specified message can’t be deleted.	Message deletion isn't supported for the chat message with the specified `chatmessage_id`.
desk500500	An internal error has occurred.	An error occured while processing the request.

List message deletion logs

Retrieve a list of logs for deleted chat messages.

HTTP request

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

Request body

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

Property

Required	Type	Description
limit	int	Specifies the number of results to return per page. Acceptable values are 1 to 100, 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)

Optional	Type	Description
start_date	string	Specifies the start date of the logs to retrieve, in YYYY-MM-DD format. The time range between `start_date` and `end_date` should be less than or equal to one year, in UTC. If not specified, the default time range is 30 days prior to `end_date` below.
end_date	string	Specifies the end date of the logs to retrieve, in YYYY-MM-DD format. The time range between `start_date` and `end_date` should be less than or equal to one year, in UTC. If not specified, the current date becomes the last date of the log list.

Response

If successful, this action returns a list of log resources for deleted messages in the response body.

Status: 200 OK

{
    "id": 1,
    "ticketId": 1341,
    "messageId": 114161,
    "userType": "AGENT",
    "message": "Thank you for your patience.",
    "deletedAt": "2019-07-18T09:13:44.846926Z",
    "requestedFrom" : "DASHBOARD",
    "requestedBy" : {
        "id": 1,
        "displayName": "Summer",
        "project": 1,
        "user": 1,
        "sendbirdId": "agent_id_1234",
        "role": "AGENT",
        "createdAt": "2018-03-28T08:53:54.222766Z",
        "status": "ACTIVE",
        "connection": "ONLINE",
        "email":"summer_agent@sendbird.com",
        "photoThumbnailUrl":"https://sendbird.com/profile_summer.png",
        "connectionUpdatedAt": "2019-11-13T09:03:13.060232Z",
        "tier": "EXPERT"
    }
}

Error

In the case of an error, an error object like below is returned. See the error code table for more details.

Status: 400 Bad Request

{
    "message": "The value of limit should be integer.",
    "code": 400111,
    "error": true
}

Error code	Error message	Description
deskp400111	The value of limit should be integer. The value of offset should be integer.	The value of either `limit` or `offset` isn't integer.
deskp400111	The value of start_date should be YYYY-MM-DD. The value of end_date should be YYYY-MM-DD.	The value of either `start_date` or `end_date` isn't in YYYY-MM-DD format.
deskp400113	The value of limit should be between 1 to 100.	The value specified in `limit` is out of the acceptable range, which is 1 to 100, inclusive.
deskp400113	The date range should be within 1 year.	The time range between `start_date` and `end_date` is longer than one year.

Try API requests