Actions Node — Sync HTTP

TL;DR:

• Use Sync HTTP when your scenario needs to call an external API and immediately continue the flow.
• Configure the reusable endpoint at the workspace level, then apply request body, URL parameters, testing, and response mapping in the node.
• Best for real-time lookups, enrichment, verification, and lightweight write-backs to external systems.

What it does

The Sync HTTP action lets your scenario send a synchronous HTTPS request to an external API during node execution. It can build a dynamic URL, interpolate request tokens, validate the response, and save selected response values back into your variables.

This is useful when a bot needs fresh data right now, for example:

• checking a product price or exchange rate,
• verifying an external record,
• fetching profile details from another system,
• sending a lightweight status update to your backend.

Unlike a generic webhook, Sync HTTP is designed for request-response workflows. You can test the request inside the editor, inspect the response, and map JSON values directly back into fields.

Where to configure

• Workspace preset: Go to Workspace Settings → Integrations → Sync HTTP to create reusable endpoint definitions.
• Scenario node: Inside the Actions node, add a Sync HTTP action and select one of your enabled presets.

Preset vs Node responsibilities

The feature is split into two layers so teams can reuse endpoint definitions safely:

Workspace preset

Configured on the Integrations settings page.

The preset owns:

• request method,
• URL template,
• headers,
• expected response type,
• success statuses,
• enabled / disabled state.

Use presets for stable transport settings that should be shared across scenarios.

Scenario node

Configured inside the Actions node.

The node owns:

• path parameter values,
• query parameter values,
• request body,
• test values for request macros,
• response mapping,
• node-level response handling preferences.

Use node settings for execution-specific data that can change from one scenario to another.

When to use it

• ✅ Real-time lookup — fetch data from an API before choosing the next message.
• ✅ External verification — validate a coupon, product code, or partner status.
• ✅ Enrichment — load external metadata and store it into subscriber variables.
• ✅ Lightweight write-back — notify your own backend or partner API and continue the flow.

When NOT to use it

• ❌ Long-running jobs — use an async integration or backend worker if the request may take too long.
• ❌ Human-facing content formatting — if you only need to transform data locally, prefer Formula.
• ❌ Bulk background sync — this action is optimized for per-user, real-time execution inside a scenario.

What you can configure

1. Choose a preset in the Actions node

Inside the Actions node, add the Sync HTTP action and select one of your enabled workspace presets.

The node summary shows the selected preset and a compact overview of:

• method + host,
• body mode,
• expected response type,
• success statuses,
• mapping count,
• path/query parameter count.

2. Configure URL parameters

If the preset URL contains placeholders like:

https://api.example.com/v1/products/{product_id}

the node automatically detects them as Path Parameters.

The node can also define Query Parameters, for example:

lang=en
market={%utm_source%}

Path parameters

• Keys come from the preset URL template.
• Keys are read-only in the node.
• You only provide the value.

Query parameters

• Added and removed at the node level.
• Each row has a key and a value.
• Empty values are skipped during request building.

3. Configure request body

The node supports:

• No Body
• JSON
• Plain Text

Body content can include formula-style tokens. The editor inserts tokens visually and stores them in formula syntax.

Examples:

{
  "symbol": "{%ref%}",
  "campaign": "{%utm_campaign%}",
  "promo_code": "{@current_promo@}"
}

4. Configure headers

Headers are configured in the workspace preset, not in the node.

Header values support macro insertion too, but only global variables are allowed there. This keeps preset headers stable and suitable for shared credentials or static workspace-wide values.

Example:

Authorization: Bearer {@api_token@}

Token support

Sync HTTP uses the same user-facing token format as the rest of the scenario builder:

• system, utm, field → {%key%}
• global → {@key@}

Where tokens can be used

Area	Supported tokens
Path parameter values	system, utm, field, global
Query parameter values	system, utm, field, global
Body	system, utm, field, global
Preset headers	global only

Token-aware inputs

Single-line Sync HTTP inputs use a token-aware field:

• inserted tokens appear as chips,
• deleting a token removes it as one unit,
• unknown tokens stay visible so you can spot broken references.

Testing requests

The Test tab is designed to help you build and validate the request before publishing.

What the Test tab does

The Test tab helps you validate the request before publishing. During testing, the editor builds a concrete request from:

• preset method + URL + headers,
• node path/query/body settings,
• current global values,
• generated test values for {%...%} macros.

Test Data panel

If the request contains {%...%} macros in:

• path parameters,
• query parameters,
• body,

the Test tab shows a Test Data section.

Each detected macro gets an editable test value. These values are generated automatically and can be changed manually before running the test.

Examples of generated defaults:

• {%first_name%} → John
• {%email%} → [email protected]
• {%phone%} → +12025550123
• {%utm_source%} → google

Important notes:

• Only {%...%} macros are shown in editable test data.
• {@...@} globals are resolved automatically from real global values.
• Test data is temporary and is not saved into the node.

Raw response preview

The response viewer formats JSON nicely and wraps long lines so you can inspect payloads without horizontal scrolling.

Response mapping

If the response type is set to JSON, the node can map values from the response back into variables.

Source paths

Source paths use dot-path notation:

user.name
data.items.0.code
quote.price

After a successful JSON test, the editor builds a searchable picker from the real response structure. You can either:

• pick a path from the list, or
• type it manually.

Target fields

Targets are selected through the standard target selector and can point to:

• system fields,
• UTM fields,
• global variables,
• custom fields,
• scenario variables: var.key (session) or var.key+ (persist).

When the target is a scenario variable (var.*), the mapped value is written directly to the scenario context and does not push to the CRM outbox. Use var.key for data you need only within the current session, and var.key+ for data that should survive /start and be available in future sessions.

Type guidance

The mapping UI helps you choose safer targets:

• text targets are the safest,
• numeric/date/datetime targets are shown with compatibility hints,
• more risky mappings display a short warning plus tooltip details.

This guidance is especially useful after a JSON test because the editor already knows the source value type from the sample response.

Security and limits

WARNING

Never paste API keys, passwords, or other secrets directly into node-level fields. Store credentials in preset headers using global variables, and restrict access to those variables through workspace roles.

• HTTPS only. All requests are sent over HTTPS. Non-HTTPS URLs are rejected at runtime.
• Request timeout. Sync HTTP requests time out after 15 seconds. If your API is slower, use an async integration or backend worker instead.
• Response size limit. Responses larger than 256 KB are rejected — the action fails and mappings are not applied.
• Rate limiting. The runtime applies per-workspace rate limits. If you exceed the limit, the request is queued and retried automatically.

Output and behavior

The Sync HTTP action is non-fatal. If anything goes wrong — network error, bad status, invalid JSON, timeout, or SSRF block — the action is skipped entirely. No mappings are applied, and the scenario continues to the next action or node.

When mappings are applied

Mappings run only when all of these conditions are met:

• The response type is set to JSON.
• The HTTP status matches the configured success statuses (defaults to 200–299).
• The response body is valid JSON and under 256 KB.

If any condition fails, no mapped values are written and the previous variable values remain unchanged.

When mappings are NOT applied

• The preset is missing, disabled, or the action payload is invalid.
• The URL was blocked by SSRF protection.
• The request timed out or a network error occurred.
• The HTTP status is outside the success range.
• The response body is not valid JSON, is too large, or the response type is Text.

In all these cases, the action is silently skipped. No error is shown to the user, and no branching occurs.

Mapping and type conversion

When mappings do run:

• If the target field already has a type, the runtime tries to convert the value. If conversion fails, that specific mapping is skipped.
• If the target field is untyped, the value is stored as text.
• A bad mapping does not break the entire node — only that one mapping is skipped.

Examples

Example 1 — Lookup by dynamic path parameter

Goal: Fetch market data for a symbol stored in a variable.

Preset URL:

https://api.example.com/v1/symbols/{symbol}

Node path parameter value:

{%ref%}

Result: The request URL is built dynamically for each user.

Example 2 — Send JSON body with tokens

Goal: Send user profile data to an external service.

Body:

{
  "name": "{%first_name%}",
  "email": "{%email%}",
  "campaign": "{%utm_campaign%}"
}

Result: The request body is resolved at runtime with the user's current values.

Example 3 — Map API response back into fields

Goal: Save product metadata returned by an API.

Mappings:

• data.title → custom field product_title
• data.price → custom field product_price
• data.currency → custom field product_currency

Result: The node enriches the user profile with external data for later conditions, formulas, or messages.

Example 4 — Save API response to a scenario variable

Goal: Fetch a loyalty score from an external API and use it later in a Condition or Formula node without touching the CRM.

Response:

{ "points": 420 }

Mappings:

• points → var.loyalty_points (session) — or var.loyalty_points+ to persist across /start

Result: var.loyalty_points is available immediately in Message, Condition and Formula nodes. No CRM field is created or updated.

Common pitfalls

Test request does not run after adding macros

Cause: The request contains {%...%} macros but test data was not reviewed, or the final JSON/body becomes invalid after substitution.
Fix: Open the Test Data section, confirm the generated values, and make sure the resolved JSON remains valid.
Prevention: Use quoted tokens in JSON strings unless you intentionally build a numeric field.

A response mapping does not update the target

Cause 1: The source path does not exist in the latest response.
Cause 2: Runtime could not convert the value into the target type.
Fix: Re-run the test, inspect the response path, and prefer matching data types.
Prevention: Use text targets when you are not sure about the response format.

URL template parameters are missing

Cause: The preset URL includes placeholders like {id} but the node does not provide a value.
Fix: Open the URL Parameters tab and fill every required path parameter.
Prevention: Treat preset URLs as templates and node path parameters as required inputs.

Header token shows as unknown

Cause: The global catalog was not loaded yet, or the referenced global key no longer exists.
Fix: Reopen the modal after the workspace catalog loads, and verify the global variable still exists.
Prevention: Use stable global variables for preset headers and avoid deleting them while they are still referenced.

Sync HTTP vs Webhook

	Sync HTTP	Webhook
Direction	Outgoing request from the bot to your API.	Outgoing notification from the bot to your endpoint.
Response	Reads and maps the response back into variables.	Fire-and-forget; no response handling.
Use when	You need data back immediately to decide the next step.	You only need to notify an external system.
Configuration	Workspace preset + node-level parameters, body, and mapping.	Single URL and optional headers in the Actions node.
Best for	Real-time lookups, verification, enrichment.	Event notifications, logging, triggers.

FAQ

• Q: Can I edit headers inside the node?
  A: No. Headers belong to the shared workspace preset. The node focuses on URL parameters, body, testing, and response mapping.

• Q: Can I use dynamic values in the URL?
  A: Yes. Put placeholders like {product_id} in the preset URL and assign values to them in the node.

• Q: Can I use macros in the body?
  A: Yes. Body content supports the same formula-style tokens used elsewhere in the builder.

• Q: Why are only globals allowed in headers?
  A: Preset headers are shared across scenarios, so they are limited to stable workspace-wide values.

• Q: What happens if a mapping type does not match?
  A: Runtime tries to convert the value. If conversion fails, that mapping is skipped and the flow continues.

Related nodes

• Actions Node — Overview of all action types available in the node.
• Workspace Settings — Integrations — Set up shared Sync HTTP presets, webhook destinations, and email recipients before using them in scenarios.
• Variables and Tags — Understand where mapped values are stored and how to use them later.
• Formula Node — Use formulas when you need local transformations instead of an external HTTP call.