Skip to main content
When you design an Action in Watermelon, the AI Agent often needs to collect several pieces of information from a user before it can run the Action — for example an order number, postal code and email address.

​
Mapping API Fields to Attributes

Each required or optional parameter in your API schema must have a corresponding input field (attribute) in your Action. Example:
API parameterAttribute name (Watermelon)Required?Type
order_numberorder_numberstring
postal_codepostal_codestring
emailemailstring

​
How to Add

  1. Open your Action in AI Agent → Actions.
  2. Under Input Fields, click Add Field.
  3. Use the exact parameter name expected by your API.
  4. Mark each as required or optional.
  5. Save the Action.
Always copy parameter names directly from the API documentation to avoid case or spelling mismatches.

​
How the AI Agent Handles Partial Inputs

The Agent automatically keeps track of what the user already provided and what’s still missing. Behavior
  • If all required fields are not yet filled, the Agent asks only for the missing ones.
  • If the user answers in any order, the Agent maps each answer to the correct field.
  • Once all required values exist, the Agent triggers the Action automatically.
No extra scripting is needed — this behavior is built in.

​
Writing Natural Follow-Ups

The Agent’s follow-up messages are generated from the field names and Domain Knowledge you provide. Well-written prompts make the interaction sound natural.
FieldExample Follow-Up
email“Can I have your email address?”
postal_code“What’s your postal code?”
order_number“Could you share your order number?”

​
Developer Tip

If your attribute name is technical (customer_email_address), add an instruction in Domain Knowledge like:
“When asking for customer_email_address, say ‘Can I get your email address?’”

​
Required vs Optional Fields — When to Trigger the Action

  • Required fields → Must be filled before the Action runs.
  • Optional fields → Used if available; otherwise ignored.
Watermelon automatically waits until all required attributes have values before calling the API. Example If your API path is 
/orders?order_number=123&email=jane@example.com
and both parameters are marked required, the Action triggers only after the Agent has collected both values.

​
**Confirmation **

Even though the agent has all the data it won’t automatically execute the action. The agent will first ask to verify if all attributes are correct. The user has a chance to review the data and and change it by correcting the agent **“That is not my email address, it should be example@.test.com” **
The way the agent asks for comfirmation is steerable in the domain knowledge
If the user is happy with the data they can **confirm **the action. With a direct response. “Yes, Okay,” Or a sentence “Yes that is correct”
The confirmation logic is not optional and can not be overwritten by instructions in the domain knowledge this can rather confuse the agent and give bad results