> ## Documentation Index
> Fetch the complete documentation index at: https://help.fanaura.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Journey tools

> Parameters and responses for the 12 tools that create, edit, check, publish, and list journeys.

A journey is one link with one job: someone comments or DMs your keyword, Fanaura sends your link, can ask for a contact detail, and sends them to your page. These tools build and manage journeys.

<Note>
  Every tool that takes `journey_id` expects the UUID returned by `start_journey`, `create_journey`, or `list_journeys`.
</Note>

## Create and publish in one call

### Create journey

`fanaura.create_journey` builds a journey from a destination URL and publishes it in the same call unless `publish` is false. Fanaura fills in anything you left out: the name, the keyword, up to ten public comment replies, automatic contact capture, and every connected Instagram, text, and email trigger. It returns `live`, a recap of those settings, and `public_url` when the journey is live. The journey is saved as a draft, with the reason in `blockers`, when Instagram is not connected, the keyword is live on another journey, the public name is not claimed, or membership is inactive. An invalid URL creates nothing. A repeat with the same `idempotency_key` returns the first result and creates nothing new.

<ParamField body="destination_url" type="string" required>
  The full public `https://` page people land on, such as a song, an episode, a booking page, or a download.
</ParamField>

<ParamField body="keyword" type="string">
  One word of up to 32 letters or numbers. Saved in capitals. When omitted, Fanaura suggests one from the link and falls back to `LINK`.
</ParamField>

<ParamField body="name" type="string">
  The journey name. When omitted, Fanaura names it from the page. The public link is built from the name.
</ParamField>

<ParamField body="public_comments" type="string[]">
  Public reply lines posted under the comment. Up to 10 are kept. Fanaura writes the rest so there are always up to 10 versions.
</ParamField>

<ParamField body="private_message" type="string">
  The DM text that comes with the link. When omitted, Fanaura uses its default greeting.
</ParamField>

<ParamField body="followers_only" type="boolean" default="false">
  Send the link only to people who follow the account on Instagram.
</ParamField>

<ParamField body="allow_reentry" type="boolean" default="true">
  Send the link again when the same person comments the keyword again.
</ParamField>

<ParamField body="publish" type="boolean" default="true">
  Pass `false` only when the user asks for a draft.
</ParamField>

<ParamField body="idempotency_key" type="string">
  Any unique string. A retry with the same key returns the first result instead of building a second journey.
</ParamField>

<ResponseField name="live" type="boolean" required>
  `true` when the journey is published.
</ResponseField>

<ResponseField name="message" type="string" required>
  "Journey is live at" plus the public link, or the reason it stayed a draft.
</ResponseField>

<ResponseField name="recap" type="object">
  What Fanaura chose: `name`, `keyword`, `destination_url`, `public_url`, `share_url`, `triggers`, `followers_only`, `capture`, `public_comment_replies`, `sample_public_reply`, and `repeat_visitors_get_link_again`.
</ResponseField>

<ResponseField name="structuredContent" type="object">
  <Expandable title="properties">
    <ResponseField name="journey" type="object">The full saved journey, including the draft and revision.</ResponseField>
    <ResponseField name="blockers" type="object[]">Each item has a `code` and a `message`. Empty when the journey is live.</ResponseField>
    <ResponseField name="public_url" type="string">The public link, such as `fanaura.me/yourname/free-guide`.</ResponseField>
    <ResponseField name="share_url" type="string">The short share link, or `null`.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```json Request theme={null}
  {
    "name": "fanaura.create_journey",
    "arguments": {
      "destination_url": "https://example.com/guide",
      "keyword": "GUIDE"
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Live theme={null}
  {
    "success": true,
    "live": true,
    "message": "Journey is live at https://fanaura.me/yourname/free-guide.",
    "recap": {
      "name": "Free Guide",
      "keyword": "GUIDE",
      "destination_url": "https://example.com/guide",
      "public_url": "https://fanaura.me/yourname/free-guide",
      "triggers": ["Instagram comments", "Instagram DMs"],
      "followers_only": false,
      "capture": "Automatic: asks one missing contact detail per visit (phone, then email, then name)",
      "public_comment_replies": 10,
      "sample_public_reply": "Sent it to your DMs",
      "repeat_visitors_get_link_again": true
    },
    "iphone_deep_link": "fanaura://journeys/2f6c...",
    "web_builder_url": "https://app.fanaura.com/automations/2f6c..."
  }
  ```

  ```json Draft theme={null}
  {
    "success": true,
    "live": false,
    "message": "Connect Instagram before this keyword can go live.",
    "structuredContent": {
      "blockers": [
        { "code": "instagram_not_connected", "message": "Connect Instagram before this keyword can go live." }
      ]
    }
  }
  ```
</ResponseExample>

#### Blocker codes

| Code | Meaning |
| - | - |
| `invalid_destination` | The link is not a full public URL, or the keyword is not allowed. Nothing is saved. |
| `instagram_not_connected` | No ready Instagram connection. Saved as a draft. |
| `keyword_taken` | Another journey uses this keyword. The message names it. Saved as a draft. |
| `membership_inactive` | No active membership. Saved as a draft. |
| `name_not_claimed` | The public name is not claimed. Saved as a draft. |
| `publish_failed` | Publishing failed for another reason. Saved as a draft. |

## Build step by step

### Start journey draft

`fanaura.start_journey` creates a new unpublished draft when you pass a destination URL, and returns its `journey_id` and suggested keywords. Without a URL it saves nothing and asks for the link. It does not publish, send messages, or buy a texting number. It is not marked destructive.

<ParamField body="destination_url" type="string">
  Optional page to set now.
</ParamField>

<ParamField body="name" type="string">
  Optional journey name.
</ParamField>

<ResponseField name="journey_draft" type="object">
  The new draft, including its `id`.
</ResponseField>

### Set destination URL

`fanaura.set_destination_url` saves the page people land on. It requires a full public website URL and returns an error for anything else. A live journey keeps its current destination until the draft is published again.

<ParamField body="journey_id" type="string" required>Journey UUID.</ParamField>
<ParamField body="url" type="string" required>Full public `https://` address.</ParamField>

### Set keyword

`fanaura.set_instagram_keyword` sets the word people comment or DM. It never triggers on every comment.

<ParamField body="journey_id" type="string" required>Journey UUID.</ParamField>

<ParamField body="keyword" type="string" required>
  One word, no spaces, up to 32 letters or numbers. Reserved: STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, HELP, INFO, START, YES, NO, and UNSTOP.
</ParamField>

### Set public comment replies

`fanaura.set_public_replies` replaces the reply list on the draft with up to ten versions, and each matching comment gets one of them. It sends no private messages and no blasts. A live journey keeps its current replies until the draft is published again.

<ParamField body="journey_id" type="string" required>Journey UUID.</ParamField>
<ParamField body="replies" type="string[]" required>Up to 10 reply lines.</ParamField>

### Set contact capture

`fanaura.set_capture` adds an email field or a phone field to the journey draft. It does not export, share, or sell contacts.

<ParamField body="journey_id" type="string" required>Journey UUID.</ParamField>

<ParamField body="mode" type="'email' | 'phone' | 'either'" required>
  `email` adds an email field. `phone` adds a phone field. `either` currently adds only an email field.
</ParamField>

### Followers only on Instagram

`fanaura.set_followers_only` sends the link only to people who follow the account.

<ParamField body="journey_id" type="string" required>Journey UUID.</ParamField>
<ParamField body="followers_only" type="boolean" default="true">`true` to require a follow. `false` to send to anyone.</ParamField>

<Info>
  Each `set_` tool returns the updated `journey_draft`. On a live journey, the change waits in the draft until `publish_journey` runs.
</Info>

## Check and publish

### Check destination link

`fanaura.check_link` answers yes or no for a destination. Read only.

<ParamField body="journey_id" type="string" required>Journey UUID.</ParamField>
<ParamField body="url" type="string">Optional URL to check instead of the saved one.</ParamField>

### Validate publish checklist

`fanaura.validate_publish` lists what is missing before publish. It never publishes.

<ParamField body="journey_id" type="string" required>Journey UUID.</ParamField>

### Publish journey

`fanaura.publish_journey` reserves the public link from the journey name and publishes the current draft. It returns `public_url`, `share_url`, and a recap of the live settings. When the live version already matches the draft, it changes nothing and says so. It fails when the checklist is incomplete, the public name is not claimed, or the draft changed after `expected_revision`.

<ParamField body="journey_id" type="string" required>Journey UUID.</ParamField>

<ParamField body="user_confirmed" type="boolean" required>
  Must be `true`. This records that you asked for the journey to go live. Publishing is refused when it is false or missing.
</ParamField>

<ParamField body="expected_revision" type="number">
  Optional. The revision from the latest draft. Prevents publishing over a newer change made elsewhere.
</ParamField>

<ResponseField name="message" type="string">
  "Journey is live at" plus the link, or "This journey is already live." when nothing changed.
</ResponseField>

<ResponseField name="data" type="object">`journey`, `public_url`, and `share_url`.</ResponseField>
<ResponseField name="recap" type="object">The same recap as `create_journey`.</ResponseField>

<Warning>
  On failure, `error` reads `Field <name>: <what to fix>` and `field` names the input. Fields include `user_confirmed`, `destination_url`, `keyword`, `replies`, `name`, `slug`, `expected_revision`, and `journey_id`.
</Warning>

## Read journeys

### List journeys

`fanaura.list_journeys` answers what is live, what keyword a journey uses, and where it sends people.

<ParamField body="archived" type="boolean" default="false">`true` to list archived journeys.</ParamField>
<ParamField body="query" type="string">Search by name, keyword, or destination.</ParamField>

### Get journey

`fanaura.get_journey` returns one draft or live journey.

<ParamField body="journey_id" type="string" required>Journey UUID.</ParamField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.