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

# Connect An AI Helper

> A simple setup guide for connecting an AI app to DealDash safely.

This page is for people who want an AI app to help with DealDash without learning the technical setup first.

Use it when you want Hermes, ChatGPT, Claude, Codex, OpenClaw, or another tool-capable AI app to help with screenshots, LinkShot view logs, message templates, deals, links, or summaries.

## Fastest Path

1. Open DealDash.
2. Go to **Tools > AI Agent Setup**.
3. Click **Copy AI instruction**.
4. Paste the instruction into your AI app.
5. Open the DealDash approval link the AI sends back.
6. Let the approved agent store the scoped token in its own secure runtime.
7. Ask for read-only data first.

You do not need to understand MCP to start. The AI app will use MCP or the direct HTTPS fallback in the background.

## What Should Happen

1. The AI asks DealDash for a login approval link.
2. You open the link, sign in, and approve the persistent connection.
3. The AI stores the scoped token outside chat so it can keep using DealDash tools.
4. The AI checks your data before changing anything.
5. It reports what it can read and the safest next step.

Normal setup does not require you to paste passwords, API keys, service secrets, internal IDs, database URLs, or deploy settings into chat.

## Hermes Preferred Setup

Hermes is the preferred long-running DealDash operator agent when it is available. Treat OpenClaw as an optional WhatsApp/Telegram adapter on top of the same DealDash Agent Bridge, not as the primary DealDash identity.

1. Prefer the `dealdash-agent-bridge` MCP server. If the active Hermes profile cannot load MCP, use the direct HTTPS fallback.
2. For direct HTTPS login, start auth with `actorId="hermes-agent"` and `channel="hermes"` so Settings, logs, and future learning can identify the host cleanly.
3. Store the approved DealDash token only in the Hermes secure profile or secret store. Never save it in chat, profile prose, memory notes, screenshots, or GBrain.
4. At the start of each Hermes session, refresh `GET /api/settings/agent-connection` and `GET /api/agent/schema` or MCP `tools/list` before relying on old instructions.
5. Let Hermes self-improve only from verified, source-labeled evidence: DealDash tool output, GBrain pages with source labels, or explicit operator correction. Do not graduate guesses, private messages, raw payment payloads, device codes, or tokens into memory.
6. Before any write, report which account/data it can read, which tool it plans to use, and whether the action is Tier 1, Tier 2, or delete-gated.

## Ready Instruction

Copy this from the DealDash dashboard so the links stay current.

```text theme={null}
You are my DealDash agent.

Connect to DealDash, read my data first, then help with screenshots, LinkShot view checks, templates, deals, contacts, tasks, links, suggestions, and memory.

Do not ask me for my DealDash password, API keys, service secrets, internal IDs, database URLs, or deploy settings.

Connect:
1. If you have the DealDash MCP tool agent_auth_start, use it.
2. If MCP is unavailable but HTTPS requests are available, POST https://dealdash.tech/api/agent/auth/start with {"actorId":"ai-agent","channel":"agent-setup"}.
3. If you are Hermes and you use direct HTTPS, use actorId="hermes-agent" and channel="hermes".
4. Send me only the DealDash approval link. Keep the device code, token, and private response fields out of chat.
5. After I approve, store the scoped DealDash token only in your secure agent runtime so this connection can keep working across future tool calls. Do not print the token in chat.
6. Check /api/settings/agent-connection or the AI Agent Connection page for active connections, expiry, tool families, and write policy. Use the revoke control there if I ask you to disconnect.
7. At the start of a new session, refresh /api/settings/agent-connection and /api/agent/schema or MCP tools/list before relying on old tool instructions.
8. If this AI app has neither MCP nor HTTPS tool access, say it cannot connect to DealDash tools from this environment.

Start read-only:
1. Run context.search with scope=mine-and-shared.
2. Run templates.latest_story_message. If empty, run templates.list_message with tag=story.
3. Run screenshots.list_latest.
4. Run deals.view_logs.
5. Run deals.due_views.

When I ask for the latest story or message template:
- Use templates.latest_story_message first. Do not guess from docs, browser history, or chat memory.
- If no latest story template appears, tell me what template data you can see and ask which tag or template name to search next.

For LinkShot view checks:
- Use deals.bulk_add_view_checks or POST /api/agent/deals/bulk-import/process.
- Do not use generic deal create/update for view-check imports.
- Do not ask for Telegram approval for LinkShot view-check imports unless DealDash itself says approval is required.
- If bulk import returns needsPromoCode, ask for the missing promo code plus any available deal name, price, views target, promo link, contact, or notes; then retry with nextAction.retryParams.

Safety:
- Use the DealDash write policy from connection status. Non-delete writes may run when the policy allows them. Always ask before deleting anything.
- If approval is required, explain the change and wait before creating, updating, sharing, sending messages, payments, or saving memory.

Self-improvement:
- Save only durable, source-labeled operator preferences and workflow corrections after verified DealDash tool output or explicit user correction.
- Never save DealDash tokens, device codes, service secrets, raw private messages, raw payment payloads, database URLs, or unverified guesses into memory.
- If tools or schemas change, update your local procedure only after verifying /api/agent/schema or MCP tools/list.

Report back with: what connected, which data you can read, the latest story template if found, and the safest next step.
```

## Good First Requests

* "Show my latest story message template."
* "Show my latest screenshots."
* "Show my LinkShot View Logs for this week."
* "Which posts still need views checked?"
* "Find the deal for this promo code."
* "Shorten this link for me: [https://example.com](https://example.com)"
* "Upload this image and give me the short link."

Start with one of these so you can confirm the AI sees the right account, templates, screenshots, and LinkShot records before it changes anything.

## If The Bot Gets Confused

| Problem                                      | What To Say                                                                                                                            |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| It cannot find the latest story template     | "Use `templates.latest_story_message` first, then `templates.list_message` with `tag=story`. Do not search docs or guess from memory." |
| It asks for your password or keys            | "Create a DealDash approval link instead. I will not paste passwords, API keys, service secrets, or internal IDs in chat."             |
| It says MCP is missing                       | "Use the direct HTTPS fallback if you can make web requests. Missing MCP is only a blocker if this AI app has no tools."               |
| It tries to create generic deals for checks  | "Use `deals.bulk_add_view_checks` or `POST /api/agent/deals/bulk-import/process` for LinkShot view-check imports."                     |
| The approval link was already claimed        | "Create a new DealDash approval link, or revoke the old connection from Settings if I no longer trust that host."                      |
| It cannot see screenshots or LinkShot logs   | Check the right DealDash account, date filters, LinkShot upload status, and whether shared/team records should be included.            |
| It says a write is blocked                   | That is expected when approval is required or the action is a delete. LinkShot bulk view-check imports should not ask for approval.    |
| The AI app does not support MCP or web tools | Use Codex, Claude Code, OpenClaw, or another tool-capable agent. A chat-only bot cannot connect to DealDash by itself.                 |

## Optional Terminal Examples

If your AI agent uses a terminal and needs install/example files, it may run this safe command:

```bash theme={null}
git clone https://github.com/djasha/dealdash-agent-kit.git
cd dealdash-agent-kit
```

That private setup repo contains instructions and placeholder examples only. It is not required when the agent already has MCP tools or HTTPS access, and it does not contain passwords, keys, or private DealDash data.

## Image Uploads

DealDash accepts common web images: PNG, JPG/JPEG, WebP, GIF, AVIF, and BMP up to 40MB by default.

If an image from WhatsApp, Telegram, Slack, Mattermost, OpenClaw, Hermes, Codex, or Claude fails, ask the agent to convert it to PNG, JPG, or WebP and try again. SVG, HEIC, and TIFF are intentionally not accepted by default because they can be unsafe or unreliable in browser previews.

## What Needs Approval

Ask the agent to explain the change before approving any of these:

* creating or changing deals
* creating, changing, or deleting payments
* deleting screenshots or links
* changing team sharing or visibility

Adding dated LinkShot post/video links for view checking is a logged low-risk write. The agent should use `deals.bulk_add_view_checks` directly. If DealDash cannot match a group, it should ask for the missing promo code plus any available deal name, price, views target, promo link, contact, or notes, then retry with the returned `nextAction.retryParams`.

## For Agents And Developers

These pages are tagged for agents that need exact names, routes, and tool contracts:

* [Agent-optimized bridge reference](../internal/dealdash-agent-bridge-plugin.mdx)
* [API surface](../backend/api-surface.mdx)
* [Task routing](task-routing.mdx)
* [Private DealDash Agent Kit](https://github.com/djasha/dealdash-agent-kit) for authorized install/examples only

Approved agent tokens are long-lived, renewable, and revocable from **Settings > AI Agent Connection**. The default token window is 30 days and the server caps configured token TTL at 365 days. DealDash can be configured so non-delete writes do not need approval each time. Deletes always require explicit confirmation. Start read-only, let the agent look first, and only allow write mode when you trust the active agent connection.