Make an HTTP request from Composer

APPLIES TO: Composer v1.x and v2.x

Your bot might need to access an external service, on behalf of the user or as part of your business logic. To make an HTTP request, with or without authentication, use the Send an HTTP request action.

You can use the Bot Framework Emulator to test such a bot locally.

Prerequisites

• A basic bot you built using Composer
• An external service for your bot to call
• Basic knowledge of how to send an HTTP request without OAuth
• Basic knowledge of how to use OAuth in Composer

Set up OAuth in Composer

This section uses OAuth to issue the HTTP request to authenticate a user. For information about anonymous requests, see Make an HTTP request anonymously.

Composer v2.x

1. In Composer, create a bot using the Empty bot template. Let's call it testhttp.

2. Optionally, in the Greetings trigger, set the message to Testing HTTP request.

3. Follow the steps described in the article Add user authentication to set up OAuth in your bot to access GitHub. The Unknown intent trigger is modified as shown in the figure below.

   The Send a response message contains ${turn.oauth.token} that is the token returned by GitHub after the connection with the bot has been succeeded.

   Also make sure your Composer settings have the appropriate app ID and app password of the Azure Bot resource, as described in Configure OAuth connection settings in Composer. When Azure creates the Azure Bot resource, it also generates an app ID and an app password.

4. Select Start Bot, then Test in Emulator.

5. In the emulator, enter a short message. The bot will display a Login card.

6. Select Login and follow the required steps. GitHub will send back the connection token.

   

Now, with the OAuth setup ready and token successfully obtained, you're ready to add the HTTP request in your bot.

Composer v1.x

See the article Add user authentication to set up OAuth in your bot. The Token property you set will store the OAuth token result, and you can reference it using ${dialog.token.token}. Also make sure your Composer settings have the appropriate app ID and app password of the Azure Bot resource described in Configure OAuth connection settings in Composer. When Azure creates the Azure Bot resource, it also generates an app ID and an app password.

Optionally, you can add a Send a response action to test if your bot can get the OAuth token.

1. Select the + icon then Send a response from the list of actions. In the Text box on the right, enter The token is: ${dialog.token.token}. When this action fires, the bot will output the value of the authentication token.

2. Select the Start Bot button in the Composer toolbar, then Test in Emulator. You should be able to see the authentication token in the Emulator as shown below:

   

Now, with the OAuth setup ready and token successfully obtained, you're ready to add the HTTP request in your bot.

Make the HTTP request

Composer v2.x

1. In Composer, open the Create page.

2. Select the Unknown intent trigger in the bot explorer.

3. In the authoring canvas, select the + icon, under Send a response.

4. Select Access external resources from the drop-down menu, then Send an HTTP request.

   

5. In the properties pane, set the method to GET, then set the URL to your target API. For example, a typical GitHub API URL such as https://api.github.com/users/your-username/orgs.

6. Add headers to include more info in the request. For example, we can add two headers to pass in the authentication values in this request.

   1. In the first line of header, add Authorization in the Key field and bearer ${turn.oauth.token} in the Value field. Use Tab or Enter to save your changes.
   2. In the second line of header, add User-Agent in the Key field and Vary in the Value field. Use Tab or Enter to save your changes.

7. Finally, set the Result property to dialog.api_response and Response type to json.

   Note

   The HTTP action sets the following information in the Result property: statusCode, reasonPhrase, content, and headers. Setting the Result property to dialog.api_response means you can access those values via dialog.api_response.statusCode, dialog.api_response.reasonPhrase, dialog.api_response.content and dialog.api_response.headers. If the response is json, it will be a deserialized object available via dialog.api_response.content.

Composer v1.x

1. The HTTP request action is found under the Access external resources menu in the flow + button.

   

2. In the Properties pane, set the method to GET and set the URL to your target API. For example, a typical GitHub API URL such as https://api.github.com/users/your-username/orgs.

3. Add headers to include more info in the request. For example, we can add two headers to pass in the authentication values in this request.

   1. In the first line of header, add Authorization in the Key field and bearer ${dialog.token.token} in the Value field. Press Enter.
   2. In the second line of header, add User-Agent in the Key field and Vary in the Value field. Press Enter.

4. Finally, set the Result property to dialog.api_response and Response type to json.

   Note

   The HTTP action sets the following information in the Result property: statusCode, reasonPhrase, content, and headers. Setting the Result property to dialog.api_response means you can access those values via dialog.api_response.statusCode, dialog.api_response.reasonPhrase, dialog.api_response.content and dialog.api_response.headers. If the response is json, it will be a deserialized object available via dialog.api_response.content.

Process and test the HTTP response

Composer v2.x

Add an If/else branch to test the response of this HTTP request.

1. In the authoring canvas, select the + icon, under Send an HTTP request.

2. Select Create a condition from the drop-down menu, then Branch:If/else.

3. In the properties pane, set Condition to dialog.api_response.statusCode == 200.

4. Add two Send a response actions to be fired based on the testing results (true/false) of the condition. This means if dialog.api_response.statusCode == 200 is evaluated to be true, send a response called with success! ${dialog.api_response}, else send a response calling api failed.

   

5. Restart your bot and test it in the Emulator. After logging in successfully, the response content of the HTTP request should be visible.

Composer v1.x

You can add an If/else branch to test the response of this HTTP request.

1. Set Condition to dialog.api_response.statusCode == 200 in the Properties pane.
2. Add two Send a response actions to be fired based on the testing results (true/false) of the condition. This means if dialog.api_response.statusCode == 200 is evaluated to be true, send a response called with success! ${dialog.api_response}, else send a response calling api failed.
3. Restart your bot and test it with Web Chat or the Emulator. After logging in successfully, the response content of the HTTP request should be visible.