Skip to main content

Pre-call functions

Pre-call functions run before the conversation — before the number is dialed on an outbound call, and after the connection but before the agent’s first line on an inbound one. Their result lands in the call’s variables, so the agent knows them from its first word. When exactly the block starts and what budget it has is on Pre- and post-call functions.

Adding a pre-call function

In the pre-call functions block, click + Add and pick a kind:
  • Custom function — an HTTP request to your system;
  • Code — a short Python script in a sandbox.
The card appears in the block and its form opens on the right. A new function is named by kind and number — “Function 1”, “Code 1” — and you can rename it.

Shared fields

The panel header shows the function kind (“Custom function” or “Code”) and the “Before call” mark. Below it:
  • Name — the label of the card in the block. It does not affect variables.
  • Description — a note for you and your colleagues.
  • When to run — “After previous” or “Parallel with previous” (see Ordering and parallelism). The first function of a block has no such field.
Right below them are two hints. The first is about the shared budget of the block: 10 s before the first reply for inbound and web calls and 60 s before the dial for outbound; whatever does not fit is skipped, and on inbound calls it keeps running in the background. The second is about the decision variables call_decision, call_decision_reason, and call_retry_after (see Dial decision).

Custom function (HTTP)

A new custom function is created in “HTTP (real call)” mode with the POST method and an empty URL, and its function name equals the card id (cf1). Replace it with a clear prefix, for example crm. Until you have an address, switch the mode to “Mock (deterministic response)”.
  • Name — inside the Function section this is a second, different field, and it is the prefix of the result variables. A function named crm writes crm_status, crm_success, crm_error, crm_result. Both fields are labeled “Name”: the one at the top of the panel is the card label, the one inside the Function section is the prefix.
  • Execution mode — “Mock (deterministic response)” or “HTTP (real call)”. While you are still building the flow, keep the mock: nothing leaves the platform.
  • Method and URL — the method is picked from a list: GET, POST, PUT, PATCH, DELETE. The URL, Query params, Headers, and the body support {{variable}} substitution.
  • Secrets — do not type keys into the fields: in the URL, headers, params, and body write a {{env.NAME}} reference to an organization secret, and the value is substituted at execution time. The call history stores the request with the value masked.
  • Body (request body) — available for every method except GET. Type: json, form, or raw. Content-Type (override) sets the header by hand; left empty, Content-Type follows the body type.
  • Response variables (variable ← JSONPath) — the variable name the flow will see is on the left, the path in the JSON response on the right, for example $.data.balance. Only what is listed here becomes a variable from the response.
  • Timeout, sec — 10 by default, 30 maximum. The timeout applies to each attempt.
  • Retries — 0 by default, so there are no retries. A retry fires on a network error, a timeout, and a 5xx response; a 4xx is not retried.
  • Backoff, sec — 0.5 by default, doubling with each retry: 0.5 → 1 → 2 s. With retries and backoff a call lasts longer and spends the block budget.
  • Verify TLS certificate (tls_verify) — on by default.
  • Success when (success statuses) — 2xx by default; you can list your own codes and ranges, for example 200-299, 404. If the response is declared as JSON but does not parse, the function ends with the invalid_json error.
Mock response and scenarios. The section at the bottom of the form sets what the function returns in mock mode and on Test with mock:
  • Mock status and Mock response — JSON with {{variable}} substitution;
  • Mock scenarios — named variants, added with ”+ Scenario”: “success (response)” with its own status and JSON response, or timeout / network to emulate a failure;
  • Default active scenario — which scenario answers; ”— base mock response —” takes the status and response from the fields above.
Custom function panel: the card Name on top and the function Name — the variable prefix — inside the Function section

Code

  • Code (Python sandbox: vars, metadata, http, now) — vars (the call variables), metadata (call metadata), http(...) (a request under the same URL policy as a custom function), and now("Asia/Almaty"). There are no imports, no file access, and no print. {{env.NAME}} references are not expanded in http(...) — make requests that need secrets with a custom function.
  • Output variables (comma-separated) — the names your code put into result. Every key of the result dict becomes a call variable, even if it is not listed. A listed name the code did not fill keeps its previous value, and if there was no such variable, none appears. The names vars, result, now, metadata, and http belong to the sandbox itself: an output variable named like one of them never reaches the call variables, and the builder warns about it.
  • Execution timeout, sec — 10 by default, 30 maximum.
Code function panel: the sandbox, output variables and the timeout

The variables a function produces

A custom function always writes a service set, even with an empty response mapping: Plus everything you listed under response variables. On a name clash your mapped variable wins over the service one. A code function writes <id>_success, and <id>_error only on failure. Its prefix is not the name but the card id (cf1, cf2). Plus the keys of result and the output variables you declared. A code function does not write http_*.

Dial decision

A pre-call function can return a dial decision — its response is placed into the variables call_decision, call_decision_reason, and call_retry_after. The card of such a function shows the ⤳ icon with the tooltip “This function decides what happens to the call”. The pre-call block runs on every outbound call — from the cabinet, through the public API, and in a campaign — but the decision applies only to a campaign dial. More on Dial decisions in a campaign.

Ordering and parallelism

Cards run top to bottom in the order the system executes them. One row is one step. To make two functions run at the same time, drag one card onto the other’s row; while dragging, the hint reads “Runs with this row”. A row of two or more cards is outlined with a dashed border and labeled “in parallel · N”. To restore the queue, drag the card into the gap between rows (“Gets a row of its own”). Without a mouse the same is done by:
  • the When to run field in the function form — “After previous” or “Parallel with previous”;
  • keys on the focused card: Alt+↑ and Alt+↓ move the card as a separate row above or below, Alt+→ puts it into the row above, Alt+← takes it out of a shared row into its own.
What matters about rows:
  • Variable visibility is by row, not by arrow. A function in row k sees the variables of every earlier row, not just of the ones it was placed after. The results of a row are merged into the shared set once the whole row has finished, in card order left to right — which is why http_* ends up belonging to the last custom function of the row.
  • Two functions in one row cannot write the same thing. The same prefix (function name) or overlapping result-variable names within one row is an error: the outcome would depend on who finished first. Across rows it is allowed, and the later row wins.
  • A failure does not cancel what follows. If a function fails or times out, the one placed after it still starts and sees <name>_success = "false".
  • Cards do not move between the pre and post blocks: a function has no phase switch.
Under the block there is a line “Longest chain: N s of 10 s”. That is the budget check: what counts is not the sum of all timeouts but the longest chain of consecutive rows. Three requests of 4 seconds in one row are 4 seconds, not 12. If the chain is longer than 10 s, a warning appears listing the ids of the functions in it, for example cf1 → cf3. Pre-call block: a batch row "in parallel · 2" and the longest-chain line

Testing without calling anyone

One function. Select the card. A custom function has two buttons at the bottom of the panel: Test — a real call to your URL — and Test with mock — the same run with the mock mode forced, so nothing leaves the platform. A code function has a single button, Run Code. Pre-call functions also carry a Trial budget selector with two values — “Before the first reply (inbound, web)” and “Before dialing (outbound)” — so you can see that a slow request misses the first budget and fits the second. The result appears under the buttons and on the card: Success, Error, Timeout, or Skipped (budget exhausted), plus the time in milliseconds, the status code, and the list of variables written. If a pre-call function returned a dial decision, a line right there reads “Decision: dial”, “Decision: cancel the dial”, or “Decision: defer the contact”. Warnings: “The decision value was not recognized — the dial goes on” and “The retry time was not readable — the campaign retry policy applies”. The whole block. Once a block holds more than one function, a Test the block button appears. It runs the rows the way a call would, but without late delivery: whatever does not fit the chosen budget gets “Timeout” or “Skipped (budget exhausted)”. Functions in HTTP mode call your real addresses. The answer shows “Whole block — N ms” and a per-row breakdown: “Row 1:”, “Row 2:”, and the status of each function. This is the fastest way to confirm that parallelism is set up the way you intended. The trial result lives until the page is reloaded and is never saved into the flow. Trial run: the budget selector, the buttons and the result card Whole-block run broken down by rows

Late delivery of a result

On inbound and web calls, a function that misses the budget before the first reply is not cut off. The agent starts speaking on budget while the function keeps running in the background with its own timeout, and the result flows into the ongoing conversation — the next flow node that reads variables will see it. Until the result arrives, nodes see <name>_success = "false" and <name>_error = "late". The history holds two events for such a function: first “waiting for the result”, then the final status. An utterance already spoken is not replayed: if the agent greeted the caller without a name, it will not retrofit one. Boundaries:
  • outbound calls have no late delivery — the 60 seconds before dialing are enough;
  • in realtime mode late data reaches variables and tools, but not the system prompt that was already assembled;
  • the chat test in the editor stays synchronous.