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

# Tools

> Create standalone JavaScript tools that can be versioned, tested, and used as WhatsApp Flow endpoints — directly from your campaign flows 📓

Tools are JavaScript functions you create and manage in the **Tools** section of Connectly (`/tools`). Each tool is versioned, deployable, and reusable across multiple flows. Tools also automatically receive a public HTTPS URL you can use as a WhatsApp Flow data-exchange endpoint, with end-to-end encryption handled by Connectly.

## Tools section

The Tools section has four tabs:

| Tab              | Description                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Tools**        | Your personal tool library. Each tool has a code editor, version selector, deploy button, and a built-in test panel. Tools you create here are private to your account unless explicitly shared.                                                                                                                                                                                                       |
| **Shared Tools** | Tools shared with your business by Connectly or other team members. Shared tools can be referenced in any flow without copying the code.                                                                                                                                                                                                                                                               |
| **Executions**   | A filterable log of every tool call across your business. Use this for debugging and monitoring — see [Monitoring executions](#monitoring-executions) below.                                                                                                                                                                                                                                           |
| **Integrations** | Pre-built integrations that expose external services as callable operations inside your tools. For example, the **Commerce Platform** integration provides e-commerce operations (checkout, cart, orders, and more) that your tool code can invoke directly, without manually writing HTTP calls. Each integration shows the number of available operations and how many are required to configure it. |

## Tool structure

Every tool exports a single `onExecute` function:

```javascript theme={null}
export async function onExecute(input, config) {
  const { id } = input.sessionContext.variables;

  const resp = await fetch(`https://api.example.com/validate?id=${id}`, {
    headers: { Authorization: `Bearer ${config.secrets.API_KEY}` }
  });
  const result = await resp.json();

  return [{ valid: result.valid }, 'SUCCESS'];
}
```

## Parameters

### `input`

Contains the current session context:

```json theme={null}
{
  "sessionContext": {
    "business": { "id": "..." },
    "customer": { "phoneNumber": "..." },
    "variables": { "VAR1": "1" }
  }
}
```

| Field                                 | Description                                                                                                   |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `sessionContext.business.id`          | Your Connectly business ID.                                                                                   |
| `sessionContext.customer.phoneNumber` | The current customer's phone number.                                                                          |
| `sessionContext.variables`            | All session variables set so far in the flow, including any variables passed when the campaign was triggered. |

<Note>
  **Campaign input variables** — Variables sent with a campaign (e.g. `name`, `id`) are automatically available in `input.sessionContext.variables`. No extra setup required.

  ```javascript theme={null}
  const { name, id } = input.sessionContext.variables;
  ```

  Example `sessionContext.variables` when a campaign is sent with custom variables:

  ```json theme={null}
  {
    "channel_type": "whatsapp_cloud",
    "external_id": "+5521986260652",
    "name": "Maria",
    "id": "123456789"
  }
  ```
</Note>

### `config`

Contains secrets configured for the tool:

```json theme={null}
{
  "secrets": { "SECRET1": "value" }
}
```

## Return value

Tools must return a tuple `[data, outcome]`:

```javascript theme={null}
return [{ FIELD1: 'one', FIELD2: 42 }, 'OUTCOME2']
```

| Return value | Type   | Description                                                                                                                                                               |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`       | object | JSON object — any fields you want to save to session variables.                                                                                                           |
| `outcome`    | string | A string that maps to an outgoing edge in the flow. Each possible outcome must be configured as an edge in the Campaign Builder. There is no default or fallback outcome. |

## Versioning and deployment

Tools support versioning. Use the version selector in the editor header to manage releases, and click **Deploy** to publish a new version. Previous versions remain available for rollback.

## Testing tools

Each tool has a built-in **Test** panel on the right side of the editor. Paste a mock JSON payload into the input field and click **Run Test** to execute the tool and inspect the output and logs without triggering an actual campaign.

## Tool URL as a WhatsApp Flow endpoint

Every tool is automatically assigned a public URL:

```text theme={null}
https://app.connectly.ai/tools/{tool-id}
```

You can use this URL directly as the **data-exchange endpoint** for a WhatsApp Flow. Connectly handles E2E encryption transparently — no key management required in your tool code.

### WhatsApp Flow handler example

WhatsApp Flows send an `init` action first, then `data_exchange` actions as the user navigates screens. Route on `action` and `screen`:

```javascript theme={null}
export async function onExecute(input, config) {
  const { action, screen, data } = input;

  // Respond to the initial ping with the first screen
  if (action !== 'data_exchange') {
    return [{ screen: 'FIRST_SCREEN', data: {} }, 'SUCCESS'];
  }

  // Route by the screen that submitted the data exchange
  switch (screen) {
    case 'SCREEN_PERSONAL':
    case 'SCREEN_DOC':
      return [await handleDocScreen(data, config), 'SUCCESS'];
    default:
      return [
        { screen: '', data: { error_message: 'Unknown screen: ' + screen } },
        'ERROR',
      ];
  }
}
```

<Tip>
  See [WhatsApp Flow endpoints](/messaging/whatsapp-flow-endpoints) for the full data-exchange protocol.
</Tip>

## Monitoring executions

The **Executions** tab shows a log of every tool call with filters for:

* **Tool** — narrow to a specific tool
* **Status** — filter by success or error
* **Time range** — 15 min, 30 min, 1h, 6h, 1d, 2d, 3d, 7d, 15d, or custom
* **Execution ID / Session ID / Room ID** — look up a specific call from a campaign run

## Using a tool in a flow

In the Campaign Builder, add a **Tool node** and select the tool you want to call. Map the tool's `data` output fields to session variables for use in downstream nodes.

| Raw param    | Maps to session variable                      |
| ------------ | --------------------------------------------- |
| `outcome`    | Any variable you configure (e.g. `VARX`)      |
| `data`       | Any variable (receives the whole data object) |
| `data.FOO.1` | A specific nested field (e.g. `VAR_FOO1`)     |