Tools & 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. 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 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. 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.

​

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

​

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.

​

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. A newly created call initially returns its current status; poll until it reaches a final state.