Tools

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.

For a full walkthrough of creating, authenticating, testing and publishing tools in the dashboard, see the Tools overview. This page focuses on the JavaScript tool code reference.

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 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:

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:

{
  "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.

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

const { name, id } = input.sessionContext.variables;

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

{
  "channel_type": "whatsapp_cloud",
  "external_id": "+5521986260652",
  "name": "Maria",
  "id": "123456789"
}

`config`

Contains secrets configured for the tool:

{
  "secrets": { "SECRET1": "value" }
}

Return value

Tools must return a tuple [data, outcome]:

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:

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:

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',
      ];
  }
}

See WhatsApp Flow endpoints for the full data-exchange protocol.

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`)

Get Started

Campaigns

Audiences

Messaging

Opt-Outs

Webhooks

Assets

AI Features

Analytics

Business Management

Integrations

Webchat

Resources

Tools

Tools section

Tool structure

Parameters

`input`

`config`

Return value

Versioning and deployment

Testing tools

Tool URL as a WhatsApp Flow endpoint

WhatsApp Flow handler example

Monitoring executions

Using a tool in a flow

​Tools section

​Tool structure

​Parameters

​input

​config

​Return value

​Versioning and deployment

​Testing tools

​Tool URL as a WhatsApp Flow endpoint

​WhatsApp Flow handler example

​Monitoring executions

​Using a tool in a flow

Tools section

Tool structure

Parameters

`input`

`config`

Return value

Versioning and deployment

Testing tools

Tool URL as a WhatsApp Flow endpoint

WhatsApp Flow handler example

Monitoring executions

Using a tool in a flow