Run app actions during conversations

An app action tool lets an assistant run one action in a connected app while the conversation is still going. Examples are adding a row to a Google Sheets spreadsheet or creating a contact in HubSpot. You choose the app, the connection and the action, and Famulor turns the action’s fields into a tool with real parameters. You don’t need your own API endpoint or an automation.

App action tools are in Beta. Owners and admins see them once Beta Features is on under Settings → Workspace, and the workspace plan must include Automations. Other members see assigned app action tools but can’t change them.

How an app action tool works

A hair salon wants callback requests from callers in a spreadsheet. It creates an app action tool for the Google Sheets action “Add row”. The spreadsheet and the sheet are fixed values, the assistant fills in the caller’s name and request, and the phone number comes from the caller ID. Before the assistant writes the row, it reads the details back and asks the caller to confirm them. The tool appears in Agent Tools next to your other tools, and you assign it to assistants like any other tool. It works in every conversation channel:

phone calls, web calls and WhatsApp calls
web chat, including Test Chat
every messaging channel, such as WhatsApp, SMS, Telegram or Slack
email, both the assistant’s own address and connected mailboxes

Choose the right kind of tool

An app action tool covers exactly one action in one app. For anything else, another tool type fits better:

You need	Use
One action in a connected app	An app action tool (this page)
A request to your own HTTP endpoint	An API tool
Several steps, conditions or apps in one run	An automation called from the conversation

For a single action, an app action tool is faster than a callable automation. The assistant sends each field directly, so no extra AI step has to pull the values out of a free-text request.

Before you start

Check these requirements first:

You’re an owner or admin of the workspace.
Beta Features is on under Settings → Workspace.
The workspace plan includes Automations, and its Tools & MCP limit has room for another tool.
The app is connected under Automations → Connections. You can also connect it while you create the tool.

Create an app action tool

Choose the app and the action

Open Agent Tools and select New tool → App (Beta). You can also start from the Apps card under Agent Connectors, where an app logo opens that app directly, or select Use in assistant next to an app under Automations → Connections. The editor lists your connected apps. To add another app, select Connect an app: the same app list as in Automations opens, and you return here after signing in. Then pick the action. If the app has more than one connection, choose one under Connection.

Name the tool and say when to use it

Name is prefilled, for example google_sheets_add_row. In Use when, describe the situation in which the assistant should call the tool, for example “When the caller asks for a callback.” Use at least 10 characters. A specific sentence works better than a short label.

Choose where each value comes from

Each field of the action has a Value from setting, described in the next section. Required fields come first. Optional fields start as Off under More fields.

Decide whether the assistant asks first

For actions that change data, Ask first is on. Leave it on unless the change needs no confirmation. The section on Ask first below explains how it works.

Check the preview and test

What the assistant sees shows the tool exactly as the assistant receives it. Run a test under Test before you save, as described below.

Save and assign

Select Create tool, then assign the tool to assistants. In an assistant’s settings, Advanced → Tools → Add tool lists your Connected apps: select one to open the same editor, or select Connect an app to connect another app first. The tool is assigned when you select Add to assistant. An app action tool can’t be a Tool step in a flow yet; assign it to the assistant instead.

Set where each value comes from

Value from decides who provides the value of a field:

Value from	The value comes from	Use it for
AI	The assistant, from the conversation	Details the customer tells you, such as a name, a request or a preferred date
Fixed value	Your entry, sent on every run	IDs of a spreadsheet, calendar, list or pipeline, and fixed labels
Variable	A conversation variable, such as Caller number	The caller’s phone number, the customer’s email address or an assistant variable
Off	Nothing: the field isn’t sent	Optional fields you don’t need

For AI fields, Famulor writes a description from the app’s field information, including the expected format, such as YYYY-MM-DD, and an example. Type your own description to replace it. Up to 12 fields can use AI. Keep it to 8 or fewer: fewer fields make calls faster and more reliable. The assistant never sees Fixed value and Variable fields and can’t change them. A fixed text can contain variables such as {{caller_number}} and the values of AI fields, written with the parameter name shown in What the assistant sees, for example {{start_time}}. When you paste a link to a Google Sheets, Docs, Drive, Notion or Airtable item, Famulor keeps only its ID. A few more rules apply to fields:

Phone fields start with the variable Caller number. On messaging channels, it holds the contact’s phone number.
Required fields can’t be Off.
Some fields take table rows, for example the values of a new spreadsheet row or the attendees of an event. They show Columns. For a spreadsheet row, select Add column for each value and name the column. For a list such as attendees, the app sets the columns, for example Email and Name; select Add row for each entry. Choose AI, Fixed value or Variable for each cell. A required column needs a value in every row.
In a list such as attendees, optional columns start Off. Turn them on for a row when you need them. Number and yes/no cells take AI or Fixed value.

What the assistant sees lists the tool name, its description and every AI field. Fixed values and variables appear as not visible to the assistant. The description can be up to 900 characters long. Select the pen icon to write the description yourself. The sentences about confirming changes and about unknown outcomes always stay at the end.

Ask first

Actions that change data, such as adding a row or creating a contact, have Ask first turned on by default. Actions that only read data never ask. With Ask first on, a change runs like this:

The assistant calls the tool. Nothing changes yet: Famulor returns a summary of the values.
The assistant reads the summary to the customer and asks whether it’s correct.
The assistant calls the tool again with the same values. This call runs the action in the app if the condition of the channel is met:
- In messaging and email, the customer has sent a new message since the summary.
- On calls and in web chat, at least 4 seconds have passed since the first call. There, Famulor can’t tell whether the customer answered.

A call that comes too early changes nothing, and the assistant is told to wait for the customer’s answer. If a value changes in between, the assistant reads the new details back and asks again. A prepared change expires after 10 minutes on calls and in web chat, after 72 hours in email, including connected mailboxes, and after 24 hours in other messaging channels.

On calls and in web chat, Ask first only enforces a pause: a change can run after 4 seconds even if the customer didn’t answer. In messaging and email, a change runs only after a new message from the customer. In no channel is Ask first a consent record: Famulor doesn’t check what the customer answered and keeps no separate proof of agreement. Where you need documented consent, for example for a contract or a payment, collect it through a process built for that purpose.

You can turn Ask first off for a change that needs no confirmation. The assistant then changes data in the app without reading it back first.

Test before you use it

Test every tool before you assign it to an assistant that talks to customers. Under Test, enter sample values for the AI and variable fields and select Run test:

Actions that read data run for real.
Actions that change data first run as a dry run, which changes nothing and shows what the assistant would read back. Select Run for real and confirm to make the change in the app.

The result shows whether the run succeeded, how long it took and exactly what the assistant receives. On calls, the caller waits while the action runs, so check the duration. Afterwards, try the tool in a Test Call or Test Chat with the assistant it’s assigned to.

What the assistant receives

Famulor shortens every result before the assistant reads it. It removes internal IDs, version numbers and values that look like secrets. It also cuts texts to 500 characters and lists to 10 items, and it limits the whole result to 2,000 characters. Under Advanced → Result, choose Selected fields to keep only the fields you pick from a successful test result. Through the API, result_config.max_chars raises the limit to 3,500 characters. The assistant receives results marked as external data, not as instructions.

Limits

Limit	Value
Time per run	12 seconds; the app must answer within 8 seconds
AI fields per tool	12
Tool description	900 characters
Text per value	4,000 characters
Result for the assistant	2,000 characters, up to 3,500 through the API
Runs per tool	60 per minute
Runs per workspace	300 per minute
Runs per tool in one conversation	15 per minute, including up to 5 changes (reading the details back isn’t a change)
Actions that delete data	Not available yet

When the app doesn’t answer in time, the result depends on the action. An action that reads data didn’t run, and the assistant can try again. For a change, the outcome is unknown: the assistant doesn’t retry and tells the customer that the team will check.

Edit, reconnect or delete a tool

Open the tool in Agent Tools to change its fields, Use when or Ask first. Runs lists the tool’s recent runs from every channel, including messaging, email and tests. A prepared change that waits for the customer and a dry run don’t appear there, because nothing ran in the app. Failed runs and runs with an unknown outcome show as errors. To use a different action, create a new tool.

You can switch the tool to another connection of the same app.
When a connection expires, the tool shows Reconnect and doesn’t run until you reconnect it. Select Reconnect and sign in again: Famulor renews the same connection and brings you back to the tool. If the tool has unsaved changes, Famulor first asks whether to discard them. If the sign-in fails, the tool shows the error and Reconnect again.
You can’t delete a connection that app action tools use. Move the tools to another connection or delete them first.
To delete an app action tool, first remove it from every assistant that uses it. Then delete it like any other tool.
App action tools can’t be moved to another workspace. Create the tool again in the other workspace.

API, MCP, CLI and SDK

You can create, read, change and test app action tools without the dashboard. Every request needs an owner or admin credential. Listing and reading actions, and creating, changing or testing a tool, also need a workspace plan with Automations. Listing actions and reading an action need the scope automations:read, reading a tool needs assistants:read, and creating, changing or testing a tool needs both assistants:write and automations:write. As in the dashboard, creating a tool also needs Beta Features.

API	MCP	CLI	SDK
`GET /api/v1/automations/connections/{id}/actions`	`list_app_actions`	`famulor list-app-actions <id>`	`client.api.listAppActions({ path: { id } })`
`GET /api/v1/automations/connections/{id}/actions/{action}`	`get_app_action`	`famulor get-app-action <id> <action>`	`client.api.getAppAction({ path: { id, action } })`
`POST /api/v1/tools/app-actions`	`create_app_action_tool`	`famulor create-app-action-tool --input tool.json`	`client.api.createAppActionTool({ body })`
`GET /api/v1/tools/app-actions/{toolId}`	`get_app_action_tool`	`famulor get-app-action-tool <toolId>`	`client.api.getAppActionTool({ path: { toolId } })`
`PATCH /api/v1/tools/app-actions/{toolId}`	`update_app_action_tool`	`famulor update-app-action-tool <toolId> --input patch.json`	`client.api.updateAppActionTool({ path: { toolId }, body })`
`POST /api/v1/tools/app-actions/{toolId}/test`	`test_app_action_tool`	`famulor test-app-action-tool <toolId> --input test.json`	`client.api.testAppActionTool({ path: { toolId }, body })`

App action tools also appear in GET /api/v1/tools with an app_action summary. Assign them with PUT /api/v1/assistants/{id}/tools, or pass assistant_id when you create the tool; an unknown assistant returns 404 before the tool is created. GET /api/v1/tools/{id}/runs and the MCP tool list_tool_runs return the runs shown under Runs. Remove a tool from its assistants, then delete it with DELETE /api/v1/tools/{id}. The general PATCH /api/v1/tools/{id} can still rename a tool or turn it on and off; any other change there returns 409. The general test, POST /api/v1/tools/test or test_tool, also returns 409 for an app action tool.

Create a tool with the API

First, list the actions of a connection. q searches by name. Actions that delete data aren’t listed.

curl "https://app.famulor.io/api/v1/automations/connections/CONNECTION_ID/actions?q=row" \
  -H "Authorization: Bearer YOUR_API_KEY"

Read the details of the action you picked with get-app-action. They list the action’s fields, each with its key, path, param and a suggested mode. In the create request, send only the fields you want to change, identified by path or key. You can set mode, value, variable and description; all other fields keep their suggested setting. This request creates the tool and assigns it to an assistant:

{
  "connection_id": "CONNECTION_ID",
  "action": "ACTION_ID",
  "use_when": "When the caller asks for a callback.",
  "confirmation": "ask_first",
  "assistant_id": "ASSISTANT_ID",
  "fields": [
    { "key": "spreadsheet_id", "mode": "fixed", "value": "SPREADSHEET_ID" },
    { "key": "phone", "mode": "variable", "variable": "caller_number" }
  ]
}

Field keys depend on the action. confirmation is ask_first or none; actions that read data never ask. To make sure the action hasn’t changed since you read it, also send its version: the request then fails if the action has a newer version. Save the body as tool.json and send it with famulor create-app-action-tool --input tool.json or POST /api/v1/tools/app-actions. Then test the tool. values holds sample values for the AI and variable fields. Use each field’s param, the parameter name the assistant sees, not its key. The two often differ: the field startTime has the param start_time, and a column takes the name of the column, such as name. For a variable field, the variable name, such as caller_number, works too:

{
  "values": { "name": "Anna Weber", "request": "Call back about a color appointment" },
  "mode": "dry_run"
}

mode is dry_run, the default, or live. For an action that changes data, a live test also needs "confirm_write": true and changes real data in the app. The response contains model_text, the exact text the assistant would receive. For an action that changes data, read_back lists what the assistant would read back, also in a dry run.

Getting started

Assistants

Flow builder

Telephony

Channels

Audience

Campaigns

Live operations

Workspace settings

Billing

Run app actions during conversations

How an app action tool works

Choose the right kind of tool

Before you start

Create an app action tool

Set where each value comes from

Ask first

Test before you use it

What the assistant receives

Limits

Edit, reconnect or delete a tool

API, MCP, CLI and SDK

Create a tool with the API

Next steps

Agent Tools

App Catalog

​How an app action tool works

​Choose the right kind of tool

​Before you start

​Create an app action tool

​Set where each value comes from

​Ask first

​Test before you use it

​What the assistant receives

​Limits

​Edit, reconnect or delete a tool

​API, MCP, CLI and SDK

​Create a tool with the API

​Next steps

Agent Tools

App Catalog

How an app action tool works

Choose the right kind of tool

Before you start

Create an app action tool

Set where each value comes from

Ask first

Test before you use it

What the assistant receives

Limits

Edit, reconnect or delete a tool

API, MCP, CLI and SDK

Create a tool with the API

Next steps