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

Ticket note

Copy link

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

Copy link

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

Property nameTypeDescription

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

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

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

Copy link

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

HTTP request

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

Parameter

Copy link

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

Optional
Parameter nameTypeDescription

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.

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

Response

Copy link

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

{
    "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":"summer_agent@sendbird.com",
                "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

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

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

Copy link

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

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

Request body

Copy link

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

Required
Property nameTypeDescription

ticketId

int

Specifies the unique ID of the ticket to leave a note to.

note

string

Specifies the content of the ticket note.

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

Response

Copy link

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

{
    "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":"summer_agent@sendbird.com",
        "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

Copy link

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

{
    "message": "note is required.",
    "code": 400105
}
Error codeError messageDescription

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

Copy link

Update an existing ticket note.

HTTP request

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

Request body

Copy link

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

Required
Property nameTypeDescription

note

string

Specifies the content of the updated ticket note.

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

Response

Copy link

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

{
    "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":"summer_agent@sendbird.com",
        "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

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

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

Copy link

Delete a ticket note from the specified ticket.

HTTP request

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

Parameter

Copy link

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

ticket_note_id

int

Specifies the unique ID of the ticket note to delete.

Response

Copy link

If successful, this action returns the ID of the deleted ticket note 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 specified ticket doesn’t exist.",
    "code": 400201
}
Error codeError messageDescription

deskp400201

The specified ticket_note_id doesn’t exist.

The ticket note with the specified ticket_note_id doesn't exist.