Desk / JavaScript
Home
/
Desk
/
JavaScript

Key functions

This page explains the key functions of Sendbird Desk consisting of how to create, handle, and close a ticket from your client app.


Message types

There are two types of messages in Desk. User messages are messages sent from an agent or a customer while Admin messages are messages sent from the Desk server without a specific sender.

Among User messages, the following three subtypes of messages that have additional implementation processes are grouped into Rich messages: URL preview, confirmation request for ticket closing, and feedback request messages. Their custom message type is specified as SENDBIRD_DESK_RICH_MESSAGE and the type of the message is determined in the message.data as below.

Rich messages

Message typemessage.customTypemessage.data

URL previews

SENDBIRD_DESK_RIGH_MESSAGE

SENDBIRD_DESK_URL_PREVIEW

Confirmation request for ticket closing

SENDBIRD_DESK_RICH_MESSAGE

SENDBIRD_DESK_INQUIRE_TICKET_CLOSURE

Feedback request

SENDBIRD_DESK_RICH_MESSAGE

SENDBIRD_DESK_CUSTOMER_SATISFACTION

Admin messages are classified into Notification messages and System messages. System messages have SENDBIRD_DESK_ADMIN_MESSAGE_CUSTOM_TYPE as their custom message type that makes it to be distinguished from notification messages. They also have subtypes specified in the message.data property.


Create a ticket

Implement the Ticket.create() method to create a new ticket either before or after the customer’s initial message. Once a ticket is successfully created in the Desk server, you can access the ticket and its channel through the callback from the server. Until a customer sends the first message, agents can’t see the ticket on the dashboard. When a conversation starts, the ticket is assigned to an available agent by the Desk server while messages are sent and received through the Chat SDK.

Light Color Skin
Copy
Ticket.create(TICKET_TITLE, USER_NAME, GROUP_KEY, CUSTOM_FIELDS, PRIORITY, RELATED_CHANNEL_URLS, (ticket, error) => {
    if (error) {
        // Handle error.
    }

    // The ticket.channel property indicates the group channel object within the ticket.
});

You can use the following parameters when creating a ticket.

List of arguments

ArgumentTypeDescription

TICKET_TITLE

string

Specifies the title of the ticket.

USER_NAME

string

Specifies the name of the user who submits or receives the ticket.

GROUP_KEY

string

Specifies the identifier of a specific team.

CUSTOM_FIELDS

nested object

Specifies additional information of the ticket that consists of key-value custom items. Only custom fields already registered in Settings > Ticket fields on your dashboard can be used as a key.

PRIORITY

string

Specifies the priority value of the ticket. Higher values stand for higher priority. Valid values are LOW, MEDIUM, HIGH and URGENT.

RELATED_CHANNEL_URLS

array

Specifies group channels in Sendbird Chat platform that are related to this ticket and consists of channel URLs and channel names. Up to three related channels can be added.


Add custom information to a ticket

Use the ticket.setCustomFields() method to add additional information about a ticket.

Light Color Skin
Copy
const customFields = {
    'Product type': 'Desk',
    'line': '3'
};

ticket.setCustomFields(customFields, (ticket, error) => {
    if (error) {
        // Handle error.
    }

    // The customFields property of a ticket has been updated.
});

Note: Only custom fields already registered in Desk > Settings > Ticket fields of your dashboard can be used as a key.


Add custom information to a customer

Use the setCustomerCustomFields() method of the SendBirdDesk to make your customers add additional information about themselves.

Note: Only custom fields already registered in Settings > Customer fields of your dashboard can be used as a key.

Light Color Skin
Copy
SendBirdDesk.setCustomerCustomFields(
    {
        gender: "male",
        age: 20
    },
    (error) => {
        if (!error) {
            // Custom fields for the customer are set.
            // Some fields can be ignored if their keys aren’t registered in the dashboard.
        }
    }
);

Related channels indicate group channels in Sendbird Chat platform that are related to a ticket. When creating a ticket, pass one or more URLs (channel_url) of the related group channel as an argument to the relatedChannelUrls parameter in the Ticket.create() method. To update related channels, use the ticket.setRelatedChannelUrls() instead. The ticket.relatedChannels property in the callback indicates the group channel object of related channels and it contains channel names and their URLs.

Light Color Skin
Copy
Ticket.create(TICKET_TITLE, USER_NAME, GROUP_KEY, CUSTOM_FIELDS, PRIORITY, RELATED_CHANNEL_URLS, (ticket, error) => {
    if (error) {
        // Handle error.
    }

    ...
});
Light Color Skin
Copy
ticket.setRelatedChannelUrls(RELATED_CHANNEL_URLS, (ticket, error) => {
    if (error) {
        // Handle error.
    }

    // The ticket's relatedChannels property has been updated.
});

Note: Up to three related channels can be added per ticket.


Add URL previews

With URL previews, your application users can meet their expectations of what they’re going to get before they open the link during the conversations.

To preview URLs, every text message should be checked if it includes any URLs. When a text message including a URL is successfully sent, the URL should be extracted and passed to Sendbird server using the getUrlPreview() method. Set the parsed data received from the server as a JSON object and stringify the object to pass it as an argument to a parameter in the updateUserMessage() method. Then the updated message with URL preview is delivered to the client apps through the onMessageUpdated() method of the channel event handler.

Light Color Skin
Copy
ticket.channel.sendUserMessage(TEXT, (message, error) => {
    if (!error) {
        const message = message;
        if (SendBirdDesk.Message.UrlRegExp.test(message.message)) {
            const urlInMessage = SendBirdDesk.Message.UrlRegExp.exec(message.message)[0];
            SendBirdDesk.Ticket.getUrlPreview(urlInMessage, (response, error) => {
                if (error) {
                    // Handle error.
                }

                this.ticket.channel.updateUserMessage(
                    message.messageId,
                    message.message,
                    JSON.stringify({
                        type: SendBirdDesk.Message.DataType.URL_PREVIEW,
                        body: {
                            url: urlInMessage,
                            site_name: response.data.siteName,
                            title: response.data.title,
                            description: response.data.description,
                            image: response.data.image
                        }
                    }),
                    message.customType,
                    (response, error) => {
                        if (error) {
                            // Handle error.
                        }

                        this.updateMessage(response);
                });
            });
        }
    }
});

In the onMessageUpdated() method of the channel event handler, you can find the data for URL preview in the message.data property as below.

Light Color Skin
Copy
{
    "type": "SENDBIRD_DESK_URL_PREVIEW",
    "body": {
        "url": "https://sendbird.com/",
        "site_name": "Sendbird",
        "title": "Sendbird - A Complete Chat Platform, Messaging and Chat SDK and API",
        "description": "Sendbird's chat, voice and video APIs and SDKs connect users through immersive, modern communication solutions that drive better user experiences and engagement.",
        "image": "https://6cro14eml0v2yuvyx3v5j11j-wpengine.netdna-ssl.com/wp-content/uploads/sendbird_thumbnail.png"
    }
}

Receive system messages

Admin messages are customizable messages that are sent by the system, and there are two types of admin messages. Notifications are messages that are sent and displayed to both customers and agents, such as welcome messages or delay messages. System messages are messages sent and displayed to agents in the Ticket details view when a ticket has some changes, such as changes in ticket status and assignee.

Note: You can customize notifications in Settings > Triggers, and system messages in Settings > System messages on your dashboard.

When the client app receives the message through the onMessageReceived() method of the channel event handler, system messages are distinguished from notification messages by the value of the message.custom_type, and their subtype is specified in the message.data as below.

Light Color Skin
Copy
{
    "message_id" : 40620745,
    "type": "ADMM",
    "custom_type": "SENDBIRD_DESK_ADMIN_MESSAGE_CUSTOM_TYPE",
    "data": "{\"type\": \"SYSTEM_MESSAGE_TICKET_ASSIGNED_BY_SYSTEM\", \"ticket\": <Ticket Object>}",
    ...
    "message": "The ticket is automatically assigned to Cindy.",
    ...
}

Note: The transfer property appears only when the data has SYSTEM_MESSAGE_TICKET_TRANSFERRED_BY_AGENT.

System messages are intended to be displayed for agents only. Refer to the following sample code to avoid displaying them to your customers.

Light Color Skin
Copy
function isVisible(message) {
    let data = {};
    try {
        data = message.data ? JSON.parse(message.data) : null;
    } catch (e) {
        throw e;
    }

    message.isSystemMessage = message.customType === 'SENDBIRD_DESK_ADMIN_MESSAGE_CUSTOM_TYPE';
    message.isAssigned = data.type === SendBirdDesk.Message.DataType.TICKET_ASSIGN;
    message.isTransferred = data.type === SendBirdDesk.Message.DataType.TICKET_TRANSFER;
    message.isClosed = data.type === SendBirdDesk.Message.DataType.TICKET_CLOSE;

    return !message.isSystemMessage
        && !message.isAssigned
        && !message.isTransferred
        && !message.isClosed;
}

Request confirmation to close a ticket

While admins have permission to directly close a ticket, agents can either close a ticket as admins do or ask customers whether to close a ticket, depending on the agent permission setting. The confirmation request message can have three types of state as below.

Confirmation states

StateDescription

WAITING

Set when an agent sends a confirmation request message.

CONFIRMED

Set when a customer replied Yes.

DECLINED

Set when a customer replied No.

When a customer replies to the message, the response Yes or No is sent to the Desk server by calling the Ticket.confirmEndOfChat() method. Then, the state of the confirmation request message is changed to CONFIRMED or DECLINED.

Light Color Skin
Copy
Ticket.confirmEndOfChat(USER_MESSAGE, 'yes'|'no', (ticket, error) => {
    if (error) {
        // Handle error.
    }

    ...
});

Sendbird server notifies the customer’s client app of updates through the onMessageUpdate() method of the channel event handler.

Light Color Skin
Copy
channelHandler.onMessageUpdated = (channel, message) => {
    SendBirdDesk.Ticket.getByChannelUrl(channel.url, (ticket, error) => {
        if (error) {
            // Handle error.
        }

        let data = JSON.parse(message.data);
        const isClosureInquired = data.type === SendBirdDesk.Message.DataType.TICKET_INQUIRE_CLOSURE;
        if (isClosureInquired) {
            const closureInquiry = data.body;
            switch (closureInquiry.state) {
                case SendBirdDesk.Message.ClosureState.WAITING:
                    // Implement your code for the UI when there is no response from the customer.
                    break;
                case SendBirdDesk.Message.ClosureState.CONFIRMED:
                    // Implement your code for the UI when the customer confirms to close the ticket.
                    break;
                case SendBirdDesk.Message.ClosureState.DECLINED:
                    // Implement your code for the UI when the customer declines to close the ticket.
                    break;
            }
        }
    });
};

Note: You can find the stringified JSON object of the following in the message.data property within the onMessageUpdate() of the channel event handler.

Light Color Skin
Copy
{
    "type": "SENDBIRD_DESK_INQUIRE_TICKET_CLOSURE",
    "body": {
        "state": "CONFIRMED"
    }
}

Request customer feedback

You can send a message to customers right after closing a ticket to ask whether they are satisfied with the support provided through the ticket. When the Customer satisfaction rating feature is turned on in your dashboard, customers get a message asking to give a score and leave a comment as feedback. The message can have two states as below.

Request states

StateDescription

WAITING

Set when an agent sends a customer feedback request message.

CONFIRMED

Set when a customer sends a response.

When a customer replies to the message, their score and comment for the ticket are sent to the Desk server by calling the ticket.submitFeedback() method. Then, the state of the confirmation request message is changed to CONFIRMED.

Light Color Skin
Copy
ticket.submitFeedback(USER_MESSAGE, SCORE, COMMENT, (ticket, error) => {
    if (error) {
        // Handle error.
    }

    ...
});

Sendbird server notifies the customer’s client app of updates through the onMessageUpdate() method of the channel event handler.

Light Color Skin
Copy
channelHandler.onMessageUpdated = (channel, message) => {
    SendBirdDesk.Ticket.getByChannelUrl(channel.url, (ticket, error) => {
        if (error) {
            // Handle error.
        }

        let data = JSON.parse(message.data);
        const isFeedbackMessage = data.type === SendBirdDesk.Message.DataType.TICKET_FEEDBACK;
        if (isFeedbackMessage) {
            const feedback = data.body;
            switch (feedback.state) {
                case SendBirdDesk.Message.FeedbackState.WAITING:
                    // Implement your code for the UI when there is no response from the customer.
                    break;
                case SendBirdDesk.Message.FeedbackState.CONFIRMED:
                    // Implement your code for the UI when there is a response from the customer.
                    break;
            }
        }
    });
};

Note: You can find the stringified JSON object of the following in the message.data property within the onMessageUpdate() of the channel event handler.

Light Color Skin
Copy
{
    "type": "SENDBIRD_DESK_CUSTOMER_SATISFACTION",
    "body": {
        "state": "CONFIRMED",
        "customerSatisfactionScore": 3, // Score range: 1 to 5
        "customerSatisfactionComment": "It was really helpful :)."  // Comment is optional.
    }
}

Reopen a closed ticket

A closed ticket can be reopened by using the ticket.reopen() method.

Light Color Skin
Copy
closedTicket.reopen((openTicket, error) => {
    if (error) {
        // Handle error.
    }

    // Implement your code to update the ticket list with the result object in the "openTicket" parameter.
});

Retrieve a list of tickets

You can retrieve a list of the current customer’s open and closed tickets by using the Ticket.getOpenedList() and Ticket.getClosedList().

Note: Only 10 tickets can be retrieved per request.

getOpenedList()
getClosedList()
Light Color Skin
Copy
Ticket.getOpenedList(OFFSET, (openedTickets, error) => {
    if (error) {
        // Handle error.
    }

    const tickets = openedTickets;
    // offset += tickets.length; for the next tickets.
    // Implement your code to display the ticket list.
});
Light Color Skin
Copy
Ticket.getClosedList(OFFSET, (closedTickets, error) => {
    if (error) {
        // Handle error.
    }

    const tickets = closedTickets;
    // offset += tickets.length; for the next tickets.
    // Implement your code to display the ticket list.
});

For tickets set with custom fields, you can add a filter to the getOpenList() and getClosedList() to sort tickets by keys and values of custom fields.

Light Color Skin
Copy
const customFieldFilter = {'subject' : 'doggy_doggy'};
Ticket.getOpenedList(OFFSET, customFieldFilter, (openedTickets, error) => {
    if (error) {
        // Handle error.
    }

    const tickets = openedTickets;
    // offset += tickets.length; for the next tickets.
    // Implement your code to display the ticket list.
});

Retrieve a ticket

You can retrieve a specific ticket with its channel URL.

Light Color Skin
Copy
Ticket.getByChannelUrl(CHANNEL_URL, (ticket, error) => {
    if (error) {
        // Handle error.
    }

    ...
});

Display open ticket count

You can display the number of open tickets on your client app by using the Ticket.getOpenCount().

Light Color Skin
Copy
Ticket.getOpenCount((count, error) => {
    if (error) {
        // Handle error.
    }

    const numberOfOpenTickets = count;
    // Implement your code with the value of the "count" parameter.
});

Close a ticket

Use the ticket.close() method to allow customers to directly close a ticket on their client app so that agents can quickly switch to other customer inquiries without delay or a customer’s confirmation.

Light Color Skin
Copy
ticket.close(CLOSE_COMMENT, (ticket, error) => {
    if (error) {
        // Handle error.
    }

    ...
});

Note: Only active and idle tickets can be closed by customers.