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

# Tools & webhooks

> Let assistants call tools during a conversation, and send call results to your systems through webhooks

Assistants can call tools during a conversation to look something up or take an action. When a call or conversation ends, Famulor can deliver the result to your systems through a webhook.

## Reusable assistant tools

Create tools once on the **Tools** page, then assign them under **Assistant → Settings → Tools** or add them to a flow. Updating a reusable tool updates every assignment.

### API tools

API tools call an HTTP endpoint during a conversation. Define:

* the endpoint and authentication,
* the inputs the assistant should collect,
* any fixed values,
* what the response should contain, and
* whether the caller should hear a short progress phrase.

Use clear descriptions and return only the data the assistant needs to continue the conversation. A tool's description also decides *when* the assistant reaches for it — state the trigger condition plainly ("use this when the caller asks about an existing order") rather than only what the tool does.

| Method   | Use for                                                |
| -------- | ------------------------------------------------------ |
| `GET`    | Fetching data — a lookup, an availability check        |
| `POST`   | Creating something new — an order, a ticket, a booking |
| `PUT`    | Replacing an entire existing record                    |
| `PATCH`  | Updating specific fields on an existing record         |
| `DELETE` | Removing something                                     |

Requests time out after 10 seconds by default (configurable up to 120), and a response over 2 MB is rejected — keep endpoints fast and replies small. Use a scoped, least-privilege API key rather than a master credential, and keep customer-identifying details out of any error message the assistant might read back.

Build an API tool when the answer changes often and the endpoint answers quickly and reliably. If the information barely changes, a [knowledge base](/assistants/knowledge-base) or the system prompt is cheaper and can't fail mid-call.

**Example configurations**

Each value the assistant collects is a named parameter with a description telling it what to ask for. Parameters travel in the query string on `GET` and `DELETE`, and in the JSON body on `POST`, `PUT`, and `PATCH`. To put one in the path instead, write `{{parameter_name}}` into the endpoint URL. Set a parameter's source to **Static** for a fixed value the assistant never has to ask about, and keep credentials in **Headers**.

| Pattern                 | Method | How to set it up                                                                                          |
| ----------------------- | ------ | --------------------------------------------------------------------------------------------------------- |
| Look up by ID           | `GET`  | Endpoint `.../orders/{{order_number}}`, with `order_number` as a parameter the assistant collects         |
| Create something        | `POST` | Endpoint `.../appointments`, with `date` and `service` as parameters — they're sent in the JSON body      |
| Check before continuing | `GET`  | Endpoint `.../customers/lookup`, with `phone` and `email` as parameters — they're sent as query values    |
| Notify only             | `POST` | Endpoint `.../notify` with static parameters only; the assistant simply confirms it passed the message on |

The assistant reads the response and answers in its own words, so return short, plainly named fields (`ship_date`, `confirmed_time`) rather than a deep object it has to interpret.

### Perplexity Agent Connector

Open **Tools → Agent Connectors**, choose **Perplexity AI**, and paste your own API key. Select **Load models** to validate the key and retrieve the models currently available to your account. The same model selector is available later in **Edit** and reloads the catalog using the securely stored key. You can add an optional system prompt and adjust temperature (default `0.2`), Top P (`0.9`), presence penalty (`0`), and frequency penalty (`1`). Maximum tokens is blank by default and is omitted from requests until you set it. The system prompt controls tone, language, style, and answer format; the assistant still supplies the complete research request at runtime. The saved key is masked and is never returned by the tools API.

### External MCP servers

Connect an MCP server by entering its URL and, when required, authentication details. You can allow all offered tools or select only the tools an assistant may use. Reach for this when the other side already exposes a whole MCP toolkit — connecting once brings in every tool it offers; for a single HTTP endpoint, a plain API tool above is usually simpler.

A URL ending in `/mcp` is treated as Streamable HTTP and one ending in `/sse` as classic SSE; anything else tries Streamable HTTP first, then falls back to SSE. Authentication can be **none**, a **static header or bearer token**, or **OAuth** — when the server supports OAuth, Famulor runs the sign-in flow and stores the resulting token.

The Installed list shows the latest execution result and flags connections that need attention. If OAuth expires, choose **Reauthorize** on the existing tool. The sign-in flow repairs that tool in place, so assignments, allowed tools, settings, and run history are preserved.

For each selected tool, **Execution behavior** lets you control cancellation, overlapping calls, and spoken progress updates. Cancellation cannot undo an action the external service has already completed.

<Warning>
  Only connect services you trust. Their tool descriptions, results, and progress messages can influence the conversation.
</Warning>

### Built-in tools

Built-in tools cover common actions such as call transfer, transfer to another assistant, SMS, email, business-hours checks, callbacks, keypad input, payment-card collection, variables, and ending a call.

## Manage tools through the API

Use the public API to automate tool management:

* `GET /api/v1/tools` and `POST /api/v1/tools`
* `POST /api/v1/tools/perplexity/models` to list available models with either a supplied API key or an existing connector ID
* `GET /api/v1/tools/{id}`, `PATCH /api/v1/tools/{id}`, and `DELETE /api/v1/tools/{id}`
* `POST /api/v1/tools/{id}/reauthorize` to receive a short-lived browser sign-in URL for an existing OAuth MCP tool
* `GET /api/v1/assistants/{id}/tools` and `PUT /api/v1/assistants/{id}/tools`
* `GET /api/v1/assistants/{id}/automations`, `POST /api/v1/assistants/{id}/automations`, and `DELETE /api/v1/assistants/{id}/automations/{automationId}`

The connected [MCP endpoint](/api/mcp) offers equivalent assistant-tool operations, including `reauthorize_tool` and `list_perplexity_models`. Tool-list responses include secret-free connection health and the latest execution result. Secret authentication values are masked after they are saved.

For an [automation](/automations/overview) the assistant should call during a conversation, use the assistant-automation endpoint or MCP `create_assistant_automation`. Provide a precise description of when it should run. The same assignment is available in voice, web chat, messaging, and email conversations. The platform creates a draft workflow and securely connects the required tool without returning credentials. Build its steps, return a concise result suitable for spoken or written replies, and make the automation Live when it is ready; pausing it also disables the callable tool everywhere. These generated tools are shown as automation-managed and can only be edited or disconnected from Assistant settings. Conversational retries reuse the same run and response, so they do not repeat billing or side effects.

## Receive call results with webhooks

When a call finishes, Famulor sends its result to the webhook URL configured on the assistant (**Settings → Automations → Call completed**). The URL is unsigned and belongs to that one assistant. Per-assistant delivery settings — timeout, retry count, and a test send — live on [Post-call webhooks](/assistants/webhooks).

Email threads reuse the same assistant URL: once the assistant has replied, Famulor delivers a `conversation.ended` event there carrying the thread transcript and its analysis. Telegram, Slack, and the other messaging connectors have their own **Conversation ended webhook URL** instead, set per connector — see [Messaging channels](/channels/messaging).

<Note>
  Signing works differently for the inbound **variable webhook** — the per-assistant URL Famulor calls at the start of an inbound call to enrich variables. That request carries an HMAC-SHA256 signature; see [Custom variables](/assistants/variables#inbound-variable-webhook).
</Note>

### `call.completed`

The event includes customer-facing call details such as assistant, direction, status, duration, timestamps, transcript, collected flow variables, campaign context, and available recording links.

If the call cannot complete, the payload includes a provider-neutral `failure` object with a stable code, customer-safe message, retry guidance, and suggested action. Build recovery logic from this object rather than infrastructure-specific details.

<Tip>
  Return a successful `2xx` response promptly. Process longer follow-up work after acknowledging the webhook.
</Tip>

## Poll instead of receiving a webhook

You can retrieve the same call result with `GET /api/v1/calls`, `GET /api/v1/calls/{id}`, or the call-history tools in [MCP](/api/mcp). A newly created call initially returns its current status; poll until it reaches a final state.