Requesting CSAT Feedback

CSAT, or Customer SATisfaction, is a numerical score used to keep track of how customers are feeling after interacting with your company. By gathering this data, it's easy to track metrics like agent performance and overall customer sentiment.

With Gladly's webhooks and APIs, it's easier than ever to integrate with the CSAT Survey provider you already use. Use this integration to trigger the CSAT survey when an agent closes a conversation in Gladly, gather feedback from the customer, and then post that data directly to the customer's timeline which helps to keep all relevant information in the same place.

Follow this simple guide to get started.

Send CSAT Survey

Step 1: Create a webhook for closed conversations in Gladly

Agents close conversations when all of the interaction with the customer is done. By creating a webhook that triggers on the CONVERSATION/CLOSED event, we can start the process of sending a CSAT Survey to the customer so that they can tell you how their experience was.

To create a webhook in Gladly, you can either use the Webhooks Admin UI in the app, or use the REST API if you wish to do so programmatically.

Use the following fields when creating your webhook:

Name: The name of your webhook. Be descriptive about what it does.

Webhook URL: Where you want the webhook to send data.

Events: Choose CONVERSATION/CLOSED event from the drop-down list.

Basic Auth: Use basic authentication on your endpoint or header-based authentication.

Using the Webhooks Admin UI

Using the REST API

For more information on using the REST API––request body schema, response object, error states––you can view the docs.

POST /api/v1/webhooks
{
  "name": "CSAT integration",
  "url": "https://gateway.organization.com/gladly/webhook",
  "events": [
    "CONVERSATION/CLOSED"
  ],
  "credentials": {
    "username": "integrations@organization.com",
    "password": "fxdUfTcejVxVs9bQ8DizKccq"
  },
  "headers": {
    "X-Gladly-Token": "123"
  }
}

Step 2: Receive webhook from Gladly on a closed conversation event

Once your webhook is set up, your endpoint will receive the following data every time an agent closes a conversation. Make sure you keep the conversationId and customerId, they're important for the next step!

POST https://gateway.organization.com/gladly/webhook
{
    "id": "ahDTUqU1QqKTetQ0AfvDWQ",
    "event": "CONVERSATION/CLOSE",
    "timestamp": "2019-08-28T04:30:14.846Z",
    "content": {
        "conversationId": "qt_Nnro9TzqBpmXbdBedSg",
        "customerId": "XV7Rj6RXTYS52SMwG91oog"
    }
}

Step 3: Request customer data

Now that you have the customerId and conversationId, you can use those to request further information about the customer by using the Gladly REST API. You can use the data you gather in this step to determine:

  • What data to send to your CSAT provider,
  • If you should even send a survey to the customer,
  • What agent worked on the conversation.

Each request that you can make below will have ideas for how to use the data that is provided.

Request customer profile data

Customer profile data is full of useful tidbits, like name, phone number, address, emails, and more. The most common use case for customer profile information is data to send to the CSAT Survey provider.

Use the customerId you received to get the data on that customer.

// GET customer by customer ID
GET /api/v1/customer-profiles/{customerId}

You will receive:

{
  "name": "Martha J Williams",
  "address": "563 Rigoberto Station Apt. 197",
  "emails": [
    {
      "normalized": "martha.williams@gmail.com",
      "original": "Martha.Williams@gmail.com",
      "primary": false
    }
  ],
  "phones": [
    {
      "normalized": "+17244895501",
      "extension": "123",
      "original": "7244895501",
      "regionCode": "US",
      "primary": false,
      "smsPreference": "OFF",
      "type": "OFFICE"
    }
  ],
  "externalCustomerId": "a21c1636-c622-48b7-bf6a-d9032645aa55",
  "customAttributes": {
    "membershipNumber": "RQ564555333",
    "membershipTier": "gold"
  },
  "id": "8SWY6EwlSnqgD7HC-9RS9A",
  "createdAt": "2019-02-21T07:15:18.07272933Z",
  "updatedAt": "2019-02-21T19:50:23.486566336Z"
}

Request customer conversation data

Conversation data is an array of conversation items––chat messages, emails, phone calls, agent notes, topics, etc–– from the conversation that was just closed. This data can be useful to see what the conversation was about, how long it lasted, and what form of communication was used.

It's important to note that if you wish to collect data on the agent involved or on the topic(s) applied, you will need to first make this request.

Use the conversationId you received to get the conversation data on that customer.

//GET conversation items by conversation ID
GET /api/v1/conversations/{conversationId}/items

You will receive:

[
    {
    "id": "AhBjYKomTSGYjrSWc37Avg",
    "customerId": "XV7Rj6RXTYS52SMwG91oog",
    "conversationId": "qt_Nnro9TzqBpmXbdBedSg",
    "timestamp": "2019-01-26T01:32:10.000Z",
    "initiator": {
      "id": "kXM47UICQuiASeyIoenM9g",
      "type": "CUSTOMER"
    },
    "content": {
      "type": "CHAT_MESSAGE",
      "content": "hello",
      "sessionId": "gT0sA7MnQv2nbU8QlJIT3g"
    }
  },
  {
    "id": "eBil8cpCT9KdyWeEijNLqQ",
    "customerId": "XV7Rj6RXTYS52SMwG91oog",
    "conversationId": "qt_Nnro9TzqBpmXbdBedSg",
    "timestamp": "2019-01-26T01:32:18.718Z",
    "initiator": {
      "id": "XJd0gCfDRre-bznd-9XoQg",
      "type": "AGENT"
    },
    "content": {
      "type": "CHAT_MESSAGE",
      "content": "oh hello",
      "sessionId": "gT0sA7MnQv2nbU8QlJIT3g"
    }
  },
    {
      "id": "2p1GLlgUSwKSSxxAbfFfIw",
      "customerId": "XV7Rj6RXTYS52SMwG91oog",
    "conversationId": "qt_Nnro9TzqBpmXbdBedSg",
    "timestamp": "2019-01-26T01:32:26.000Z",
    "content":{
      "type": "TOPIC_CHANGE",
      "addedTopicIds": ["MhDu8JP9RLqNLIwxqYeqNw"],
      "removedTopicIds": []
      }
  }
]

GET agent metadata

Agent metadata is useful when you want to track which agent was involved in a conversation.

To get the agentId, you need to get the id from the initiator section of a conversation item (data received from the previous request).

{
    "id": "eBil8cpCT9KdyWeEijNLqQ",
    "customerId": "XV7Rj6RXTYS52SMwG91oog",
    "conversationId": "qt_Nnro9TzqBpmXbdBedSg",
    "timestamp": "2019-01-26T01:32:18.718Z",
    "initiator": {
      "id": "XJd0gCfDRre-bznd-9XoQg",
      "type": "AGENT"
    },
    "content": {
      "type": "CHAT_MESSAGE",
      "content": "oh hello",
      "sessionId": "gT0sA7MnQv2nbU8QlJIT3g"
    }
  },

That id is then used as the agentId to request agent data from Gladly.

// GET agent
GET /api/v1/agents/{agentId}

You will receive:

{
  "id": "XJd0gCfDRre-bznd-9XoQg",
  "name": "Amy Agent",
  "emailAddress": "amy.agent@example.org"
}

GET topic data

Topic data is useful when you want to see what the conversation was about. Sometimes it can be used to determine if a CSAT survey should even be sent at all. For example, say there is a certain topic, like "Address Change" that you don't care about the survey data on. If you see that this recently closed conversation has the topic "Address Change," you can go ahead and skip the rest of the steps in this tutorial and wait for the next request from the webhook.

To get the topicId, you need to get the strings inside of the addedTopicIds array in a TOPIC_CHANGE conversation item (data received from the customer conversation data request).

{
    "id": "2p1GLlgUSwKSSxxAbfFfIw",
    "customerId": "XV7Rj6RXTYS52SMwG91oog",
    "conversationId": "qt_Nnro9TzqBpmXbdBedSg",
    "timestamp": "2019-01-26T01:32:26.000Z",
    "content": {
      "type": "TOPIC_CHANGE",
      "addedTopicIds": ["MhDu8JP9RLqNLIwxqYeqNw"],
      "removedTopicIds": []
    }
}

Every string in that array is a different topicId that you can request information about from Gladly. Please note that conversations can have multiple topics!

// GET topic
GET /api/v1/topics/{topicId}

You will receive:

{
  "id": "MhDu8JP9RLqNLIwxqYeqNw",
  "name": "Order Return",
  "disabled": false
}

Tip: How to create a permalink to the closed conversation in Gladly

If you need quick access back to the conversation in Gladly, simply take the conversationId and customerId to form a permalink.

/customer/{customerId}/conversation/{conversationId}

Step 4: Gather feedback from the customer

Once you have gathered all of the information you need, send a request to your CSAT Survey Provider with whatever information that they require. Once the feedback has been filled out by the customer and sent back to you, move on to the next step.

Step 5: Post feedback response to customer's timeline in Gladly

Now that you have the feedback from the customer, it's time to send that data back into Gladly to live with the conversation data. Keeping all data about the customer and their conversations in the same place is part of what makes Gladly so useful for everyone working in a contact center.

Create a new conversation item

This POST request will add a new conversation item containing the feedback data to the customer's conversation timeline.

id: A unique ID, 50 chars or less. If you have a survey ID that you generated, use that here. It helps to keep track of it in case you need to update the Survey item later. If you do not provide an ID, one will be generated for you.

type: CUSTOMER_ACTIVITY is always the type that should be used for a CSAT survey. This has to do with how the data gets displayed in Gladly!

title: The bold content at the top of the item that is posted.

body: The main content of the CSAT Survey.

activityType: ALWAYS use SURVEY!! That's what ensures the icon on the right-hand side of the image below shows up as a survey response, and not something else. Getting the right icons makes using Gladly easy for the agents.

sourceName: The name of the survey provider you used. For example, Delighted.

link: If you wish to link out to more details or a webpage with the full results, you can use the link section. Use url for the link and linkText for the words that are displayed on the hyperlink.

POST /api/v1/customers/{customerId}/conversation-items

{
     "id": "141d0ff03c114cefa1cfd338dbc5ff8d",
   "content": {
      "type": "CUSTOMER_ACTIVITY",
      "title": "NPS: 10",
      "body": "Julian went the extra mile, helping us.",
      "activityType": "SURVEY",
      "sourceName": "SurveyProviderName",
      "link": {
         "url": "https://www.surveyprovider.com/survey/XYZ",
         "text": "View Details"
       }
   }
}

Update Survey in Gladly

Sometimes the pieces of survey data are sent in parts. A common workflow is that the NPS score is sent first, and then a customer comment is sent later, once they fill it out. If you post these separately in Gladly, they will show up as two different survey results. This is no good because we want the survey information to be aggregated in one spot.

Our solution is for you is to try to send the survey information to Gladly each time you receive more data. If the Survey conversation item already exists in Gladly, then you just have to delete it and re-post it.

Follow these steps to update an existing survey in the Gladly timeline.

Step 1: Try to POST the survey conversation item

When you send your request, be sure to include a unique surveyId as the Gladly item's id. If Gladly responds with a HTTP 409 error, then that means that the id is already in use. If you do not receive an error code, then this is the first time that the survey has been posted and you can stop because you are done!

POST /api/v1/customers/{customerId}/conversation-items

{
     "id": "141d0ff03c114cefa1cfd338dbc5ff8d",
   "content": {
      "type": "CUSTOMER_ACTIVITY",
      "title": "NPS: 10",
      "body": "Julian went the extra mile, helping us.",
      "activityType": "SURVEY",
      "sourceName": "SurveyProviderName",
      "link": {
         "url": "https://www.surveyprovider.com/survey/XYZ",
         "text": "View Details"
       }
   }
}

Step 2: DELETE the outdated survey item

In order to post the most up-to-date information, you have to remove the old item from the feed.

customerId: The customerId you received from Gladly when the webhook triggered

itemId: The surveyId you used for the id when creating the conversation item in Step 1

DELETE api/v1/customers/{customerId}/conversation-items/{itemId}

Step 3: POST the survey conversation with all of the updated information

Send the same request as Step 1 except this time, there should be no error and your item will successfully show up in the customer's Gladly timeline.

Conclusion

Hurray for you, you've now successfully set up a CSAT Survey integration with Gladly!