We’re going to help you learn how to make magic with API.
Today. Right now.
Your Support Stack is probably getting taller these days. You might use a help desk, a ratings tool, a chat software, a project management tool, team chat apps and a CRM. Plus, you might support your own platform or service. How many tabs do you have open right now?
Getting all of these tools to play nicely together can be a challenge.
Well, we have a secret for you. Actually, it’s not really a secret, but it’s definitely a tool that customer support teams should be taking more advantage of. This tool is APIs.
Using APIs can help you integrate your tools into neat and tidy automated workflows, and troubleshoot support issues.
Don’t worry if you’re “not a programmer.” No one is born coding. While it takes a little practice and explanation to understand APIs, it’s totally worth it. In this post, we’ll help you understand what an API is, the basic parts of an API request and we’ll even walk through a sample of creating a rating in Nicereply using the updated Nicereply API. Ultimately, you’ll have a good understanding of how you can continue to play with APIs to improve your skills.
Stick with me. You’ve got this!
What are APIs?
API stands for Application Programming Interface. It allows two computer programs talk to each other. APIs can connect almost every tool you use. Want to display ticket information in Slack? APIs can help you do that. Want to integrate a rating system into your own app? APIs are here for you. Pushing meetings into a common Google Calendar? Yep, you guessed it, you can do it through APIs.
APIs communicate through a specific protocol called HTTP (hyper text transfer protocol). The client (user) sends a HTTP request to the server (where the program runs). If everything follows protocol, the server understands the request, performs the action, and returns a response to the client.
How APIs work
In order to start putting APIs to work for you, you’ll need to know a little about how they function. This article is by no means exhaustive, so make sure you check out the links at the bottom to continue learning about APIs.
Note: We’re talking about a specific type of API called REST throughout this post. You don’t need to know anything more about that, other than there are different types of APIs. REST API is the most common and what you’ll most likely find when connecting up support tools.
The method is basically an instruction for a program to do something. What that something is depends on the type of request you make. They’re basically like the verb (action word) of an API call sentence. There’s four basic methods you should know about:
POST – adds information.
Eg: use POST to create a new case in Zendesk.
PUT – edits information.
Eg: use PUT to update a rating in Nicereply.
GET – retrieves information.
Eg: use GET to retrieve a user’s profile from your CRM.
DELETE – deletes information.
Eg: use DELETE to remove a rating in Nicereply.
Parameters are the actual data you want to give or request from the program. For example, if you want to POST a rating to a ticket, you’ll provide the ticket ID, the rating and any other information you need to save.
What information an specific program accepts through their API will be outlined in their API documentation. For example, take this Nicereply API request for a histogram of all ratings:
We’re using a GET request to retrieve information. The information we need to provide along with our request (aka the parameters) are the API key from the account, the agent’s identification, and the start and end date for the data range. If you don’t specify a date range, we return everything.
If you’re using a PUT or POST, the parameters will include the information you want to add through the API.
It would be pretty bad if we could all use APIs willy-nilly to update information we don’t normally have access to. Fortunately, APIs aren’t a secret back door. You still need the key to get in. If you’re sending an API call, you’ll need to authenticate your request.
There’s a few different methods of authentication, including a simple username/password combination, using an API key or a more complicated OAuth system. You can find what your API requires in the documentation.
HTTP status codes
When you send an API request, the server will return a response. This will either provide the information you asked for, or simply tell you that your request was successful. Because HTTP is a universal protocol, every API uses the same response codes. You’ll also see these response codes pop up in other web development areas – like when you Inspect a page in Google.
Here’s a few common ones you might see. You can also check Wikipedia for a full list of all HTTP status codes.
|Response Code||What it means|
|200 OK||Everything went as planned, and the action was completed. If you’re asking for information, you’ll see it below the response code.|
|400 Bad Request||Something ambiguous was wrong with the client’s request, and the action was not completed.|
|401 Unauthorized||Either you haven’t authenticated, or the user you’ve logged in as doesn’t have permission to do what you’re trying to do.|
|429 Too Many Requests||To prevent programs from overloading the server, most APIs will have “rate limits” – a set number of requests they will accept in a time period. If you send too many requests too quickly, the API will not process them.|
|500 Internal Server Error||Something is wrong on the server side – either it’s experiencing down time, delayed responses, or is just… broken.|
Putting it all together
So how do all these pieces fit together? Let’s look at a sample API request and response from Nicereply.
Say we want to retrieve the stats for one of the agents in your company, with the username ‘john doe’. We’d type the following request into our environment:
Notice the request is “getAllUserStats” and the parameters (apikey and username) follow the request. In response, you’d get something like this:
This format of data is JSON, and is pretty standard for REST APIs because it’s simple to read and work with. For example, you can see the full name of the user is John Doe, and he’s received 3 ratings.
Testing API calls
When you’re first starting to work with APIs, you’ll spend a lot of time testing. The best way to practice is using Postman, an API development environment that makes it easy to send requests and see the responses from your favorite APIs. It’s also a great way to troubleshoot issues that might not be easily visible from within your product.
Let’s try one together. First, download Postman and let’s post a rating to your Nicereply account. (Full disclosure: I still have trouble with APIs myself, and had to ask a friend for help a couple times through this. Don’t be afraid to play around and ask questions!)
Got Postman up? Great. Let’s get our authentication set up, so that Nicereply knows we’re authorized to post to the account. Nicereply uses Basic Authentication. On a blank Postman tab, choose “Basic Auth.” You’ll be asked for a username and password.
Nicereply just requires your private API key. Leave the username field blank, or add a space if Postman needs something in the field. You can find your Nicereply private API key in your account under Settings > API.
Let’s look at the Nicereply API docs to see what else is required to post a rating. We just need the survey ID, the score and the user. Other parameters can be set if you want! For example, you can add a comment or a ticket number.
We already know the score (10/10!) and the user (found under personal settings), so we just need to find the survey id we want to post to. Each survey has it’s own unique identification number. You can have multiple surveys in your Nicereply account – one for sales and one for support. Or maybe one for each different product. Using the number identification makes sure the rating goes to the right place.
To retrieve a list of possible surveys we can post to, we’re going to use a GET call.
Enter this URL in the top field of Postman and click the Send button.
Scroll down to see the response, and the id of the survey we want to add a rating to.
Now, we can actually create the rating, using the following API call. The Nicereply API currently only accepts JSON, so you can structure the “Body” of the call like this:
I got a bunch of errors the first time I tried to send it, because my syntax wasn’t quite right. A few edits later, and I received a 201 Response! Rating created!
Recipe ideas for Nicereply’s API
Now that you’ve made an API call, let’s start thinking about what you can do with it. You can either build something from scratch using the API of tools you already use, or use something like Zapier that helps create integrations from APIs with little or no coding. Here’s some great ideas for how you can use Nicereply’s API to build more customized rating experiences for your customers and your support team.
Build a new feedback page
Need a new way to collect ratings from your customers? You can use the API to submit ratings from anywhere.
POST the new rating, along with any parameters to your Nicereply account.
Proud of your CSAT score? You should be! Keep your customers up to date on your current average rating by displaying it in your Help Center, or on your front page.
GET your monthly average rating, along with the five most recent comments.
Automate a rating workflow
If a bad rating comes in, you may want to notify your team so they can follow up. Zapier uses the Nicereply API to automate notifications. You can connect it to Slack or email or any service you use to automatically see when customers are upset and act quickly.
The world’s your API-oyster
Alright. That’s about all I have for you now, young Padawan. From here on out, it’s mostly just trial and error, plus reasoning with the internet gods, along with hair pulling, crying and finally victorious fist pumping when it finally works.
I’m just kidding – it’s not really that bad. Have fun experimenting with your favorite API and see what you can create. Zapier’s Introduction to API e-book can help when you get stuck. I’d also recommend Lyzi Diamond’s great resources on how the Internet works. Plus, don’t be afraid to Google when you need to, or ask someone with more experience.
Most importantly: READ THE DOCUMENTATION. The more time you spend working with APIs, the easier it gets. You’ll be stirring up customer support magic with APIs faster than you know!