REST API Instructions | Yext Hitchhikers Platform

What You’ll Learn

By the end of this unit, you will be able to:

• Define what a REST API instruction is and when to use it
• Explain the difference between the GET and POST method
• List the required properties to create a REST API instruction

Overview

A REST API instruction can be used to read or write data from a REST API, often using data collected from previous instructions (though not always).

The REST API instruction will most commonly be used to get data from an external data source to help users find information or to answer their questions. It is similar to the search instruction step in this way; the only difference is that the data isn’t coming from Yext Search and Content.

The REST API instruction also enables Chat to integrate with other third-party systems to accomplish tasks such as appointment scheduling, placing orders, or collecting leads. In this case, once you gather information from a user, the REST API can then help you store that data elsewhere for your company to utilize for other projects.

Setting up a REST API Instruction

When you choose the REST API action for an instruction, you need to fill out the following:

• Instruction: A description of what you want the bot to do.
• Method: Choose from GET or POST method. GET if you want to retrieve data and POST if you want to create/send data.
• URL: the URL of the API.

There are other additional properties you can use to setup your REST API instruction, but there are optional depending on what you want to achieve:

• Authentication Method: API Key, Bearer Token, Basic Authentication
• Additional Headers: HTTP headers for the request.
• Query Parameters: Appended to the URL as key-value pairs.
• Results Path: A JMESPath query expression used to simplify large results for AI prompt organization.
• Request Body Format (POST method only): JSON object to be sent as the request body.

GET Method

The GET method is used when retrieving data from a source. For example, you may want Chat to summarize the details of a Zendesk ticket conversation.

We will create a goal called “Summarize Ticket” for this scenario with a collect instruction, REST API instruction, and a reply instruction.

The collect instruction is used to identify the ticket or ticket number the user wants the bot to summarize. It will collect the ticket number for the field ID ticketNumber which can then be referenced in the next instruction.

The REST API instruction will then use that ticket information to retrieve the ticket details via an API. The REST API instruction inputs may look something like this:

• Instruction: “Call the Zendesk ticket API to return the ticket conversation history.”
• Method: GET
• URL: https://tags.zendesk.com/api/v2/tickets/comments.json
• Query Parameters:
  • Key: ticket, Value: [[collectedData.ticketNumber]]

A direct answer reply instruction can then use the conversation details from the REST API instruction to summarize it back to the user. The instruction can be something like “Summarize the conversation. Be concise. The conversation takes place in the body field within each comment object of the array. Confirm if the question was resolved.”

POST Method

The POST method is used to create or send data to a source. Similar to the previous example, you could utilize your bot to allow users to create a Zendesk ticket.

We will create a goal called “Create a Ticket” for this scenario with a collect instruction, REST API instruction, and a reply instruction.

The collect instruction is used to gather information to be submitted along with the ticket request. It will collect fields such as subject and description to be referenced in the Request Body Format section of the REST API instruction.

The REST API will then use that information to create a new ticket details an API call. The REST API instruction inputs may look something like this:

• Instruction: “Call the Zendesk ticket API to return the ticket conversation history.”
• Method: POST
• URL: https://tags.zendesk.com/api/v2/tickets/
• Authentication method: Fill in your authentication information for your Zendesk account

• Request Body Format:

  {
  "ticket": {
    "comment": {
      "body": "[[collectedData.description]]"
    },
    "priority": "urgent",
    "subject": "[[collectedData.subjects]]"
  }
  }