> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/en/crm-marketing/message-personalization/connected-content.md). # Writing Connected Content This is a feature that pulls **real-time data** from an external API at the very moment a message is sent and inserts it into the body.\ You can use information that is not stored in Hackle, such as remaining points, today's coupon, and personalized recommended products, in your messages.

#### How to write Connected Content for non-developers {% hint style="success" %} You do not need to write code directly.\ When you press the **`{...}` Add personalization variable button** in the message editor, the `{% connected_content %}` tag is automatically generated just by filling out a form. {% endhint %} {% hint style="info" %} **Before you start (get these from your development team)** 1. The API address to call (starts with `https://`) 2. The request method (GET or POST) 3. A response example (JSON) - to check which fields can be used in the message {% endhint %} {% stepper %} {% step %} ### Select Connected Content Click the `{...}` button in the message editor. Select the **Connected Content** tab. At the top of the modal, choose between **Property** and **Connected Content**. Select **Connected Content — real-time data from an external API**.

{% endstep %} {% step %} ### Enter and test the API URL Enter the **API URL**. If you need authentication headers or a POST body, expand **Request Options** and enter them. You can insert personalization variables such as `{{user_properties["id"]}}` directly into the URL as well. Then, press the **`Test API`** button to check in advance whether the actual response comes back correctly and which fields are included.

{% endstep %} {% step %} ### Choose the values and variable name to insert into the message From the response result, check the fields to display in the message (e.g., `code`, `discount`). Then, enter the name (e.g., `product`) to use for the \*\*response variable name (`:save`)\*\*. This name becomes the variable you will use to pull values out in the body.

{% endstep %} {% step %} ### Insert the saved variable into the body When you press `Save`, the variable created by the modal is added to the **"Available variables" list**. Place the cursor at the desired position in the body and click that variable, and it will be inserted automatically like `{{coupon.code}}`. ```liquid {% connected_content https://dummyjson.com/products/1 :save product %} The {{product.title}} you saved has {{product.stock}} left in stock! Discover it now for {{product.price}} won. ``` {% hint style="info" %} In case the response comes back empty, include a **fallback text** as well. {% endhint %}

{% endstep %} {% endstepper %} ### Basic Syntax ```liquid {% connected_content [:method ] [:body ] [:headers ] [:save ] %} ```

Item	Description	Required
`<URL>`	The absolute URL of the API to call. Only the `https://` scheme can be used. Only final URLs that resolve to a public IP can be called.	Required
`:method`	The HTTP method. `GET` and `POST` are supported. The default is `GET`. `PUT`, `DELETE`, `PATCH`, and the like skip the entire tag.	Optional
`:body`	The POST request body. Used only when `:method POST`. Ignored for GET requests. Enter a JSON object string. Example: `:body {"foo":"bar"}`	Optional
`:headers`	The request headers. Enter a JSON object whose values are all strings. Example: `:headers {"Authorization":"Bearer abc","X-Trace":"123"}` If you enter a numeric value such as `:headers {"Retry": 3}`, validation fails and the tag is skipped. `Content-Type: application/json` is applied by default.	Optional
`:save`	The name of the variable that will store the response JSON object. You can then use it as `{{variable.field}}`. It can also be referenced by subsequent tags and Output nodes in the same template. If the response is not an object or is empty, an empty value is stored.	Optional

{% hint style="success" %} You can freely use personalization variables such as `{{user_properties["name"] | default: "Customer"}}` and `{{event_properties["campaign_id"] | default: "1"}}` in the values of the URL, body, and headers. {% endhint %} ### Response Handling Rules | Response form | Result | | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200 OK` + JSON object |

Parses the JSON and maps it to the :save variable.

Fields are accessed via {{var.field}} or {{var\["field"]}}

| | `200 OK` + JSON array or primitive value | Not a JSON object, so treated as an empty value | | `200 OK` + empty body | Treated as an empty value | | All status codes other than 200 (4xx, 5xx, 3xx, etc.) | Treated as an empty value (***redirects are not followed***) | | Response body exceeds 1MB | Treated as an empty value | | Network error, timeout | Treated as an empty value | {% hint style="warning" %} Being treated as an empty value means that an empty map is stored in the variable specified by `:save`. `{{var.anything}}` renders as an empty string, and this does not cause the message send itself to fail. {% endhint %} ### Security Policy

Item	Limit
URL scheme	Only `https://` allowed
Host	Only hosts that resolve to a public IP are allowed Internal networks / private ranges are blocked.
Redirects	Not followed You must specify the final URL directly.
Response body size	Up to 1MB Treated as an empty value if exceeded.
Single call timeout	2 seconds
Cumulative call time within one message (Liquid render)	2 seconds total Calls after the limit is exceeded are skipped without an HTTP call.
HTTP methods	`GET`, `POST` only
Header value format	JSON object string, all values must be strings

### Behavior on Failure Connected Content does not block message sending. All failure cases are "***replaced with the default value***." **Representative cases:** * URL is empty or a flag-value pair does not match → entire tag is skipped * An unsupported method such as `PUT` is specified in `:method` → tag is skipped * `:headers` is not a valid JSON object string → tag is skipped * URL validation fails (not HTTPS, private IP, etc.) → empty response * Network error, non-200 response, body exceeds 1MB, not a JSON object → empty response * Calls after the cumulative call time within one message exceeds 2 seconds → skipped without an HTTP call, empty response Even if you use a variable in which an empty response is stored in the message, it renders as an empty string. Therefore, we recommend adding defensive code like the following in case the response is empty. ``` {% connected_content https://api.example.com/coupon :save coupon %} {% if coupon.code %} Today's coupon: {{coupon.code}} {% else %} Check it out right now! {% endif %} ``` ``` {% connected_content https://api.example.com/user :save user %} Hello, {{ user.name | default: "Customer" }}! ... ``` *** ### Examples #### 1. The simplest GET call ```liquid {% connected_content https://api.example.com/products/123 :save product %} {{product.name}} {{product.price}} won ``` If the response is `{"name":"Sneakers","price":59000}` → `Sneakers 59000 won` #### 2. Inserting user/event variables into the URL ```liquid {% connected_content https://api.example.com/orders/{{event_properties["order_id"]}} :save order %} Order status: {{order.status}} ``` If `event_properties.order_id = "ABC-123"`, the actual call URL becomes `https://api.example.com/orders/ABC-123`. #### 3. POST + JSON body ```liquid {% connected_content https://api.example.com/recommend :method POST :body {"user_id":"{{user_properties["id"]}}","limit":3} :save rec %} Recommended product: {{rec.items[0].name}} ``` #### 4. A call that requires an authentication header ```liquid {% connected_content https://api.example.com/me :headers {"Authorization":"Bearer {{api_properties.token}}"} :save me %} Hello, {{me.nickname}} ``` #### 5. Extracting a value from a nested JSON response ```liquid {% connected_content https://api.example.com/products/456 :save data %} {{data.product.name}} by {{data.product.brand}} ``` Response `{"product":{"name":"T-shirt","brand":"Nike"}}` → `T-shirt by Nike` #### 6. Tag chaining (using the result of a previous call in the next call) ```liquid {% connected_content https://api.example.com/me :save me %} {% connected_content https://api.example.com/orders/{{me.id}} :save orders %} {{me.id}} has {{orders.total}} orders ``` #### 7. POST + form-encoded body + custom headers ```liquid {% connected_content https://api.example.com/post :method POST :headers {"X-Trace":"abc123","X-Src":"hackle"} :body {"a":1,"b"=3} :save r %} {{r.ok}} ``` *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.hackle.io/en/crm-marketing/message-personalization/connected-content.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.