Custom Actions

Build custom actions that let you do things you can't do in Adalo - like use external services (APIs) to send emails, crop photos, generate IDs, or shorten URLs like in this walkthrough.

Skill Level: Expert

Before You Begin

• You will need a paid Adalo plan to use this feature

• Ensure you have an understanding of Actions, Databases, and Magic Text

• Ensure you have read about the basics of APIs (see our primer on them here)

Current Limitations:

• You can't use the return value of a Custom Action if it is used as a whole-screen action.

• Custom Actions do not work on Form component submit buttons.

Intro Video

The video above is Version 1 of Custom Actions. If you want to see Version 2 where you can now bring data back into your app from other external apps, watch the video here!

Walkthrough

Simple

For a detailed beginner's walkthrough with a simple example, click on the In-Depth tab.

1.) Select the component you would like to add the custom action to. Note that custom actions do not work on forms or for using return values on whole-screen actions.

2.) In the Click Actions section of the component's settings, click Add Action, hover over Custom Action, then click New Custom Action.

3.) Give your new Custom Action a name and select the label to be displayed in the Adalo Builder. Choose from Create, Update, or Delete, then click Next

4.) Next you'll want to reference your chosen APIs documentation to find its Base URL, Authorization requirements (if any), and parameters to be sent. Each API is different and has different requirements. For help with this step you can see our primer on APIs or start with a simple example in the In-Depth tab to get your feet wet.

5.) Input the APIs Base URL in the API Base URL field of the custom action. Note that you can use Magic Text here as well to reference the inputs you create (Step 7)

5.) Add any headers or query parameters that are required for your API by clicking +Add Item, then choosing either Header or Query Parameter. Some common headers are the Authorization header and the Content-Type header.

6.) Next, you'll need inputs for your action. You'll want to add an input for each changing piece of data you want to send to the API. In the right side of the popup under the Inputs section, click +Add Item

7.) Give the input a label/name and select what type of data it is. More information on data types can be found in the Learn More section of this help guide.

8.) In the Body input field, build or paste the request JSON body. You can use Magic Text to replace portions of the request with the inputs you just made. This makes these portions of the request variable (dynamic) so you can send different data to the API with each request.

9.) Click Run Test Request. If all goes well, you will receive a Test Successful message along with an output from the API called shortURL. These outputs are automatically created Magic Text outputs for the returned data. You can customize these outputs by clicking on them to change their name or type, or you can delete an output if you don't need it. Once done, click Save Custom Action.

If you receive an error or the test is not successful, check your Custom Action setup and try again. You can always click Show Full Response to see the full response from the API as well as any error codes. If you don't have any returned information, you can also click on +Add Item to find and add the result manually if it is available.

10.) Now that your action is setup you can place Create, Update or Delete actions below it and reference the custom action outputs through Magic Text. If you need to edit the custom action, you can click on the Pencil icon in the lower left of the action.

11.) Now that your custom action is setup, you can use it in any app in your team and on any component!

In-Depth

1.) For this walkthrough, add an Input field and a Button to a blank screen as well as a Text property to the User's Collection called "Personal Link". If you need help with this step, please see our Getting Started guide first. You should have something like this:

2.) Select the component you want to add a custom action to. In this walkthrough, we'll be adding it to a button that will shorten a link for us using a powerful external service called Micro.

3.) In the button's Click Actions area, click Add Action, then hover over Custom Action and choose New Custom Action. If you have created Custom Actions previously, you will see those here as well.

4.) Give the new custom action a Name such as "Shorten URL" and choose what type of action to display it as in Adalo. You can choose from either Create, Update, or Delete. For this walkthrough, let's choose Create and click Next.

5.) Open the browser tab containing your Micro account, click on your email in the top right corner, then click on API Keys. API Keys are like a password for your API usage. For this particular API, we can create multiple API Keys if we need to for different apps, but not all APIs are this way.

6.) Click on Create. A popup will appear where you should enter a key Description and select the Scopes, or permissions, this key will use. The scopes directly relate to the services you would like to use with this API Key. In our case, we're going to use the URL service to shorten a URL so just check URL for now. (You can see a full list and descriptions of Micro's services here.)

7.) Click Create and you will see your new key in a black text box. Make sure you click Copy and save this to a safe, but memorable location. If you lose your key, you will need to create another one. Click Close once you're done.

8.) With the popup now closed, find the code snippet in the API Usage section, then copy the portion that says https://api.m3o.com/v1/{service}/{endpoint} . This is our Base URL. Paste this into your Custom Action's API Base URL field.

9.) Next we'll replace the {service} and {endpoint} portions of the link with the service and endpoint we want to use. The Micro documentation for the url service tells us that the endpoint for shortening URLs is called shorten. So our Base URL now looks like this: https://api.m3o.com/v1/url/shorten.

10.) Most APIs will specify which Method should be used for an endpoint depending on it's function, but for Micro we should select POST from the dropdown. For more information on request methods, see our Methods primer.

11.) This API requires authentication using our API key. Back in the API Keys portion of your Micro account, you will find in the API Usage section that it requires a Header (-H) named Authorization with your key as the value. For our Custom Action, click +Add Item under the Headers and Queries section, then choose Header

12.) For the name of the header, type in Authorization. For the value, type in Bearer, then paste in your API Key that you saved from Micro. Don't forget to add a space (not Enter) between Bearer and your Key.

13.) Next, we need to add an input field for our Action so that we can send any URL we want using Magic Text. Click +Add Input under the right-hand Inputs section of the Custom Action. Since a URL is a combination of letters, numbers and symbols, choose Text as the input type.

14.) Give the new input a label/name such as "URL to be Shortened", paste in a URL as the Example Value to test with, then click Done. You can find a complete list of the data types and descriptions in the Learn More section of this help guide.

15.) We need to send any related parameters to our endpoint. In this case, we need to send the URL to be shortened. The Micro documentation for our "Shorten" endpoint tells us that we only have to send one parameter called destinationURL . In the JSON Body field of the Custom Action, paste in the Request code snippet from Micro documentation: { "destinationURL": "https://mysite.com/this-is-a-rather-long-web-address" }

If the endpoint you're using requires multiple parameters, format them the same way, but add a comma after each line except the last one. Take Micro's Weather Forecast endpoint for example:

{ "days": 3, "location": "St. Louis" }

For more information on using and creating JSON like this, see our primer on JSON

16.) Use the Magic Text button to replace the https://mysite.com/this... in quotes with the "URL to be Shortened" Input we created.

17.) Click Run Test Request. If all goes well, you will receive a Test Successful message along with an output from the API called shortURL. These outputs are automatically created Magic Text outputs for the returned data. You can customize these outputs by clicking on them to change their name or type, or you can delete an output if you don't need it. Once done, click Save Custom Action.

If you receive an error or the test is not successful, check your Custom Action setup and try again. You can always click Show Full Response to see the full response from the API as well as any error codes. If you don't have any returned information, you can also click on +Add Item to find and add the result manually if it is available.

18.) Now we need use Magic Text to set the input we created called URL to be Shortened to be whatever the user types into the input field.

19.) You can use the outputs of a Custom Action in subsequent actions. For our example, let's add an Update action to our button underneath our Shorten URL action we just made. Let's have it update the Logged in User.

20.) Use Magic Text in the "Personal Link" property to place info from our previous custom action Shorten URL > shortURL. If you ever need to edit the Custom Action, click on the action and select the Pencil icon in the lower left of the action.

Video

Custom Action Example - Shorten a Link with the Micro API

Custom Action Example - Send an Email with SendGrid

Custom Action Example - Send Information to a Zapier Webhook

Using the Results or Outputs of a Custom Action

Example

Now when a user puts a link into the input field and taps the button, it will send the link to the Micro API, return the shortened link, and save it to the User's record.

Since Custom Actions cannot be copied with apps, we can't provide a cloneable template, but if you would like to try out the app used in this walkthrough, click here.

Learn More

• The Micro API has lots of wonderful endpoints that work the exact same way as this walkthrough. Just be sure to branch out and explore other APIs now that you have some experience with a simple one. You can use a site like Public APIs to find free and paid APIs to help you do all sorts of cool things in Adalo.

• For a complete list of use cases for Custom Actions, click here.

• Custom Actions work best with REST APIs and can only recognize JSON responses. APIs utilizing XML, SOAP, or GraphQL are not supported unless they can return JSON responses.

• Custom Actions do not work on form actions.

• Custom Actions can't send multiple records in their API request.

• Custom Actions are different from External Collections in that they are used to perform a single function instead of displaying a list of items like an external collection.

• Custom Actions cannot be copied from team to team

Help

If you would like to take a further look at the capabilities of Custom Actions, we will highly recommend you to take the Custom Actions Course from The Adalo App Academy.

If you need additional help with this article, you can always ask in our community forum! Be sure to paste the link to this article in your post as well!