The External Request action allows you to send or request information from external services, and then receive a response from them and write it to the subscribers' custom fields.
Below we will consider the simplest scenario for using the "External Request" action. This scenario is far from real, but it shows the setup stages and all the functionality of the "External Request".
Description of the scenario and its settings
In this example, we will use the swapi.dev . It stores information about the Star Wars film series: movie titles, character names and their characteristics, descriptions of vehicles, planets, races, and so on.
In other words, this service is a Wikipedia on the Star Wars universe.
Main stages of the script
- The subscriber gets into the bot.
- The bot sends a request to the swapi.dev service with the subscriber ID.
- The service returns a description of the character whose ID is the same as the subscriber's.
- The bot writes the character's name into the custom field and displays this value to the subscriber.
Setting up the bot
Build a simple bot chain:
- Add a block "Message 1".
- Write a welcome text.
- Add a button to move to the next step.
- Add a block "Message 2".
- Display the user's ID.
- Using this ID, the external service will find the character in its database.
- Add an Action 1 block.
- In this block, select the action "External request". The external request settings are described below.
- Add a block "Message 3".
- Output a custom field in which you will write the name of the character received from the external service.
- Connect all the blocks and you will get a small bot like this:
Setting up an "External Request"
- After adding the "External Query" action in the "Action 1" block, click on the "pencil" to open the "External Query" editing window. Then you will need to configure everything in the window that opens.
- Enter the request URL.
- In the description of the swapi.dev service, select the method that will return the character's characteristics: https://swapi.dev/api/people/ 1 /
- Copy and paste the address into the URL field.
- In this address, "1" is the character ID. Instead of the value, insert a macro that will automatically substitute the subscriber's internal ID. To do this, click on the <> in the "URL address" field and select the desired macro.
- Final link: https://swapi.dev/api/people/{%bh_user_id%}
- Select the request type.
- The type of this request is GET. This information should be on the external service's website with a description of its API. Select this type in the "Request type" drop-down list.
- There are no headers or body to fill in with this method, so move on to testing the request.
- To make sure everything works correctly and the service returns the correct response, go to the "Response" tab or click the Test Request .
- In the opened tab you see test data for the used macros. The default value is "10". If necessary, you can change it.
- To start testing, click the Send Request .
- The response is “200 OK”, which means the external service received your request and successfully returned a response.
- On the right side of the window, in the "Response Body" section, you can see what you received in response to your request.
- You are interested in the value of the "name" field. This is what you will automatically write into the subscriber's custom field.
- Set up response matching.
- Response mapping allows you to set up logic that will take the value of the required field from the received response body and write it to the specified subscriber custom field.
- To do this, you should specify 1) the path by which you need to find the required field in the response body (read more here: link ), 2) and the user field itself in which you need to save the value.
- To do this, add a mapping and fill in the fields that appear.
- The JSON Path value "$.name" will return the value of the "name" field from the body of the response received. In the example from testing, the value was "Obi-Wan Kenobi".
- You are now finished setting up the External Request.
- Be sure to save its settings by clicking Save .
- Be sure to save the settings for the open Action 1 step by clicking Save and Close .
Testing the bot with an external request
- Start testing the bot.
- As a result, you will receive a chain of messages like this:
I am Darth Vader, who are you?🙂
If you have not found the answer to your question, ask us in the chat inside your account or write to BotHelpSupportBot or to hello@bothelp.io
Get 14 days of full functionality of the platform for creating mailings, autofunnels and chatbots BotHelp.