Desk / Platform API
Desk Platform API v1
Desk Platform API
Desk
Platform API
Version 1
Home
/
Desk
/
Platform API
/
Ticket

Chat message

Copy link

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

Resource representation

Copy link

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

Property nameTypeDescription

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

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

List of endpoints

Copy link
EndpointRefers 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

Copy link
ActionHTTP 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

Copy link

Retrieves a list of all chat messages in the application.

HTTP request

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Properties
RequiredTypeDescription

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.

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 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.

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

Response

Copy link

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

{
    "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

Copy link
Property nameTypeDescription

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

Copy link

Retrieves a list of chat messages within a specific ticket.

HTTP request

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

ticket_id

int

Specifies the unique ID of a ticket.

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)

?limit=10&offset=20

Response

Copy link

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

{
    "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

Copy link
Property nameTypeDescription

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

Copy link

Deletes a chat message in a ticket.

HTTP request

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Property nameTypeDescription

ticket_id

int

Specifies the unique ID of a ticket.

chatmessage_id

int

Specifies the unique ID of a chat message to delete.

Response

Copy link

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

{
    "id": 51
}

Error

Copy link

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

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

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

Copy link

Retrieve a list of logs for deleted chat messages.

HTTP request

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

Request body

Copy link

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

Property
RequiredTypeDescription

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)

OptionalTypeDescription

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

Copy link

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

{
    "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

Copy link

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

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

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.