Desk Platform API v1

Desk Platform API

Version 1

Ticket note

Leave a note in tickets so that agents can have a fuller context of the issue and engage with customers on a more personal level. This API can also help the next assignee catch up with the conversation when transferred. Ticket notes are visible to admins and agents only, not customers.

Resource representation

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

Property name	Type	Description
count	int	The total number of ticket notes made during the specified time period.
id	int	The unique ID of the ticket note.
ticket_id	int	The unique ID of the ticket where the note was left to.
note	string	The content of the ticket note.
requestedFrom	string	The method through which a ticket note was created. Valid values are `DASHBOARD` and `PLATFORM_API`.
createdBy	nested object	A JSON object that contains information about the agent who left the note, such as their user ID, role, and the time when the note was created. If the ticket notes were created through a Platform API request, the value of this property is `null`.
createdAt	string	The date and time when the ticket note was created, in ISO 8601 format.
updatedAt	string	The date and time when the ticket note was last updated, in ISO 8601 format.

Actions

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

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 ticket notes	`GET` /ticket_notes Retrieves a list of ticket notes created during a specific time period.
Leave a note in a ticket	`POST` /ticket_notes Leave a note in a ticket.
Update a ticket note	`PATCH` /ticket_notes/{ticket_note_id} Updates an existing ticket note in a ticket.
Delete a ticket note	`DELETE` /ticket_notes/{ticket_note_id} Deletes a ticket note from a ticket.

List ticket notes

Retrieves a list of ticket notes created during a specific time period.

HTTP request

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

Parameter

The following table lists the properties of an HTTP request 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 100, 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)
start_date	string	Specifies the start date of the ticket notes 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`.
end_date	string	Specifies the end date of the ticket notes 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 list.

Query string example

?limit=50&offset=0&start_date=2022-01-03&end_date=2022-03-03

Response

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

Status: 200 OK

{
    "count": 40,
    "next": "https://desk-api-{application_id}.sendbird.com/platform/v1/ticket_notes?limit=10&offset=30",
    "previous": "https://desk-api-{application_id}.sendbird.com/platform/v1/ticket_notes?limit=10&offset=10",
    "results": [
        {
            "id": 51,
            "ticket_id": 12512,
            "note": "need to transfer to sales",
            "requestedFrom" : "PLATFORM_API",
            "createdBy": {
                "id": 1,
                "displayName": "Summer",
                "project": 1,
                "user": 1,
                "sendbirdId": "sendbird_desk_agent_id_1",
                "role": "AGENT",
                "createdAt": "2018-03-28T08:53:54.222766Z",
                "status": "ACTIVE",
                "connection": "ONLINE",
                "email":"[email protected]",
                "photoThumbnailUrl":"https://sendbird.com/agent_1.png",
                "connectionUpdatedAt": "2019-11-13T09:03:13.060232Z",
                "tier": "EXPERT"
            },
            "createdAt": "2019-07-18T09:13:44.846926Z",
            "updatedAt": "2019-07-18T09:13:44.846926Z"
        },
        {
            ...
        },
        ... # More ticket notes...
    ]
}

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 limit parameter should be integer.",
    "code": 400111
}

Error code	Error message	Description
deskp400111	The limit parameter should be integer.	The specified `limit` is in incorrect format.
deskp400111	The offset parameter should be integer.	The specified `offset` is in incorrect format.
deskp400111	The value of start_date should be YYYY-MM-DD.	The specified `start_date` is in incorrect format.
deskp400111	The value of end_date should be YYYY-MM-DD.	The specified `end_date` is in incorrect format.
deskp400113	The value of limit should be between 1 and 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` exceeds one year.

Leave a note in a ticket

Create a new note in a ticket. You can leave multiple ticket notes in a ticket but should create one at a time.

HTTP request

POST https://desk-api-{application_id}.sendbird.com/platform/v1/ticket_notes

Request body

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

Required

Property name	Type	Description
ticketId	int	Specifies the unique ID of the ticket to leave a note to.
note	string	Specifies the content of the ticket note.

Request body

{
    "ticketId": 12512,
    "note": "first thing back in office next monday"
}

Response

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

Status: 200 OK

{
    "id": 51, 
    "note": "first thing to answer in the morning",
    "ticketId": 12512,
    "requestedFrom" : "PLATFORM_API",
    "createdBy": { 
        "id": 1,
        "displayName": "Summer",
        "project": 1,
        "user": 1,
        "sendbirdId": "sendbird_desk_agent_id_***",
        "role": "AGENT",
        "createdAt": "2018-03-28T08:53:54.222766Z",
        "status": "ACTIVE",
        "connection": "ONLINE",
        "email":"[email protected]",
        "photoThumbnailUrl":"https://sendbird.com/**.png",
        "connectionUpdatedAt": "2019-11-13T09:03:13.060232Z",
        "tier": "EXPERT"
    },
    "createdAt": "2019-07-18T09:13:44.846926Z",
    "updatedAt": "2019-07-18T09:13:44.846926Z"
}

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": "note is required.",
    "code": 400105
}

Error code	Error message	Description
deskp400105	ticketId is required.	The `ticketId` property is missing.
deskp400105	note is required.	The `note` property is missing.
deskp400111	The note parameter should be string.	The specified `note` property is in incorrect format.
deskp400201	The specified ticketId doesn’t exist.	The ticket note with the specified `ticketId` doesn't exist.

Update a ticket note

Update an existing ticket note.

HTTP request

PATCH https://desk-api-{application_id}.sendbird.com/platform/v1/ticket_notes/{ticket_note_id}

Request body

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

Required

Property name	Type	Description
note	string	Specifies the content of the updated ticket note.

Request body

{
    "note": "issue resolved on monday"
}

Response

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

Status: 200 OK

{
    "id": 51,
    "ticketId": 12512,
    "note": "issue resolved on monday",
    "requestedFrom" : "PLATFORM_API",
    "createdBy": {
        "id": 1,
        "displayName": "Summer",
        "project": 1,
        "user": 1,
        "sendbirdId": "sendbird_desk_agent_id_***",
        "role": "AGENT",
        "createdAt": "2018-03-28T08:53:54.222766Z",
        "status": "ACTIVE",
        "connection": "ONLINE",
        "email":"[email protected]",
        "photoThumbnailUrl":"https://sendbird.com/**.png",
        "connectionUpdatedAt": "2019-11-13T09:03:13.060232Z",
        "tier": "EXPERT"
    },
    "createdAt": "2019-07-18T09:13:44.846926Z",
    "updatedAt": "2019-07-18T09:13:44.846926Z"
}

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 note parameter should be string.",
    "code": 400111
}

Error code	Error message	Description
deskp400111	The note parameter should be string.	The specified `note` is in incorrect format.
deskp400201	The specified ticket_note_id doesn’t exist.	The ticket note with the specified `ticket_note_id` doesn't exist.

Delete a ticket note

Delete a ticket note from the specified ticket.

HTTP request

DELETE https://desk-api-{application_id}.sendbird.com/platform/v1/ticket_notes/{ticket_note_id}

Parameter

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
ticket_note_id	int	Specifies the unique ID of the ticket note to delete.

Response

If successful, this action returns an empty response body.

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

{
    "code": "deskp400201",
    "message": "The specified ticket_note_id doesn’t exist."
}

Error code	Error message	Description
deskp400201	The specified ticket_note_id doesn’t exist.	The ticket note with the specified `ticket_note_id` doesn't exist.

On this page

Resource representation Actions List ticket notes Leave a note in a ticket Update a ticket note Delete a ticket note