Skip to main content

The integration contract

This section is for whoever builds the HTTP handler on the client side.

The request from the platform

The URL, headers, parameters, and body are assembled from the form fields with {{variable}} substitution. Available are the call variables (from_number, to_number, direction, and everything configured in the agent and the campaign), the results of functions from previous rows of the block, and — in the post-call block only — call and analysis. The method is set in the function; the default is GET with no body — parameters go into the query string. For other methods the body is sent as JSON (the default), as a form (form), or as is (raw) with the given Content-Type. Secrets are never typed into the fields: reference them as {{env.NAME}}. The value is substituted at execution time from the flow secrets of your organization; if there is no such secret, an empty string is substituted. The reference works in the URL, query parameters, headers, and body. In the call history the request is stored masked. The platform does not sign requests and does not add authorization headers. Pass the key to your API yourself — in a header or a parameter via {{env.NAME}}, for example Authorization: Bearer {{env.CRM_TOKEN}}. The URL must be http or https. The platform refuses requests to local addresses and to internal network addresses — 10.x.x.x, 172.16.x.x–172.31.x.x, 192.168.x.x, 100.64.x.x–100.127.x.x and names ending in .local or .internal: nothing is sent and <name>_error is blocked. If the function service runs inside an internal network, contact support to have its address allowed for your organization. Redirects are followed, and every new address is checked again. The TLS certificate is verified by default.

Timeout, retries, and the budget

The request timeout is a field of the function, 10 s by default with a 30 s ceiling. It applies to a single attempt: with retries the total time is longer. Retries are off by default. Only 5xx responses, network errors, and timeouts are retried; a 4xx is not. The pause before each next retry doubles from the value set (0.5 s by default: 0.5 → 1 → 2 s). Your handler must tolerate a repeated request with the same data. How the timeout relates to the block budget:

The response and the mapping

A response is successful if its code is in the function’s “Successful response statuses” (2xx by default). A non-JSON response is kept as text. From the response the platform writes the service set into the scenario variables, plus whatever the mapping lists. <name> is the technical name of the HTTP function (the “Name” field inside the function form). The mapping is a dictionary of “variable name → JSONPath in the response”; the variable name is the key, not the value. The form shows it that way too: the name on the left, the path on the right (balance ← $.data.balance). On a name clash the mapping variable wins over the service one. The names are chosen by whoever configures the agent in the cabinet, not by you — agree in advance on which fields you return. JSONPath is supported as a subset: $, .key, [n], ['key']. There are no filters and no *. If nothing is found at the path, the variable is not written.

The dial decision

To stop a campaign dial, return the fields that the mapping puts into call_decision, call_decision_reason, and call_retry_after (values and consequences are in Dial decisions in a campaign). How the platform reads these fields:
  • call_decision — proceed, cancel, or retry, case-insensitive. Any other value — the call proceeds, with a warning in the event.
  • call_decision_reason — cut to 200 characters.
  • call_retry_after — seconds or an ISO-8601 instant; without a time zone it is read as UTC. A retry is scheduled no sooner than 60 s ahead.
  • The decision applies only to dials from a campaign.
A minimal handler that cancels the call:
In the function’s response mapping: call_decision ← $.decision, call_decision_reason ← $.reason. Then run a campaign with a single contact: the phone stays silent, the contact is closed, and the outcome breakdown shows “Cancelled by function”.

The trial run

The Test and Test the block buttons hit the cabinet endpoint POST /api/flows/{name}/call-functions/run. Body: {function, phase: "pre"|"post", variables?, mock?, budget?}, or {functions: [...]} to run the whole block. The budget field picks the budget: inbound — before the first reply, 10 s by default, or outbound — before dialing, 60 s by default; for phase="post" it is ignored. In a trial run the budget clips the timeout in both cases, and there is no background completion. For phase="post" the body accepts analysis — a stub of the analytics result. The answer for a single function: The answer for a block: outcomes (one entry per function, fields as above), batches (the layout by rows), elapsed_ms, variables_after. For phase="pre" both also carry decision — how your decision was read: {action, reason, retry_after, retry_at, warning, declared}.

Platform configuration keys

These keys are set by the platform administrator; they are not changed from the organization’s cabinet.