Skip to content

Commit ded5c83

Browse files
recoup-coding-agentRecoup CTO AgentPaperclip-Paperclip
authored
docs: Recoup Content Agent guide and API reference (#78)
* docs: add Recoup Content Agent guide and API reference - Guide page covering @mention syntax, data flow, setup, and troubleshooting - OpenAPI spec entries for POST /api/content-agent/{platform} and POST /api/content-agent/callback - API reference pages for webhook and callback endpoints - Navigation updated with Agents group in Guides tab and Content Agent group in API reference Co-Authored-By: Paperclip <noreply@paperclip.ing> * docs: fix PR feedback — link callback endpoint and add RECOUP_API_KEY - Link POST /api/content-agent/callback to its API reference page in both the data flow section and endpoints table - Add missing RECOUP_API_KEY to environment variables table Co-Authored-By: Paperclip <noreply@paperclip.ing> --------- Co-authored-by: Recoup CTO Agent <cto@recoupable.com> Co-authored-by: Paperclip <noreply@paperclip.ing>
1 parent 548d60e commit ded5c83

File tree

5 files changed

+290
-0
lines changed

5 files changed

+290
-0
lines changed

‎api-reference/content-agent/callback.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: 'Task Callback'
3+
openapi: 'POST /api/content-agent/callback'
4+
---

‎api-reference/content-agent/webhook.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: 'Slack Webhook'
3+
openapi: 'POST /api/content-agent/{platform}'
4+
---

‎api-reference/openapi.json‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4500,6 +4500,146 @@
45004500
}
45014501
}
45024502
}
4503+
},
4504+
"/api/content-agent/{platform}": {
4505+
"post": {
4506+
"description": "Webhook endpoint for the Recoup Content Agent Slack bot. Receives @mention events from Slack and triggers content generation for the mentioned artist. The bot parses the mention text for `<artist_account_id> [template] [batch=N] [lipsync]`, validates the artist, calls POST /api/content/create, and starts a background polling task that reports results back to the Slack thread.\n\nFor Slack, also handles `url_verification` challenges during app setup.",
4507+
"parameters": [
4508+
{
4509+
"name": "platform",
4510+
"in": "path",
4511+
"description": "Chat platform identifier. Currently supports `slack`.",
4512+
"required": true,
4513+
"schema": {
4514+
"type": "string",
4515+
"enum": ["slack"]
4516+
}
4517+
}
4518+
],
4519+
"requestBody": {
4520+
"description": "Slack Events API payload (app_mention event or url_verification challenge)",
4521+
"required": true,
4522+
"content": {
4523+
"application/json": {
4524+
"schema": {
4525+
"type": "object",
4526+
"description": "Slack Events API envelope — the shape depends on the event type"
4527+
}
4528+
}
4529+
}
4530+
},
4531+
"responses": {
4532+
"200": {
4533+
"description": "Event processed successfully",
4534+
"content": {
4535+
"application/json": {
4536+
"schema": {
4537+
"type": "object",
4538+
"properties": {
4539+
"ok": {
4540+
"type": "boolean"
4541+
}
4542+
}
4543+
}
4544+
}
4545+
}
4546+
},
4547+
"404": {
4548+
"description": "Unknown platform"
4549+
}
4550+
}
4551+
}
4552+
},
4553+
"/api/content-agent/callback": {
4554+
"post": {
4555+
"description": "Internal callback endpoint for the `poll-content-run` Trigger.dev task. Receives content generation results and posts them back to the originating Slack thread. Authenticated via the `x-callback-secret` header.\n\nThis endpoint is not intended for external use — it is called automatically by the polling task when content runs complete, fail, or time out.",
4556+
"requestBody": {
4557+
"description": "Content generation results from the polling task",
4558+
"required": true,
4559+
"content": {
4560+
"application/json": {
4561+
"schema": {
4562+
"type": "object",
4563+
"required": ["threadId", "status"],
4564+
"properties": {
4565+
"threadId": {
4566+
"type": "string",
4567+
"description": "Chat SDK thread identifier for the originating Slack thread"
4568+
},
4569+
"status": {
4570+
"type": "string",
4571+
"enum": ["completed", "failed", "timeout"],
4572+
"description": "Overall status of the content generation batch"
4573+
},
4574+
"results": {
4575+
"type": "array",
4576+
"description": "Per-run results",
4577+
"items": {
4578+
"type": "object",
4579+
"required": ["runId", "status"],
4580+
"properties": {
4581+
"runId": {
4582+
"type": "string",
4583+
"description": "Trigger.dev run ID"
4584+
},
4585+
"status": {
4586+
"type": "string",
4587+
"enum": ["completed", "failed", "timeout"]
4588+
},
4589+
"videoUrl": {
4590+
"type": "string",
4591+
"description": "URL of the generated video (when completed)"
4592+
},
4593+
"captionText": {
4594+
"type": "string",
4595+
"description": "Generated caption text (when completed)"
4596+
},
4597+
"error": {
4598+
"type": "string",
4599+
"description": "Error message (when failed)"
4600+
}
4601+
}
4602+
}
4603+
},
4604+
"message": {
4605+
"type": "string",
4606+
"description": "Optional human-readable message"
4607+
}
4608+
}
4609+
}
4610+
}
4611+
}
4612+
},
4613+
"responses": {
4614+
"200": {
4615+
"description": "Callback processed and results posted to Slack",
4616+
"content": {
4617+
"application/json": {
4618+
"schema": {
4619+
"type": "object",
4620+
"properties": {
4621+
"status": {
4622+
"type": "string",
4623+
"example": "ok"
4624+
}
4625+
}
4626+
}
4627+
}
4628+
}
4629+
},
4630+
"401": {
4631+
"description": "Missing or invalid callback secret"
4632+
},
4633+
"400": {
4634+
"description": "Invalid request body"
4635+
}
4636+
},
4637+
"security": [
4638+
{
4639+
"callbackSecret": []
4640+
}
4641+
]
4642+
}
45034643
}
45044644
},
45054645
"components": {

‎content-agent.mdx‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
---
2+
title: 'Content Agent'
3+
description: 'Generate artist videos from Slack with the Recoup Content Agent bot'
4+
---
5+
6+
## Overview
7+
8+
The **Recoup Content Agent** is a Slack bot that generates social-ready artist videos on @mention. It plugs into the existing [content creation pipeline](/api-reference/content/create) and delivers results directly in your Slack thread.
9+
10+
## How It Works
11+
12+
```
13+
User mentions bot in Slack
14+
↓
15+
@RecoupContentAgent <artist_account_id> [template] [batch=N] [lipsync]
16+
↓
17+
Bot validates the artist and sends an immediate acknowledgment
18+
↓
19+
Triggers the content creation pipeline (POST /api/content/create)
20+
↓
21+
Background task polls for completion (~5-10 min)
22+
↓
23+
Bot replies in-thread with the generated video URL(s)
24+
```
25+
26+
### @Mention Syntax
27+
28+
```
29+
@RecoupContentAgent <artist_account_id> [template] [batch=N] [lipsync]
30+
```
31+
32+
| Parameter | Required | Description |
33+
|-----------|----------|-------------|
34+
| `artist_account_id` | Yes | UUID of the artist account |
35+
| `template` | No | Content template name (defaults to `artist-caption-bedroom`) |
36+
| `batch=N` | No | Number of videos to generate (1-30, default 1) |
37+
| `lipsync` | No | Enable lipsync mode (audio baked into video) |
38+
39+
### Examples
40+
41+
**Basic — single video with default template:**
42+
```
43+
@RecoupContentAgent abc-123-uuid
44+
```
45+
46+
**Custom template:**
47+
```
48+
@RecoupContentAgent abc-123-uuid artist-caption-bedroom
49+
```
50+
51+
**Batch with lipsync:**
52+
```
53+
@RecoupContentAgent abc-123-uuid batch=3 lipsync
54+
```
55+
56+
## Architecture
57+
58+
The content agent follows the same pattern as the coding agent bot:
59+
60+
| Component | Location | Purpose |
61+
|-----------|----------|---------|
62+
| Slack webhook | `POST /api/content-agent/slack` | Receives @mention events |
63+
| Callback endpoint | `POST /api/content-agent/callback` | Receives polling results |
64+
| Bot singleton | `lib/content-agent/bot.ts` | Chat SDK with Slack adapter + Redis state |
65+
| Mention handler | `lib/content-agent/handlers/` | Parses args, validates artist, triggers pipeline |
66+
| Poll task | `poll-content-run` (Trigger.dev) | Monitors content runs, posts results via callback |
67+
68+
### Data Flow
69+
70+
1. **Slack event** → `POST /api/content-agent/slack` handles the webhook
71+
2. **Mention handler** parses the command, calls [`GET /api/content/validate`](/api-reference/content/validate) to check artist readiness
72+
3. **Content creation** triggered via [`POST /api/content/create`](/api-reference/content/create) — returns `runIds`
73+
4. **Poll task** (`poll-content-run`) monitors the Trigger.dev runs every 30 seconds (up to 30 minutes)
74+
5. **Callback** → [`POST /api/content-agent/callback`](/api-reference/content-agent/callback) receives results and posts video URLs back to the Slack thread
75+
76+
### API Endpoints Used
77+
78+
| Endpoint | When | Purpose |
79+
|----------|------|---------|
80+
| [`GET /api/content/validate`](/api-reference/content/validate) | Before triggering | Checks if the artist has required assets |
81+
| [`POST /api/content/create`](/api-reference/content/create) | On mention | Triggers the video generation pipeline |
82+
| [`GET /api/content/templates`](/api-reference/content/templates) | Reference | Lists available content templates |
83+
| [`POST /api/content-agent/callback`](/api-reference/content-agent/callback) | After completion | Internal — receives poll results |
84+
85+
## Setup
86+
87+
### 1. Create a Slack App
88+
89+
1. Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app
90+
2. Under **OAuth & Permissions**, add bot scopes:
91+
- `chat:write` — post messages
92+
- `app_mentions:read` — receive @mention events
93+
3. Under **Event Subscriptions**:
94+
- Enable events
95+
- Set the request URL to `https://recoup-api.vercel.app/api/content-agent/slack`
96+
- Subscribe to `app_mention` bot event
97+
4. Install the app to your workspace
98+
99+
### 2. Configure Environment Variables
100+
101+
| Variable | Where | Description |
102+
|----------|-------|-------------|
103+
| `SLACK_CONTENT_BOT_TOKEN` | API (Vercel) | Bot OAuth token (`xoxb-...`) from Slack app |
104+
| `SLACK_CONTENT_SIGNING_SECRET` | API (Vercel) | Signing secret from Slack app **Basic Information** |
105+
| `CONTENT_AGENT_CALLBACK_SECRET` | API + Tasks | Shared secret for callback authentication (generate a random string) |
106+
| `RECOUP_API_KEY` | API + Tasks | Recoup API key for authenticating pipeline requests |
107+
| `RECOUP_API_BASE_URL` | Tasks (Trigger.dev) | API base URL (e.g., `https://recoup-api.vercel.app`) |
108+
109+
### 3. Verify
110+
111+
Mention the bot in any Slack channel where it's been added:
112+
113+
```
114+
@RecoupContentAgent <your-artist-account-id>
115+
```
116+
117+
You should see:
118+
1. An immediate acknowledgment message
119+
2. A video URL reply in the thread after ~5-10 minutes
120+
121+
## Troubleshooting
122+
123+
| Issue | Cause | Fix |
124+
|-------|-------|-----|
125+
| No response from bot | Event subscription URL not configured | Check Slack app Event Subscriptions |
126+
| "Artist not found" | Invalid `artist_account_id` | Verify the UUID exists in the platform |
127+
| "No GitHub repository found" | Artist missing repo config | Ensure the artist account has a linked GitHub repo |
128+
| Timeout after 30 min | Pipeline took too long | Check Trigger.dev dashboard for the failed run |
129+
| "Unsupported template" | Invalid template name | Use [`GET /api/content/templates`](/api-reference/content/templates) to list available templates |

‎docs.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,12 @@
2323
"authentication",
2424
"api-reference/sandboxes/create"
2525
]
26+
},
27+
{
28+
"group": "Agents",
29+
"pages": [
30+
"content-agent"
31+
]
2632
}
2733
]
2834
},
@@ -243,6 +249,13 @@
243249
"api-reference/content/validate",
244250
"api-reference/content/estimate"
245251
]
252+
},
253+
{
254+
"group": "Content Agent",
255+
"pages": [
256+
"api-reference/content-agent/webhook",
257+
"api-reference/content-agent/callback"
258+
]
246259
}
247260
]
248261
}

0 commit comments

Comments
 (0)