Skip to main content

Make API requests using the HTTP Request block

What is the Request block?

The Request block lets your bot make calls to an API. The information you receive from the API can be saved as Variables and used in your Answers.

Ada bots support five types of HTTP requests:

  • GET - Retrieves information

  • POST - Submits information

  • PATCH - Makes partial changes to information

  • PUT - Creates new or overwrites existing information

  • DELETE - Deletes information

Note

POST, PATCH, PUT, and DELETE all require authentication to use.

Example: Below is what a complete Request block looks like.

Screen_Shot_2019-07-16_at_4.46.46_PM.png

Set up the Request block to make an API call

  1. Enter the API address in the URL field.

  2. Select your request type from the Method list.

  3. If required, use the Headers fields to pass metadata, like public access tokens and language.

    Example:

    Screen_Shot_2019-07-16_at_4.49.25_PM.png
  4. Click Test Request to send a sample API call and see the response body that comes back.

  5. Under Error Answer, select an Answer to appear as a fallback if the API call is unsuccessful.

  6. Under Save As Variable, save all or a portion of the response body in one or more variables for use in other blocks.

    • The easiest way to save a particular attribute is to click a blue tag with a “+” icon in the response body to automatically save that attribute as a variable. You can select or create a variable to save that value in, and the Data Key field automatically populates, as below.

      For more complex use cases, you may have to type in a data key yourself, so you can target a particular attribute or array in the response. For more information, see Use data keys to target a portion of an API response.

      Example:

      requestgif.Gif
    • To add an additional variable, you can either click another tag in the response body, or click the green “+” icon by the Save As Variable fields. For more information, see What is a variable?.

  7. Create your Answer content using the variables you've now saved.

Note

If there are more than five variables within the block, it will be collapsed by default the next time you view the Answer. This allows you to more easily scroll through the Answer's content. To expand the block and view all of the variables, click the arrow icon next to the trash can icon in the upper-right corner of the block.

Use data keys to target a portion of an API response

Data keys are a way to tell your bot to target a portion of the API request so you can save it as a variable. There is a variety of ways to do this, depending on your end goal. If you need any assistance, don't hesitate to contact your Ada team.

Warning

Variables are limited to 100,000 characters. Particularly when you're saving all or part of an API response as a variable, take care that you don't exceed this limit. If you do, you may start seeing errors, because your bot might not be able to correctly parse your variable content.

Data key notation

We use different types of notation to target different parts of the response:

  • Target the entire API response

    To save the entire API response in a variable, use the ada_response_string data key.

  • Target a specific attribute or array

    To target a specific attribute or array, enter its name exactly as it appears in the API.

  • Target a child array or attribute

    You can use dot or bracket notation to target either arrays or attributes nested in other arrays or attributes.

    Any of these notations would get your bot to look for an attribute called parent and save either an array or attribute within it called child:

    • parent.child

    • parent[child]

    • "parent"["child"]

      • Using quotation marks might help if the array or attribute name has a space in it. You must use double quotes, as above; if you use single quotes (e.g., 'parent'['child'], the data key won't work.

    If you're looking for something nested inside an array, you can target a particular instance based on its order in the API response. Note that this numbering starts at 0, not at 1, and that these numbers must be in brackets.

    For example, with this notation, your bot would look for the first item in the array called parent, find the array within it called child, and save the second item within the child array:

    • parent[0].child[1]

    • [parent][0][child][1]

    • ["parent"][0]["child"][1]

    Warning

    This method assumes that responses in the API will always be in the same order. Remember to test your API request with a variety of scenarios to ensure your data key correctly selects the attribute you're looking for. If you find that the order of items in your API response varies between calls, contact your Ada team to find a solution.

Frequently asked questions

Q: I sometimes get "Failed to Load Variable" emails, telling me a variable in my Request block has a bad access key and that I should remove it. What does that mean? Does that mean my Request block isn't working?

A: Not necessarily. Those emails are Ada's way of giving you a heads up that it was expecting data to be passed to that variable from your database, but nothing corresponding to that variable was received from your API.

There are a few reasons why this may happen. You may need to double check your API configuration and ensure that there is indeed information that should be passed to that variable. However, there are many cases where data doesn't need to be passed to the bot.

For example, if you're an e-commerce company and you're using the bot to track orders, you may have two variables that cover the customer's address and apartment number. But say a customer purchases something from your site and they don't live in an apartment (and therefore have no apartment number). When they look up their order status in the bot, your API has no apartment number associated with that account, and therefore nothing to pass to the variable. You'll then receive a Failed to Load Variable email. It doesn't mean anything went wrong, just that there was no information to pass to the bot at that time.

Q: When my team and I are creating an API for the bot, do we need readable strings for individual values? Is there anything the bot can't "read"? Is there anything else that we should consider?

A: As a general rule, the Request block supports JSON format for the API request and response. If the response from the API is anything other than JSON, the Request block will provide the chatter with the block’s error Answer.

Currently, all non-200 status codes trigger the Request block's error Answer. As a result, we recommend sending a 200 "OK" status for cases in which the API endpoint is reachable and you want to provide chatters with descriptive error messages.

Have any questions? Contact your Ada team—or email us at help@ada.support.