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 the Knowledge Graph.

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]]"
}
}

JSON Configuration

A REST API step can be used to read or write data from a REST API, often using data collected from previous steps (though not always). A REST API step requires the following configuration:

• method - the HTTP verb, either GET, POST, PUT, PATCH or DELETE.
• url - the URL of the API.
• headers - (optional) HTTP headers for the request.
• body - (optional) JSON body for a POST request.

Using Collected Data

It’s very common to use data collected from previous steps in the URL, headers, or body of a REST API request. For example, you might want to collect the user’s city of residence and then send an API request looking up the weather in that city.

You can do this by referencing collected in either the URL, params, or body of the request like so: [[ collectedData.theFieldId ]]

Here’s an example that combines a collect, a restApi, and a reply step:

{
  "goal": "Get the weather in a city.",
  "examples": [
    "How's the weather like",
    "What's the weather in Brooklyn right now?",
    "What's the weather in NY?",
    "How's the weather in San Francisco?",
    "What's the weather in Los Angeles?",
    "What's the weather in San Diego?"
],
  "instructions": [
    {
      "collect": {
        "instruction": "Ask the user what city they're interested in",
        "fields": [
          {
            "fieldType": "STRING",
            "id": "city",
            "optional": false
          }
        ]
      }
    },
    {
      "restApi": {
        "method": "GET",
        "url": "http://api.openweathermap.org/geo/1.0/direct",
        "params": {
          "q": "[[ collectedData.city ]]",
          "appId": "<YOUR_API_KEY>"
        }
      }
    },
    {
      "reply": {
        "instruction": "Based on the response, tell them the weather in that city. You must ALWAYS respond in Fahrenheit. You may convert the temperature from Kelvin/Celsius to Fahrenheit if needed.",
        "mode": "DIRECT_ANSWER"
      }
    }
  ]
}

In this example, we look up the weather in a given city by first collecting the name of the city as the city field, then we send it to the OpenWeather API  by referencing the collected data via the syntax [[ collectedData.theFieldId ]].