Nominal Package Missing

    sendbird-desk
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.22 • Public • Published

    Sendbird Desk SDK for JavaScript

    Platform Languages

    Table of contents

    1. Introduction
    2. Before getting started
    3. Getting started
    4. Creating your first ticket
    5. Implementation guide

    Introduction

    Sendbird Desk enables strong customer engagement through live, in-app support. The Desk SDK lets you easily initialize, configure, and build customer support-related functionality into your JavaScript applications.

    How it works

    Sendbird Desk is a plugin of the Sendbird Chat Platform for managing tickets, and thus Desk events are handled by event handlers through the Chat SDK.

    Every ticket is assigned appropriate agents and will be directed to a chat's group channel, which implements real-time messaging on tickets with Sendbird Chat SDK.

    Concepts

    These are a few of the main components of Desk SDK.

    • Channels: The various ways through which support can be requested e.g. in-app chats from different OS platforms or social media like Facebook and Instagram.
    • Tickets: A ticket is created when a customer and agent start a conversation and is seen as a unit of customer’s inquiry. There are five types of tickets.
    • Agents: An agent receives the requests and also handles the conversation in the Sendbird Dashboard.
    • Admins: Admins are agents who are granted the additional privileges of managing the overall dashboard settings and the tickets.
    • Messages: Desk has two types of messages that fall into further subtypes. The following table shows the hierarchical structure of messages.
    Sender Subtypes
    User message Agent or customer Rich messages
    Admin message Sent from the Desk server without a specific sender Notification messages and System messages

    Note: Rich messages are further classified into URL preview, confirmation request for ticket closing, and feedback request messages.

    More about Sendbird Desk SDK for JavaScript

    Find out more about Sendbird Desk SDK for JavaScript on Desk SDK for JavaScript doc. If you have any comments or questions regarding bugs and feature requests, visit Sendbird community.


    Before getting started

    This section shows the prerequisites you need to check to use Sendbird Desk SDK for JavaScript.

    Requirements

    Supported browsers

    • All modern versions of Chrome, FireFox, Edge, Safari, and etc. supporting ES6+
    • IE 11+
    • Mobile browsers (Android/iOS)

    Getting started

    This section gives you information you need to get started with Sendbird Desk SDK for JavaScript.

    Try the sample app

    Our sample app demonstrates the core features of Sendbird Desk SDK. Download the app from our GitHub repository to get an idea of what you can do with the actual SDK and to get started building your own project.

    Step 1: Create a Sendbird application from your dashboard

    A Sendbird application comprises everything required in a chat service including users, message, and channels. To create an application:

    1. Go to the Sendbird Dashboard and enter your email and password, and create a new account. You can also sign up with a Google account.
    2. When prompted by the setup wizard, enter your organization information to manage Sendbird applications.
    3. Lastly, when your dashboard home appears after completing setup, click Create + at the top-right corner.

    Regardless of the platform, only one Sendbird application can be integrated per app; however, the application supports communication across all Sendbird’s provided platforms without any additional setup.

    Note: All the data is limited to the scope of a single application, thus users in different Sendbird applications are unable to chat with each other.

    Step 2: Download and install the Desk SDK

    Installing the Desk SDK is simple if you’re familiar with using external libraries or SDK’s in your projects. These are the following three methods for Desk SDK implementation:

    Install the Desk SDK with npm by entering the command below on the command line.

    # npm
    ~$ cd /path/to/your-project
    ~$ npm install --save sendbird-desk

    Automatically download our Desk SDK with just an npm install command by adding sendbird-desk dependency to the package.json file of your project.

    Download the latest Desk SDK for JavaScript, copy the Desk SDK to your project classpath (most commonly the lib/ directory), and then include the Desk SDK file to your working file.

    <script src="lib/SendBird.Desk.min.js"></script>

    Creating your first ticket

    After installation has been completed, a ticket can be created for communication between an agent and customer. Follow the step-by-step instructions below to create your first ticket.

    Step 1: Initialize the Desk SDK

    First, a SendBirdDesk instance must be initialized when launching a client app. Before initializing SendBirdDesk instance, you need to initialize Sendbird with the APP_ID of your Sendbird application from the dashboard. Pass the initialized SendBird instance as an argument as a parameter in the SendBirdDesk.init() method.

    Implement the following command in your project path.

    SendBirdDesk.init(SendBird);

    Note: The same APP_ID should be used for both Desk and Chat SDKs. If you initiate the Sendbird Desk with a SendBird instance of another App_ID, all existing data in the client app will be cleared.

    It is possible to use the Chat SDK only or both Chat and Desk SDKs together in your client app depending on the chat service you want to provide.

    SDK Used for
    Chat SDK In-app messenger where customers can chat with each other.
    Chat and Desk SDKs Tickets where customers can chat with agents.

    Step 2: Authenticate to Sendbird server

    Customers can request support from various types of channels: in-app chats or social media such as Facebook, Instagram and Twitter. To use these support features of Desk SDK, the SendBirdDesk instance should be connected with Sendbird server depending on which channel the request is from:

    • Sendbird Chat Platform: Authenticate using the authenticate() method with their user IDs.
    • Social media platforms: No authentication needed as customers are automatically registered in the dashboard with their social media accounts.

    Once authenticated, customers can live-chat with agents based on Sendbird Chat platform.

    const sb = new SendBird({ appId: APP_ID });
    sb.connect(USER_ID, ACCESS_TOKEN, (user, error) => {
        if (error) throw error;
        SendBirdDesk.init(SendBird);
        SendBirdDesk.authenticate(USER_ID, ACCESS_TOKEN, (user, error) => {
            if (error) throw error;
            // SendBirdDesk is now initialized, and the customer is authenticated.
        });
    }

    Note: Customers from Sendbird Chat platform signifies users who are already authenticated with the Chat SDK. If you’re implementing Chat SDK and Desk SDK at the same time, connect a user to Sendbird server with their user ID and access token first.

    Step 3: Create a ticket

    Implement the Ticket.create() method to create a new ticket either before or after the customer’s initial message.

    Ticket.create(TICKET_TITLE, USER_NAME, (ticket, error) => {
        // The ticket.channel property indicates the group channel object within the ticket.
    });

    Once a ticket is successfully created on the Sendbird server, you can access the ticket and its channel in the ticket.getChannel() through the callback from the server.

    Before a customer sends the first message, agents can’t see the ticket in the dashboard and ticket assignment does not occur. When conversation starts, the ticket is assigned to an available agent by the Desk Dashboard while messages are sent and received through the Chat SDK.

    You can use the following parameters when creating a ticket.

    Note: Only Groupkey and customFields need to be defined and are only accessible from the Dashboard.

    Argument Type Description
    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_FILEDS nested object Specifies additional information of the ticket that consists of key-value custom items. Only custom fields already registered in Settings > Ticket fields in 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 3 related channels can be added.

    Implementation guide

    This section details the procedure to handle and close a ticket from your client app.

    Add custom information to a ticket

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

    const customFields = {  
        'Product type': 'Desk',
        'line': '3'
    }; 
    
    ticket.setCustomFields(customFields, (ticket, error) => {
        if (error) throw error;
        // The 'customFields' property of a ticket has been updated.
    });

    Note: Only custom fields 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.

    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.
            }
        }
    );

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

    Add related channels

    Related channels indicate group channels in Sendbird Chat platform that are related to a ticket. When creating a ticket, pass the channel_urls of the related group channels as an argument to the relatedChannelUrls parameter in the Ticket.create() method. To update the 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.

    Ticket.create(TICKET_TITLE, USER_NAME, GROUP_KEY, CUSTOM_FIELDS, PRIORITY, RELATED_CHANNEL_URLS, (ticket, error) => {
    });
    
    ticket.setRelatedChannelUrls(RELATED_CHANNEL_URLS, (ticket, error) => {
        // The ticket's 'relatedChannels' property has been updated.
    });

    Note: Up to 3 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.

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

    {
        "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 2 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 Desk > Settings > Triggers, and system messages in Desk > Settings > System messages in 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.

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

    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 or ask customers to close a ticket, which will depend on the agent permission settings. The confirmation request message can have 3 types of states as below.

    State Description
    WAITING Set when an agent sends a confirmation request message.
    CONFIRMED Set when a customer agrees to close the ticket. (Default: true)
    DECLINED Set when a customer declines to close the ticket. (Default: false)

    When agents send confirmation request messages, the state is set to WAITING. The customer can reply Yes or No by calling Ticket.confirmEndofChat(), and the state will change to CONFIRMED or DECLINED according to this answer.

    Ticket.confirmEndOfChat(USER_MESSAGE, 'yes'|'no', (ticket, error) => {
        if (error) throw error;
    });

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

    channelHandler.onMessageUpdated = (channel, message) => {
        SendBirdDesk.Ticket.getByChannelUrl(channel.url, (ticket, error) => {
            if (error) throw 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:
                        // TODO: Implement your code for the UI when there is no response from the customer.
                        break;
                    case SendBirdDesk.Message.ClosureState.CONFIRMED:
                        // TODO: Implement your code for the UI when the customer confirms to close the ticket.
                        break;
                    case SendBirdDesk.Message.ClosureState.DECLINED:
                        // TODO: 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.

    {
        "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 about their satisfaction level with the support. When the Customer satisfaction rating feature is turned on in your dashboard, customers will get a message asking to give a score and leave a comment as feedback. The message can have 2 states as below.

    State Description
    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 Sendbird server by calling the ticket.submitFeedback() method. Then, the state of the confirmation request message is changed to CONFIRMED.

    ticket.submitFeedback(USER_MESSAGE, SCORE, COMMENT, (ticket, error) => {
        if (error) throw error;
    });

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

    channelHandler.onMessageUpdated = (channel, message) => {
        SendBirdDesk.Ticket.getByChannelUrl(channel.url, (ticket, error) => {
            if (error) throw 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:
                        // TODO: Implement your code for the UI when there is no response from the customer.
                        break;
                    case SendBirdDesk.Message.FeedbackState.CONFIRMED:
                        // TODO: 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.

    {
        "type": "SENDBIRD_DESK_CUSTOMER_SATISFACTION",
        "body": {
            "state": "CONFIRMED",
            "customerSatisfactionScore": 3,
            "customerSatisfactionComment": "It was really helpful :)" 
    }

    Reopen a closed ticket

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

    closedTicket.reopen((openTicket, error) => {
        if (error) throw error;
        // Implement your code to update the ticket list with the 'openTicket' object.
    });

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

    Use getAllTickets() to fetch all tickets without open/closed distinction (v1.0.21)

    Note: Only 10 tickets can be retrieved per request by message creation time in descending order.

    // getOpenedList()
    Ticket.getOpenedList(OFFSET, (openedTickets, error) => {
        if (error) throw error;
        
        const tickets = openedTickets;
        // offset += tickets.length; for the next tickets.
        // Implement your code to display the ticket list.
    });
    // getClosedList()’
    Ticket.getClosedList(OFFSET, (closedTickets, error) => {
        if (error) throw 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.

    const customFieldFilter = {'subject' : 'doggy_doggy'};
    Ticket.getOpenedList(OFFSET, customFieldFilter, (openedTickets, error) => {
        if (error) throw 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.

    Ticket.getByChannelUrl(CHANNEL_URL, (ticket, error) => {
        if (error) throw error;
    });

    Display open ticket count

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

    Ticket.getOpenCount((count, error) => {
        if (error) throw error;
        
        const numberOfOpenTickets = count;
        // Implement your code with the returned value.
    });

    Install

    npm i sendbird-desk

    Homepage

    sendbird.com

    DownloadsWeekly Downloads

    352

    Version

    1.0.22

    License

    SEE LICENSE IN LICENSE.md

    Unpacked Size

    98.8 kB

    Total Files

    6

    Last publish

    Collaborators

    • sendbird