HTTP Request Block

Article Quick Links:

• What is the Request Block?
• How to set up a Request Block (GET Requests)
• Frequently Asked Questions

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

How to set up a Request Block (GET Requests)

1. Enter the API address in the URL field.
2. Select your request type from the Method drop down menu.

Note: Use the Headers field to pass metadata, like public access tokens and language.

Example:  

3. Click "Test Request" to see the values the request returns
4. Add Variables for use in Text Messages by clicking the blue tags with “+” icon in the Response body. The information will then populate the ‘Create Variables’ field.
   
   Example: 
   
   
5. Choose your Variable type (local or global, or sensitive) and click the green “+” icon.
6. Use “Error Answer” to set a fallback Answer that will be sent to the chatter if your request to the API fails.

Note: You must first create a separate “HTTP request failed” Answer in order to select it from the list of Answers when setting a fallback.

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 however, simply click the arrow icon next to the trash can icon in the upper right corner of the block. 

Frequently Asked Questions

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"? 

A: In general, if the response from the API is in JSON format, the bot can read it. As a rule, the Request Block will typically only work as long as the API is in JSON format.

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 at all. 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's 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 address & 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 the 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 will trigger the Request Block's error answer. As a result, of this, 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 [e-mail].