# Scripts and script matching (/docs/brands/videos/scripts)

Bring in the scripts your creators film from, and let Bloss find which script each post follows and tag its set.

A script is a brief your creators film from: a code, a title, the hooks a video can open with and what's said after. Bring your scripts in from Notion, Google Docs or an AI chat. Bloss then reads what each post says, works out which script it follows, and puts that script's tag on the post's set. You can then filter, compare and report by script like any other tag.

Brand admins see Scripts in the admin console. Creators don't see scripts or which one their posts were matched to.

<OpenInBloss to="admin/scripts">Open Scripts</OpenInBloss>

<Screenshot name="brands/scripts-page" alt={"The Scripts page with six scripts from Notion, Google Docs and pasted text, the last match and the brand words"} />

## How it works [#how-it-works]

<Steps>

<Step>

### Add your scripts [#add-your-scripts]

Paste links to your Notion pages or Google Docs, paste scripts from ChatGPT or Claude, or let your own AI add them. Bloss keeps a copy of each document and reads its code, title, hooks and script.

</Step>

<Step>

### Bloss matches your posts [#bloss-matches-your-posts]

Every night, and whenever you click **Match now**, Bloss reads what each recent post says and scores it against your active scripts. A clear match gets the script and its tag.

</Step>

<Step>

### You settle the close calls [#you-settle-the-close-calls]

Posts that could follow two scripts wait in **Match history** for you to pick one. Going through them takes a few key presses each.

</Step>

<Step>

### Report by script [#report-by-script]

Each script has its own tag, so the Video Vault, tag analytics and reports can show you which scripts get the views.

</Step>

</Steps>

## Add scripts [#add-scripts]

On the Scripts page, click **Add scripts**. You can bring in up to 25 documents at once.

### From Notion or Google Docs [#from-notion-or-google-docs]

<Steps>

<Step>

Make each script readable by link:

- **Notion:** open the page, click **Share**, then **Publish**, and publish it.
- **Google Docs:** click **Share** and set **General access** to **Anyone with the link**.

</Step>

<Step>

In **Add scripts**, choose **Notion or Google Docs** and paste the links, one per line. You can mix Notion pages and Google Docs.

</Step>

<Step>

Click **Read docs**. Bloss shows what each document becomes: its code and title, how many hooks it found and how much script, and whether it's new or updates one of your scripts. A document Bloss can't read says why.

</Step>

<Step>

Click **Add scripts**. Each script keeps a copy of its document, which you see when you open the script.

</Step>

</Steps>

Bloss reads the layout script documents usually have:

| In the document                                                        | Becomes                                     |
| ---------------------------------------------------------------------- | ------------------------------------------- |
| A title like **(3A) I'm embarrassed to say**                           | Code **3A**, title "I'm embarrassed to say" |
| **HOOK option 1**, **Hook 2**…                                         | One hook each                               |
| **text hook** or a line starting **On screen:**                        | What's on screen                            |
| **verbal hook**, **script** or a line starting **Said:** under a hook  | What's said                                 |
| A **Script** or **Text** section of its own                            | The body                                    |
| **Demo Direction**, **reference video** and the rest                   | Shown with the script, not matched          |

- **Updating:** a document whose code matches one of your scripts updates that script's title, hooks and body. Its tag and **Active** switch stay as they are. Other documents become new scripts, each with a tag named after it, like **S7 · Post-workout skin reset**. A document without a code in its title gets the next free code.
- **Changed a document?** Click **Refresh docs** above your scripts to read every linked document again, or **Refresh** on one script.
- **Images in Google Docs** stay in the doc: open it to see them. Images on Notion pages show with the script.

### From ChatGPT or Claude [#from-chatgpt-or-claude]

If you write scripts with an AI chat, paste its answer straight in.

<Steps>

<Step>

In **Add scripts**, choose **Paste text** and click **Copy the prompt**. It asks your chat for scripts in a format Bloss reads.

</Step>

<Step>

Paste the prompt in your chat with what you want scripts about, then copy its answer and paste it into **Add scripts**.

</Step>

<Step>

Click **Read scripts**, check what each one becomes, and click **Add scripts**.

</Step>

</Steps>

<Screenshot name="brands/scripts-add-paste" alt={"Add scripts after Read scripts: a new S7 and an update to S2, each with its hooks and script length"} />

You can paste several scripts at once: separate them with a line of `---`, or give each its own heading with a code. The format looks like this:

```md
# (S5) I paid $40 in late fees

## Hook 1
On screen: I paid $40 in late fees last month
Said: I paid forty dollars in late fees last month

## Script
I just open the app and turn on bill reminders.
Comment "bills" and I'll send you the link.
```

### With your AI [#with-your-ai]

On the **Scale** plan you can connect Bloss to Claude, ChatGPT, Cursor or another app that supports MCP, and let it add and update scripts itself. Click **Use your AI** on the Scripts page for the server URL and examples of what to ask, and see [AI agents (MCP)](/docs/developers/mcp) for each app's setup. Give it the permission **Create, edit and delete tags and scripts, tag or untag videos and sets, and match posts to scripts**.

<Screenshot name="brands/scripts-use-your-ai" alt={"The Use your AI dialog with the server URL, the setup steps and example requests"} />

It can then add scripts it writes or that you link, update them, start a match and settle posts waiting for a pick. Ask it to show you a preview first and it will, before it adds anything.

### Write one here [#write-one-here]

Click **Add scripts**, then **Write one instead**. Fill in the form, or paste a Notion or Google Docs link into **Fill from a doc** to fill it for you.

| Field      | What it's for                                                                                    |
| ---------- | ------------------------------------------------------------------------------------------------ |
| **Code**   | A short label, like `S1`. Unique within your brand.                                              |
| **Title**  | What the video is about. It also counts as a hook.                                               |
| **Tag**    | The tag matched sets get. Pick one of your tags or type a new name to create it.                 |
| **Hooks**  | How a video can open: the text **on screen** and the line that's **said**. Add one row per hook. |
| **Body**   | What the video says after the hook, in Markdown.                                                 |
| **Active** | Match posts against this script. A paused script keeps the posts it already has.                 |

Click **Create script**. The next match scores your posts against it.

### Write hooks the way creators open [#write-hooks-the-way-creators-open]

The first 30 words a post says are compared with the title and each hook, and that carries most of the score. The body is compared with everything the post says.

- Write each hook the way a creator would say it, not as a description.
- For alternatives within one hook, put **or** on its own line between them. Each alternative is matched on its own.
- Text in square brackets, like `[amount]`, is ignored.
- Lines every script shares, like "Use case: …", count for nothing.

## View a script [#view-a-script]

Click a script to open it in a side panel. With more than a few scripts, search by code, title or hook, or show only **Active** or **Paused** ones.

<Screenshot name="brands/script-drawer" alt={"A script from Notion open in the side panel: its format, hooks and script"} />

- A script from a document shows that document: its sections, screenshots and reference videos. **What Bloss matches** shows the hooks and body that posts are compared with. The header says how many posts follow the script.
- **Edit** the script, **Refresh** it from its document after you change the document, or open the document.
- Press <kbd>↑</kbd> and <kbd>↓</kbd> (or <kbd>K</kbd> and <kbd>J</kbd>) to move between scripts.
- The page's address links to the open script, so you can share it with your team.

## Set your brand words [#set-your-brand-words]

Brand words are what every campaign post shows or says: your brand's name, its handle, its site. Click **Edit** on the **Brand words** card and add one per line. Capital letters, spaces, dots and `#` don't matter, and a word needs at least 4 letters or digits to count.

A post that never names a brand word (in its caption or in what it says) and isn't a very clear match is treated as a warmup or personal post: it gets no script and is never flagged.

## When matching runs [#when-matching-runs]

Matching never runs during a sync. It runs:

- when you click **Match now** on the Scripts page or in Match history, and
- every night, after the day's sync. Turn this off with **Match every night** in the **Brand words** dialog.

Each match looks at posts from the last 30 days and at posts in payout cycles that aren't paid yet. You can leave the page while it runs.

## How a post gets its script [#how-a-post-gets-its-script]

Bloss reads each post's transcript once and keeps it. It scores the post against every active script, then compares the best script with the runner-up. That ratio is the **lead**: 2× means the best script scored twice as well as the next one.

| What Bloss finds                                                            | What happens                        | Shows as            |
| --------------------------------------------------------------------------- | ----------------------------------- | ------------------- |
| You picked the post's script                                                | Never changed by a match            | **Set by a person** |
| The post says too little to read (for example music with text on screen)    | Left alone                          | **Nothing to read** |
| No brand word anywhere, and a lead under 2×                                 | No script, never flagged            | **Not campaign**    |
| The best script is the one the post already has                             | Kept                                | **Kept**            |
| A lead of 1.5× or more                                                      | The best script and its tag are set | **Set**             |
| A lead under 1.5×, and the post's current script is within 1.3× of the best | Kept                                | **Kept**            |
| Anything else                                                               | Waits for you to pick               | **Needs a pick**    |

Before a post waits for you, an AI may take a second look at it, with its transcript and thumbnail. It sets a script only when it's sure; otherwise the post waits for you as before. It never marks a post as not a campaign video.

The videos of one set are the same video on different platforms, so they share one script. A post that can't be read takes the script of the others in its set.

Bloss reads only what posts say. Videos that only show text on screen come back as **Nothing to read** until you pick their script.

## Match history [#match-history]

Click **Match history** on the Scripts page. It shows:

- **Runs**: each match, who started it, and how many posts were checked, set, kept or left for you.
- **Posts**: each post's script, its lead, its status and where the answer came from. Filter by **Needs a pick**, **Set automatically**, **Set by a person**, **Skipped** or **All**.

<OpenInBloss to="admin/scripts/history">Open Match history</OpenInBloss>

<Screenshot name="brands/match-history" alt={"Match history with the last runs and the posts that need a pick"} />

### Review posts [#review-posts]

Click **Review** above the posts, or a post's title, to go through them one at a time. Each post shows:

- **What it says**, with its first words marked: those are compared with the hooks.
- Its caption, and a link to watch it.
- The best guesses, each with its closest hook.

<Screenshot name="brands/script-review" alt={"Reviewing a post that needs a pick: what it says, its caption and the best guesses with their closest hooks"} />

| Key                                      | Does                                                                      |
| ---------------------------------------- | ------------------------------------------------------------------------- |
| <kbd>1</kbd>, <kbd>2</kbd>, <kbd>3</kbd> | Pick that script.                                                         |
| <kbd>N</kbd>                             | **Not a campaign video**: the post and the rest of its set get no script. |
| <kbd>L</kbd>                             | **Leave**: keep the post as it is.                                        |
| <kbd>→</kbd>                             | Skip to the next post. <kbd>←</kbd> goes back.                            |

After an answer, the next post opens. You can also pick from the list: click a suggested script, or choose any script from the menu.

Your answer applies to the whole set and no match changes it. To let matching decide again, click **Hand back** (under **Set by a person**). The whole set then waits for the next match, and its script tag comes off until then.

## Script tags [#script-tags]

- A set carries the tag of its script. When its script changes, the old script's tag comes off.
- Changing a script's tag moves its posts to the new tag.
- Deleting a script doesn't remove its tag from posts. Delete the tag on the **Tags** page if you want it gone.
- Tags that don't belong to a script are never touched by matching.

Script tags don't change pay.

## See a post's script in the Video Vault [#see-a-posts-script-in-the-video-vault]

Open a video in the [Video Vault](/docs/brands/videos/video-vault). When it follows a script, **Details** shows **Script** under its tags: the script's code and title, and how it was decided (matched from what the post says, by the AI's second look, the same as the rest of its set, or set by a person). Click it to open Match history. Posts waiting for a pick, skipped or never matched show no script.

<Screenshot name="brands/vault-script" alt={"A video open in the Video Vault, with its script under its tags in Details"} />

## Common questions [#common-questions]

<Accordions>

<Accordion title="A post got the wrong script">

Open **Match history**, find the post (filter by **Set automatically**) and choose the right script from its menu. Your pick applies to the whole set, and no later match changes it. If many posts land on the wrong script, the hooks are probably too alike: rewrite them the way creators actually open their videos.

</Accordion>

<Accordion title="A post shows Nothing to read">

The post has no speech Bloss can read, for example music with text on screen. Pick its script in **Match history**. Other posts in the same set take its script too.

</Accordion>

<Accordion title="I edited a script. Are posts matched again?">

Yes, at the next match: click **Match now**, or wait for the nightly one. Posts you set by hand stay as they are.

</Accordion>

<Accordion title="Bloss can't read my Notion page or Google Doc">

Notion pages must be published to the web, and Google Docs need **Anyone with the link** access. Private documents can't be read. You can also copy the text and paste it under **Paste text**.

</Accordion>

<Accordion title="Do scripts change what creators are paid?">

No. Scripts and their tags only describe posts. Pay follows your pay rules.

</Accordion>

</Accordions>

## Related [#related]

- [Tags and tag analytics](/docs/brands/videos/tags)
- [Video Vault](/docs/brands/videos/video-vault)
- [How sets work](/docs/brands/videos/how-sets-work)
- [Syncing videos](/docs/brands/videos/syncing)
- [AI agents (MCP)](/docs/developers/mcp)
