Skip to main content

​
What Are AI Actions?

An AI Action is a custom integration between your AI Agent and an API. It allows your Agent to perform real actions — such as checking order status, creating a support ticket, or updating customer details — without leaving the chat.

​
Examples

ScenarioExample Action
Order trackingRetrieve order details from your webshop API
CRM lookupFetch customer info from HubSpot
Stock updatesGet real-time stock status from your ERP system
ReturnsConnect to Returnless to process returns automatically

​
Ways to Create an AI Action

You have two options:
  1. Use a Watermelon template → preconfigured and ready to connect.
  2. Create your own Action → build from scratch using your API.
If you’d like a new template added, Watermelon can create one for you — just reach out to support.

​
Step-by-Step: Create a Custom Action

1

Go to Actions

In your AI Agent, open the Actions tab and click Create new Action.
Actions Create Custom Action Pn
2

Add a Name & Description

Choose a clear, descriptive name that tells what the Action does. Add a short explanation of the function.
Example:Name: Retrieve order detailsDescription: Fetch detailed information about an order using the order number and email address.
3

Add the Base URL

Enter your API’s BaseURL — for example:
https://api.example.com/v1
This tells Watermelon where to send requests.
4

Add Authentication

Choose the right authentication method from your API documentation:
TypeDescriptionSetup
NoneOpen API, no credentials neededLeave empty
BasicUsername + PasswordFill both fields
Bearer (API Key)Token-based accessAdd your Token under Bearer
CustomAdd data in headers or query parametersUp to 10 per request
Never expose admin or delete endpoints. Always use HTTPS and secure tokens.
For detailed instructions, see Authentication Setup in the Help Center.
5

Add a Health Check

Add a simple endpoint (e.g. /health or /status) to verify the connection between Watermelon and your API.
6

Write a Schema (The Blueprint)

Your schema defines how your AI Agent talks to your API. Watermelon follows the OpenAPI 3.0 standard. Here’s what every schema includes:
The most important part other than endpoints and attributes are the description these are used by the agent to validate, generate and execute the request
openapi: "3.0.0"
info:
  title: "AI Agent Integration"
  version: "1.0.0"
  description: "Integration between Returnless and the AI Agent"

servers:
  - url: "https://api.example.com/v1"
    description: "Production"

paths:
  /orders.json:
    get:
      summary: Retrieve order details by order number
      description: Get order information from your webshop API
      parameters:
        - in: query
          name: number
          required: true
          schema:
            type: string
          description: The order number to retrieve
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
components:
  schemas:
    Order:
      type: object
      properties:
        id:
          type: integer
          example: 123456
        number:
          type: string
          example: ORD1234
        status:
          type: string
          example: shipped
7

Validate the Schema

Click Validate in Watermelon. If it’s valid, you’ll see all available Actions underneath. If it’s invalid, Watermelon will show an error with the line and column number to fix.
Actions Validate Action Pn
Tip: Use tools like Swagger Editor or Visual Studio Code with an OpenAPI validator to check your YAML.
8

Test the Action

Before publishing, test in the Playground.Test tips:
  • Use real or test data that exists in your system.
  • Add clear Agent instructions if multiple parameters are needed.
  • Check error codes:
    • 400 → wrong parameters
    • 401 → authorization error
    • 404 → wrong endpoint or missing item
    • 500 → server error
Playground Menu Pn
If the Playground doesn’t respond to your action, check if there’s an unfinished Action in Concepts — this can block tests. Remove the unfinished action in order to test properly.
9

Publish

Once everything works, click Publish. Your AI Agent can now use the Action in real conversations.
Actions Publish Pn

​
Using Multiple Attributes

Actions can collect multiple input fields from the user — even across messages.

​
Why it matters

BenefitDescription
Natural flowUsers can reply in any order
AccuracyThe Action only runs when all info is available
Better experienceFeels like a human chat
Example: User: I want to track my order.
AI Agent: Sure! What’s your order number?
User: 123456
AI Agent: Got it. What’s your postal code
User: 90210
AI Agent: And your email address?
User: [email protected]
→ Action triggers automatically.

​
Best Practices for Security

  • Always use HTTPS
  • Limit API responses to what’s necessary
  • Hide or hash personal data
  • Use rate limiting to prevent abuse
  • Monitor usage and logs
  • Don’t hardcode API keys
  • Validate all inputs
  • Avoid admin or delete endpoints unless absolutely required