Nullifying optional parameters in API calls for advanced AI agents

What's my plan?

Add-on

AI agents - Advanced

You may have an API that can accept multiple request parameters, yet not all are mandatory to make a successful call. If a parameter is expected but not provided, the integration may fail because the API expects a valid value—whether an empty string `””` or `null`. In that case you will need to nullify these parameters in the integration builder so that the call does not break.

To nullify optional parameters

1. Understand optional parameter behavior.
   First, make sure that your API can gracefully handle optional values as either an empty string or `null`.
2. On Chat Start, initialize the optional parameters to null or an empty string.
   This will prevent the API call from failing when a parameter is omitted. For more information, see About actions for advanced AI agents.
   
   
3. In the integration in the integration builder, make sure that the parameters are collected as request parameters and that the check box for Required is unchecked.
   
4. Hover over the Test value input box until you see the symbol for reformat values.
   
   When you click this, a dialog appears. Here, you want to add the following JSONata expression to the text box that says “Reformatting JSONata”:
   ```$a and $not($a = "null") ? $a : ""```
   This JSONata expression will check whether the parameter exists and has a value.
   • If it does, pass the parameter value to the API.
   • If it doesn’t, provide an empty string or omit it entirely.
     
     For more information on how to reformat values, see Reformatting values in request parameters for advanced AI agents.

Now when you have a value that is optional for your API call, it will be handled by the integration builder seamlessly.