DEV Community: Keith Crosslin

Syncing Sales Chat Transcripts in Real-Time with Zendesk Sell CRM and Stream Chat

Keith Crosslin — Wed, 12 Aug 2020 11:07:40 +0000

Can you imagine viewing your sales chat transcripts in real time from your sales CRM? Would your chat applications improve with more timely handling of customer chat inquiries? This post demonstrates how to leverage the powerful Stream Chat API to take action with a chat transcript as the chat takes place, response by response. The techniques provided here will help you better understand key components of the Stream Chat API, so that you can leverage them for similar applications, either with Zendesk Sell or other CRMs.

We show this through the use case of updating a Zendesk Sell Lead in real-time with the transcript messages of a Customer.

The simplified process of this post simulates a customer starting a sales chat. The customer chat components pass the chat message to a backend API, which is the focus of this post. The backend calls the Zendesk Sell API to update the desired Lead Description. You will see that the Zendesk lead description is updated after the customer sends a message. The flow is illustrated below.

Note: we only focus on the Customer experience in this post. Similar steps can be taken to sync the admin messages.

Technical Overview

The applications described in this post are composed of:

frontend which runs on http://localhost:3000/. This application supports the customer experience.
backend which runs on http://localhost:8080/. This application will facilitate communication with Stream and Zendesk.

The frontend is bootstrapped using create-react-app, and the backend server is an Express app running on nodejs. Both the frontend and backend leverage Stream's JavaScript library. The backend employs axios to interact with the Zendesk Sell API. All the code required for this tutorial is available in the GitHub repository.

Prerequisites

To follow along with the post, you will need a free Stream account, and a Zendesk Sell account (a Zendesk Trial can be obtained here).

The code in this post is intended to run locally and assumes a basic knowledge of React and React Hooks, Express, Node.js, and axios. The basic steps to configure Zendesk and use the API are explained in the post (see the Zendesk Sell API documentation to learn more). Please note, however, that you will need to create at least one Lead manually in Zendesk and use the Lead ID when logging in, as described below. Automatic Lead creation is possible, but is extracurricular to this post. If you want to see how to generate these leads programmatically when entering starting a Stream chat, see this post.

Configuration

This application requires three environment variables to be configured:

STREAM_API_KEY
STREAM_API_SECRET
ZENDESK_CRM_TOKEN

You will find a file in the backend folder, .env.example, that you can rename to create a .env file.

When the .env file has been created and configured, you can start the backend by npm start command from the backend folder.

Before we do anything we start anything we need to create and configure our accounts.

Let's get started!

Registering and Configuring Zendesk

To integrate Stream with the Zendesk Sell API, you must configure the OAuth security settings in Zendesk Sell with the following steps:

Click on the Settings gear to the right of the top menu

Click on OAuth under the Integrations menu

Click on + Add Access Token

Complete description and leave settings unchanged (more restrictive settings may be required for your application) and click Save

Copy the access token, which you will need to configure your backend communication with Zendesk.

Update you're .env file with the token you just generated.

Registering and Configuring Stream

Now we can configure Stream. To get the Stream credentials, navigate to your Stream.io Dashboard

Then click on "Create App"

Give your app a name and select "Development" and click "Submit"

Stream will generate a key and secret for your app. Copy these and update the corresponding environment variables in the .env file.

Step 1 - Starting a Chat

First, let's build a React frontend that allows you to start a chat as a Customer. Here's what our simplified logins screen looks like.

Let's start by modifying the App.js file that was generated by create-react-app:

// frontend/src/App.js:5
function App() {
  const [username, setUsername] = useState('');
  const [leadId, setLeadId] = useState('');
  const [channel, setChannel] = useState(null);
  const [chatClient, setChatClient] = useState(null);

  const startChat = async () => {
    // ...
  }

  if (channel && chatClient) {
    return <SalesChat username={username} leadId={leadId} channel={channel} chatClient={chatClient}/>;
  } else {
    return <div className="login">
      <div className="login-description">
        Type in a username and start a chat to simulate a Customer's sales chat experience. Be sure to grab a Lead ID from Zendesk Sell.
      </div>
      <label>Customer Username</label>
      <input
        type="text"
        value={username}
        onChange={(e) => setUsername(e.target.value)}
        required
      />
      <label>Zendesk Lead ID</label>
      <input
        type="text"
        value={leadId}
        onChange={(e) => setLeadId(e.target.value)}
        required
      />
      <button onClick={startChat}>Start Sales Chat</button>
    </div>
  }
}

We first present the user with the form (displayed above). This form contains a username, a leadId (to identify the Zendesk Sell lead record), and a button to start the chat. We use useState to keep track of the values of each of these fields.

To keep this post focused, we won't generate leads dynamically. This means we'll need to input the lead id from Zendesk manually. To grab our lead id, go to your Zendesk dashboard and navigate to the "Leads" section. If you don't have a lead, click on "Add" and then "Add Lead". Fill in the necessary information then click "Save". Once you've done that you should see a lead id in the URL. It will be a 6-8 digit number such as 3180101.

Once you've filled out your username and leadId, after you can click "Start Sales Chat". Upon clicking this, we fire our startChat function:

const startChat = async () => {
  const response = await axios.post("http://localhost:8080/stream-chat-credentials", {
    username, leadId
  });
  const token = response.data.token;
  const channelId = response.data.channelId;
  const chatClient = new StreamChat(response.data.apiKey);

  await chatClient.setUser({ id: response.data.userId, name: response.data.userName }, token);
  const channel = chatClient.channel("messaging", channelId);

  setChatClient(chatClient);
  setChannel(channel);
}

Here we post our username and leadId to our backend. We'll look at what our backend does in a second, but first, let's see how our frontend handles the response. Our backend will return a few pieces of data required to configure our frontend client. Using the apiKey we set up our frontend StreamChat instance. We then configure the chat instance with the userId, userName, and the Stream frontend token. Once our client is configured, we can create a reference to our channel via the channelId. We then set the React component's chatClient and channel state.

Before we move on to rendering the chat channel, let's look at the backend /stream-chat-credentials handler:

// backend/server.js:15
const streamClient = new StreamChat(
  process.env.STREAM_API_KEY,
  process.env.STREAM_API_SECRET
);

// ...

// backend/server.js:57
app.post("/stream-chat-credentials", async (req, res) => {
  const { username } = req.body;
  try {
    let user = { id: username, name: username, role: 'user' };

    await streamClient.upsertUsers([user]);
    const channel = streamClient.channel('messaging', username, {
      name: 'Sales Chat',
      created_by_id: 'sales-admin'
    });

    await channel.create();
    await channel.addMembers([username]);

    const token = streamClient.createToken(user.id);

    res.send({
      userId: user.id,
      userName: user.name,
      channelId: channel.id,
      token,
      apiKey: process.env.STREAM_API_KEY
    });
  } catch (err) {
    console.log(err);
  }
});

Here we take the username from the request. We use our streamClient to create or update the user. Then we create a chat channel that is private to that user (and any admin user). Once the chat channel is set up, we generate the user's frontend token and respond to the user with the necessary data.

Step 2: Displaying a Stream Chat Channel

Once you've started a chat you will see a screen that looks like this:

As you can see in Step 1, we have the data we need to mount the SalesChat component. This component takes the user information (username and leadId) and our Stream data (chatClient and channel). The process flow of this component is to render the chat experience, hook into the message lifecycle, send each message to our backend, then update the Lead in Zendesk Sell. Here's the entire component:

// frontend/src/SalesChat.js:7
function SalesChat({ username, leadId, chatClient, channel }) {
  async function handleMessage(_channelId, message) {
    await axios.post("http://localhost:8080/messages", { message, author: username, leadId: leadId });
    return channel.sendMessage(message);
  }

  return (
    <Chat client={chatClient} theme="commerce light">
      <Channel channel={channel} doSendMessageRequest={handleMessage}>
        <Window>
          <h1>
            Customer Support Chat: {channel.id}
          </h1>
          <MessageList/>
          <MessageInput focus/>
        </Window>
      </Channel>
    </Chat>
  );
}

Using the chatClient and channel we render the chat experience with Stream's Chat Messaging UI Kit. The component hooks into the message lifecycle by configuring the Channel component's doSendMessageRequest prop. This prop allows us to intercept the message before it goes to Stream's API. Inside of handleMessage we send the message, along with the author and leadId to our backend's /messages endpoint. Once the message has been handled by our backend, we send the message to the channel by calling sendMessage.

Step 3: Syncing the Chat Transcript on Every Message

Now that we have our chat experience mounted and are sending every message to our backend, we can sync these messages to our Zendesk Lead. Here's our /messages endpoint:

// backend/server.js:33
app.post('/messages', async (req, res) => {
  try {
    const leadId = req.body.leadId;
    let previousTranscript = await getPreviousTranscript(leadId);
    const payload = {
      'description': `${previousTranscript}\n${req.body.author}: ${req.body.message.text}`
    }
    const headers = {
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.ZENDESK_CRM_TOKEN}`
    }
    await axios.put(
      'https://api.getbase.com/v2/leads/' + leadId,
      { data: payload },
      { headers: headers }
    );
    res.send({});
  } catch (err) {
    console.log(err);
    res.status(500);
  }
});

This endpoint appends the new message and author to the description field. Every time we update the description field, it will overwrite the previous data. Therefore, we need to look up the previous transcript via getPreviousTranscript, and append the new message to it:

// backend/server.js:20
async function getPreviousTranscript(leadId) {
  const headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.ZENDESK_CRM_TOKEN}`
  }
  const response = await axios.get(
    `https://api.getbase.com/v2/leads/${leadId}`,
    { headers: headers }
  );
  return response.data.data.description || '';
}

This is simply a GET against the lead to get the previous description field out. Once we have the previous description we issue a PUT to update the lead with the new description field containing our appended message.

That does it! You now understand how to integrate Stream Chat with Zendesk Sell to update Lead Descriptions (or any other Zendesk field as needed) during your sales chat experience.

Originally published at https://getstream.io

How To Capture Leads From Live Chat In Zendesk

Keith Crosslin — Wed, 12 Aug 2020 09:41:40 +0000

This post will demonstrate how to configure a Lead creation in Zendesk from a customer inquiry via a landing page/sales chat widget. We'll build a full-screen experience that can be embedded on your homepage or landing pages. Our chat experience will start with a simple user registration to capture first name, last name, and email before moving them into a one-on-one private chat with a sales representative. Please note, the sales representative experience is out of scope for this post.

Application Process Flow

The user initiates an inquiry chat
User provides basic information via a form
The frontend passes the information to the backend, which sends a request to Zendesk to create the Lead and gets a secure frontend token from Stream
The frontend displays the chat screen.

Overview

The application described in this post is composed of a React frontend and an Express backend. The backend also leverages Stream's JavaScript library to generate a frontend token, and Axios to send data to Zendesk via the Zendesk Sell API. All the code required for this tutorial is available in github.

First, we need to register and configure our accounts:

Registering and Configuring Zendesk
Registering and Configuring Stream

Once we have our accounts we'll walk through the code step by step:

Step 1: User Enters Details
Step 2: Backend Creates CRM Lead and Authenticates User to Chat
Step 3: Frontend Registers and Configures Chat
Step 4: User Enters Chat Room

Prerequisites

To follow along with the post, you will need a free Stream account and a Zendesk Sell account. For this post, we used a Trial version of Zendesk Sell.

This post requires basic knowledge of React Hooks, Express, Node.js, and Axios. The code is intended to run locally. A basic understanding of Zendesk Sell API is also needed to configure the secure communication between the app and Zendesk (the specific steps needed are provided in the post).

There are three references that you need to provide in a .env file to make this application function:

STREAM_API_KEY
STREAM_API_SECRET
ZENDESK_CRM_TOKEN

We're using dotenv to configure our environment. A template file named .env.example is provided. Just update the values shown with your unique keys, secrets, and tokens, then remove the .example from the file name. We'll go over how to acquire these values next.

To integrate with Zendesk Sell we need to first configure the OAuth security settings from your Zendesk Sell Settings Panel using the following steps. Please note: if your dashboard looks different from the images shown below, you might be in the Zendesk Dashboard, not the Zendesk Sell Dashboard. They are separate products so make sure you're in the right place!

Registering and Configuring Zendesk

First, go to Settings

Click on "OAuth" under the "Integrations" menu item

Click on the button labeled, "+ Add Access Token"

Complete description and leave settings unchanged (more restrictive settings may be required for your application) and click "Save"

Copy the access token, which you will need to configure your backend communication with Zendesk.

You will update the backend with this Zendesk OAuth Token as explained in the next section.

Registering and Configuring Stream

To get the Stream API Key and API Secret, navigate to your Stream.io Dashboard.

Once you're there, click on "Create App", and complete the form like in the following screenshot.

Give your app a name, select "Development" and click "Submit".

Stream will generate a Key and Secret for your app. You need to copy these into your .env file.

When the .env file has been created, you can start the backend by npm start command from the backend folder.

Step 1: User Enters Details

First, we'll create the sales lead generation form the user sees when first landing on your site. This is a simple React form that shows if they haven't started a chat yet. Here's what our form looks like.

This snippet shows how the form is created (the chat app code is ignored for now, as indicated with // ...).

// frontend/src/App.js:7
function App() {
    const [firstName, setFirstName] = useState('');
    const [lastName, setLastName] = useState('');
    const [email, setEmail] = useState('');

    // We'll get to these in a bit
    const [chatClient, setChatClient] = useState(null); 
    const [channel, setChannel] = useState(null);

    async function register() {
        // ...
    }


    if (chatClient && channel) {
       // ...
    } else {
        return (https://getstream.io/blog/how-to-capture-leads-from-live-chat-in-zendesk/
            <div className="app">
                <div className="app-input">
                    <label htmlFor="firstName">First Name</label>
                    <input type="text" name="firstName"
                        value={firstName}
                        onChange={(e) => setFirstName(e.target.value)}
                    />
                </div>
                <div className="app-input">
                    <label htmlFor="lastName">Last Name</label>
                    <input type="text" name="lastName"
                        value={lastName}
                        onChange={(e) => setLastName(e.target.value)}
                    />
                </div>
                <div className="app-input">
                    <label htmlFor="email">Email</label>
                    <input type="text" name="email"
                        value={email}
                        onChange={(e) => setEmail(e.target.value)}
                    />
                </div>
                <button onClick={() => register()}>Start Chat</button>
            </div>
        );
    }
}

Here we have a simple React form that binds three values, first name, last name, and email. We use React Hook's useState to store these values. When a user clicks on "Start Chat" we call our register function. We'll see this function in Step 3.

Step 2: Backend Creates CRM Lead and Authenticates User to Chat

Before we look at our frontend register function, let's build the backend that supports it.

** Note: For this post, we will send the minimum level of information to create a CRM Lead, your requirements may differ, and can easily be added using the Zendesk API documentation. **

In the next code snippet, we use express to create a single endpoint, /registrations, that performs the following steps:

Generate our Lead in Zendesk Sell CRM
Register the user in Stream
Generate a Stream chat channel
Generate a Stream frontend token.

// backend/routes/index.js:6
router.post('/registrations', async (req, res, next) => {
    try {
        await axios.post(
            'https://api.getbase.com/v2/leads',
            {
                data: {
                    'first_name': `${req.body.firstName}`,
                    'last_name': `${req.body.lastName}`,
                    'description': 'Lead created through Chat Inquiry',
                    'email': `${req.body.email}`
                }
            },
            {
                headers: {
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Authorization': `Bearer ${process.env.ZENDESK_CRM_TOKEN}`
                }
            }
        );
        const client = new streamChat.StreamChat(
            process.env.STREAM_API_KEY,
            process.env.STREAM_API_SECRET
        );
        const user = {
            id: `${req.body.firstName}-${req.body.lastName}`.toLowerCase(),
            role: 'user',
            image: `https://robohash.org/${req.body.email}`
        };
        await client.upsertUsers([user, { id: 'sales-admin', role: 'admin' }]);
        const channel = client.channel('messaging', user.id, {
            members: [user.id, 'sales-admin'],
        });
        const token = client.createToken(user.id);
        res.status(200).json({
            userId: user.id,
            token,
            channelId: channel.id,
            apiKey: process.env.STREAM_API_KEY
        });
    } catch (error) {
        console.log(error, data.errors);
        res.status(500).json({
            error: error.message
        });
    }
});

First, we use axios to do an HTTP Post to the Zendesk Sell API (api.getbase.com). We pass along the first name, last name, and email. We grab our Zendesk OAuth token from the environment. That's all we need to do to get our lead created.

Once our App is registered as a StreamChat Client, we'll create a specific Chat Channel which our Customer and Support Agent will connect to. Stream allows for public chats, but to make our Channel private, we'll specify 'members' of that channel using unique id's, and register them with our Client Instance.

To generate the customer's id, we'll modify the Customer's frontend input (Stream ids must be lowercase with no whitespace), and create a 'user' object to identify them. You can specify unique roles with different capabilities; our Customer will be granted a generic 'user' role, with limited abilities. We'll throw on the optional 'image' key to give the Customer a random avatar.

Normally, you could create another object for the Support Agent on the other end of the chat, but for this case, we will lazily register a Support Agent inline.

The upsertUsers method registers (or updates) users. Our Customer ('user') and our Support Agent ('sales-admin') are registered so they can join the chat channel.

Next, we create the Chat Instance with the channel method, passing a chat type (messaging type'), a channel id (in this case user.id), and the members allowed to join. Then we use StreamChat client's 'createToken()' method to create a token for our Customer. All that's left is to respond to our frontend with the required information to join.

Step 3: Frontend Registers and Configures Chat

Now that we have our /registrations endpoint, let's go back to our frontend and look at our register function.

// frontend/src/App.js:15
async function register() {
    const response = await fetch("http://localhost:8080/registrations", {
        method: "POST",
        headers: {
            'Accept': 'application/json',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            firstName,
            lastName,
            email
        })
    })
    const { userId, token, channelId, apiKey } = await response.json();
    const chatClient = new StreamChat(apiKey);
    await chatClient.setUser(
        {
            id: userId,
            name: email,
            image: `https://getstream.io/random_svg/?id=${userId}`
        },
        token,
    );


    const channel = chatClient.channel('messaging', channelId);
    setChatClient(chatClient);
    setChannel(channel)
}

Our register function first performs an HTTP Post to our backend with the fields bound in the form. The backend responds with userId, token, channelId, and apiKey which are what we need to configure the chat client and user in the frontend. To load StreamChat to our React frontend we initialize a StreamChat instance, then set our Customer User via setUser. This call authenticates the client to communicate with the Stream Chat API on behalf of that user. We then retrieve the appropriate channel via chatClient.channel and set our component's state.

Step 4: User Enters Chat Room

Now that we have our chat client and channel, we can enter the chat room. Let's look at the other half of our render's if statement.

// frontend/src/App.js:45
if (chatClient && channel) {
    return (
        <div className="App">
            <Chat client={chatClient} theme={'messaging light'}>
                <Channel channel={channel}>
                    <Window>
                        <ChannelHeader />
                        <MessageList />
                        <MessageInput />
                    </Window>
                    <Thread />
                </Channel>
            </Chat>
        </div>
    )
} else {
  // ...
}

Since Stream Chat's React library provides us out of the box components, we simply configure their Chat and Channel components and embed the parts of the chat we want to see. This renders a great out of the box chat experience.

Ready to add the polish? Check out Stream's free, gorgeous UI Kit.

And that does it! You now understand how to integrate Stream Chat with Zendesk Sell to create Leads during your sales chat experience. Similar integrations can be configured with other Zendesk Objects like Contacts, Deals, Calendar, and Tasks.

Originally published at https://getstream.io