> ## Documentation Index
> Fetch the complete documentation index at: https://watermelon.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating custom actions

> AI Actions let your AI Agent interact directly with your systems — retrieving data, updating records, or performing automated tasks — using your own APIs.

## **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

| **Scenario**   | **Example Action**                                     |
| :------------- | :----------------------------------------------------- |
| Order tracking | Retrieve order details from your webshop API           |
| CRM lookup     | Fetch customer info from HubSpot                       |
| Stock updates  | Get real-time stock status from your ERP system        |
| Returns        | Connect 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**

<Steps>
  <Step title="Go to Actions">
    In your AI Agent, open the  **actions** tab and click the **plus** icon at Custom action.

    <Frame>
      <img src="https://mintcdn.com/watermelon/PZD11tUblG7-A9Ak/images/developer-resources/actions/create-custom-action/create-new-action.png?fit=max&auto=format&n=PZD11tUblG7-A9Ak&q=85&s=0841a793d357369e0f73e129fe93ce49" alt="Create New Action" width="2938" height="1390" data-path="images/developer-resources/actions/create-custom-action/create-new-action.png" />
    </Frame>
  </Step>

  <Step title="Add a Name & Description">
    Choose a **clear, descriptive name** that tells what the Action does. Add a short explanation of the function.

    <Tip>
      **Example:**

      **Name:** Retrieve order details

      **Description:** Fetch detailed information about an order using the order number and email address.
    </Tip>
  </Step>

  <Step title="Add the Base URL">
    Enter your API's **BaseURL** — for example:

    ```html theme={null}
    https://api.example.com/v1
    ```

    This tells Watermelon where to send requests.
  </Step>

  <Step title="Add Authentication">
    Choose the right **authentication method** from your API documentation:

    | **Type**         | **Description**                         | **Setup**                       |
    | :--------------- | :-------------------------------------- | :------------------------------ |
    | None             | Open API, no credentials needed         | Leave empty                     |
    | Basic            | Username + Password                     | Fill both fields                |
    | Bearer (API Key) | Token-based access                      | Add your Token under **Bearer** |
    | Custom           | Add data in headers or query parameters | Up to 10 per request            |

    <Tip>
      Never expose admin or delete endpoints. Always use HTTPS and secure tokens.
    </Tip>

    For detailed instructions, see [**Authentication Setup**](/help-center/developer-resources/action-authentication-setup) in the Help Center.
  </Step>

  <Step title="Add a Health Check">
    Add a simple endpoint (e.g. /health or /status) to verify the connection between Watermelon and your API.
  </Step>

  <Step title="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:

    <Tip>
      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
    </Tip>

    ```html theme={null}
    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
    ```
  </Step>

  <Step title="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.

    <Frame>
      <img src="https://mintcdn.com/watermelon/8QuK--6W0h-SCjPt/images/actions-validate-action.png?fit=max&auto=format&n=8QuK--6W0h-SCjPt&q=85&s=566b2c629e6bbf17ce021e0487b5d160" alt="Actions Validate Action" width="1440" height="729" data-path="images/actions-validate-action.png" />
    </Frame>

    <Tip>
      Tip: Use tools like **Swagger Editor** or **Visual Studio Code** with an OpenAPI validator to check your YAML.
    </Tip>
  </Step>

  <Step title="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

    <Frame>
      <img src="https://mintcdn.com/watermelon/1pxoPCWu6i6tm9uj/images/developer-resources/actions/testing-debugging-playground.png?fit=max&auto=format&n=1pxoPCWu6i6tm9uj&q=85&s=53fc7f8a82e1cc4e35041d9ef44cb6d1" alt="Testing Debugging Playground" width="2938" height="1390" data-path="images/developer-resources/actions/testing-debugging-playground.png" />
    </Frame>

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="Publish">
    Once everything works, click **Publish**. Your AI Agent can now use the Action in real conversations.

    <Frame>
      <img src="https://mintcdn.com/watermelon/PZD11tUblG7-A9Ak/images/developer-resources/actions/create-custom-action/create-action-publish.png?fit=max&auto=format&n=PZD11tUblG7-A9Ak&q=85&s=4314c779db4e06b5e3c053635b88a9a9" alt="Create Action Publish" width="2938" height="1390" data-path="images/developer-resources/actions/create-custom-action/create-action-publish.png" />
    </Frame>
  </Step>
</Steps>

## **Using Multiple Attributes**

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

### Why it matters

| **Benefit**       | **Description**                                 |
| :---------------- | :---------------------------------------------- |
| Natural flow      | Users can reply in any order                    |
| Accuracy          | The Action only runs when all info is available |
| Better experience | Feels 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:** [jane@example.com](mailto:jane@example.com)\
→ *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