# MADIAD Hub starter pack

This pack turns a Google Sheet into a publishing desk: you write a row, n8n reads it, publishes to
the platforms you ticked, and writes the outcome back into that same row.

**The sheet is useful on its own, for free.** Draft, plan, assign channels. To have a row actually
publish itself you need an API key, which means a MADIAD Hub plan.

---

## What is in the pack

| File | What it does | Needed |
|---|---|---|
| `wf-01-publish-on-schedule.json` | Sweeps the sheet every 15 minutes and publishes marked rows | **Yes** |
| `wf-03-reconcile.json` | Polls posts the platform is still processing and records the real outcome | **Yes** |
| `wf-02-publish-at.json` | Publishes when the time in `Publish At` arrives | if you schedule |
| `wf-04-usage.json` | Writes your plan usage into the `Usage` tab each morning | recommended |
| `wf-06-retry-unpublish.json` | Handles the `Retry` and `Unpublish` actions | if you need them |
| `wf-05-publish-now.json` | Publishes the moment you mark a row, no 15-minute wait | optional |
| `Gate.gs` | Script you paste into the sheet: menu + publish-now, only for `wf-05` | only with wf-05 |

> **Why `wf-03` is not optional:** several platforms accept a post and process it afterwards, so
> when `wf-01` returns, the post is *queued*, not live. Without `wf-03` every such row **sits at
> `Publishing` for ever** even though the post went out fine.

---

## Step 1, take a copy of the sheet (2 minutes)

1. Open the template sheet and choose **File › Make a copy**. The original is read-only for everyone.
2. On the **Config** tab, fill in `profile_id` (from your MADIAD Hub dashboard, under Connections).
3. Posting to Pinterest? Add `pinterest_board_id` too.

That is enough to draft and plan, before n8n is involved at all.

> **Which Facebook Page receives the post?** Not decided here. The destination is whichever Page you
> **pin in the dashboard**, and a pin always wins, even over a Page ID sent with the request.

---

## Step 2, connect n8n (10 minutes)

### 2.1 Store the API key once

In n8n: **Credentials › New › Header Auth**

| Field | Value |
|---|---|
| Name | `Authorization` |
| Value | `Bearer ` followed by your API key |

Name the credential **MADIAD Hub**. Create the key in your dashboard, under API keys.

> Use a separate key for n8n. If it ever leaks you revoke that one key and nothing else breaks.

### 2.2 Import the workflows

**Workflows › Import from File**, pick a JSON file. For each one:

1. Open every **Google Sheets** node and select your copy of the sheet.
2. Open the node that calls the API and select the **MADIAD Hub** credential.
3. Turn the workflow on.

**Import `wf-01` and `wf-03` at minimum.**

---

## Step 3, the faster way: install the community node

Instead of wiring HTTP Request nodes, install the MADIAD Hub node. It gives you a **profile
dropdown** loaded from your own account and a **Test button** that tells you the key works before
you run anything.

### On self-hosted n8n

1. **Settings › Community nodes › Install a community node**
2. Enter the package name: `n8n-nodes-madiad-hub`
3. Tick the risk acknowledgement and press **Install**
4. Wait for n8n to restart, then search for **MADIAD Hub** in the node panel.

Or from the command line, inside `~/.n8n`:

```bash
npm install n8n-nodes-madiad-hub
```

then restart n8n.

### On n8n Cloud

n8n Cloud only installs nodes n8n has verified. This package is not verified, so **on Cloud use the
JSON workflows above** — they use only the built-in HTTP Request node and need nothing installed.

### Using the node

1. Add a **MADIAD Hub** node.
2. Create a **MADIAD Hub API** credential, paste the key, press **Test**. Green means the key works.
3. Choose a **Resource** (`Post` / `Profile` / `Usage`) and an **Operation**.
4. **Profile** is a dropdown, not a field to paste an ID into.

The node and the workflows share one API key; running both is fine.

---

## Step 4, day to day

Write from **row 3**. Row 1 is the header, row 2 explains each column. Do not delete either.

| Column | What you put in it |
|---|---|
| `Action` | `Publish now` · `Schedule` · `Retry` · `Unpublish` |
| `Channels` | pick one, **or type several separated by commas** |
| `Title` | required by YouTube, Reddit and Pinterest |
| `Caption` | the body of the post |
| `Media` | image or video URL starting with `https://`. One link per line for several images |
| `Publish At` | only with `Schedule`. Format `2026-09-10 08:30` |
| `First Comment` | optional, posted straight under the post |

Everything else is written by the workflow. Leave it alone.

### The states a row moves through

```
(empty)  ──(you set an Action)──>  Publishing ──┬──> Published
                                                └──> Error
```

`Publishing` means it has been sent and the platform has it. `Published` is written only once the
platform has **actually** published, not when the request was accepted.

A failed row explains itself in `Error`. Fix it, clear `Status`, set `Action` again.

---

## Step 5, publishing without waiting for the sweep

`wf-01` sweeps on whatever interval you set in its schedule node. To publish sooner than that, add
the Apps Script from the pack. It gives you **two ways**, one mechanism, one setup:

**Setup (once):**

1. Import and activate `wf-05-publish-now.json`. Open the webhook node and copy the **Production URL**.
2. In the sheet: **Extensions › Apps Script**, paste all of `Gate.gs` from the pack.
3. **Project Settings › Script Properties**, add `WEBHOOK_URL` with the URL you copied.
4. Reload the sheet. A **MADIAD Hub** menu appears next to Help.
5. Run **MADIAD Hub › Test n8n connection**. Approve the permission prompt. It pings the webhook
   **without publishing anything**, so you can prove the URL is live before trusting it.

**Way 1, by hand (recommended).** Select the rows you want, then
**MADIAD Hub › Publish selected rows now**. Selecting several rows asks for confirmation first.
This path does not require the `Action` cell to say `Publish now`: clicking the menu item is the
instruction.

**Way 2, fire on edit.** For the automatic path, add one more step:

6. **Triggers › Add Trigger**: function `onEditInstallable`, event *From spreadsheet › On edit*.
   From then on, setting `Action` to `Publish now` fires it by itself.

> Step 6 must be an **installable** trigger. Google's simple `onEdit` is not allowed to reach the
> internet, so getting this wrong makes it **do nothing, silently, with no error anywhere**. Way 1
> is immune to this, because the menu works without any trigger.

---

## The pack is updated regularly

We update this pack on a regular basis: new channels, new API features, and fixes for whatever
users report getting stuck on.

New versions always live at the **same address**: <https://hub.madiad.com/n8n-templates>. Download
again and re-import over the old workflows in n8n; you do not rebuild anything.

One thing to know before re-importing: **your sheet is not touched**. An update only replaces the
workflow files. If a release does rename a column, this section will say so explicitly, because a
renamed column is the one change that makes a workflow lose track of your existing data.

## When something does not work

| What you see | Usual cause |
|---|---|
| Runs fine, publishes nothing | `Status` is not empty, or `Action` does not match exactly |
| `The Channels cell matches no platform` | A typo in a channel name. Pick from the list instead |
| `Media links must start with https://` | A Drive sharing link. You need a direct file URL |
| A row stuck on `Publishing` | `wf-03` is not running |
| Posted to the wrong Facebook Page | Re-pin the Page in the dashboard, under Connections |
| Nothing happens when you edit the sheet | The trigger is a simple `onEdit` instead of an installable one |
| `401` or `403` | Wrong API key, or the plan has expired |
| The MADIAD Hub node does not appear | n8n has not restarted, or you are on n8n Cloud |

Full API documentation: https://docs.madiad.com