TikTok v1

README.md

---
name: TikTok v1
description: TikTok read-first (list videos) then posting. Uses Sulala Portal for OAuth; connect your TikTok account in the Portal, then list or post via scripts. Use when the user wants to list TikTok videos or post a video.
credentials:
  - PORTAL_GATEWAY_URL
  - PORTAL_API_KEY
---

# TikTok — Sulala Portal auth (v1)

List your TikTok videos and post new videos using your **TikTok account connected in the Sulala Portal**. No client key/secret in the skill; auth is via Portal API.

**Auth vs upload:** Required auth (access token) comes **only from Sulala Portal** (list connections → `connections/{id}/use`). Uploading/posting is done **directly by the TikTok skill scripts**. No separate TikTok login in the skill.

**Simplest setup:** Set **PORTAL_GATEWAY_URL** and **PORTAL_API_KEY** in the TikTok skill config (Dashboard → Skills → TikTok → Config). Then the scripts fetch the token from the Portal automatically — the agent can run `node scripts/tiktok_list_videos.js 2` or `node scripts/tiktok_post_after_list.js 'caption' '/path/to/video.mp4'` without passing `--token`.

## What this skill can do
- **List videos** — Fetch your recent TikTok videos (open.tiktokapis.com v2/video/list).
- **Post video** — Upload a video and publish it (init → chunked upload → status). Caption, privacy level, optional.
- **Check publish status** — Query status of a recent upload by `publish_id` (e.g. after async upload or to see fail reason).

## What it doesn’t do
- **Delete video** — TikTok has no official delete API; use the TikTok app.
- **Analytics** — Views, likes, etc. require a different TikTok API product (Display/Research). Not included here.

## When to use
- List your recent videos (read)
- Post a new video (write)
- Check status of an upload (publish_id from a previous post)

## Important: no separate “Login to TikTok” step

**Do not ask the user to “Login to TikTok” or run a separate TikTok OAuth flow.** The user connects TikTok once in [portal.sulala.ai](https://portal.sulala.ai).

**Getting the token (two options):**

1. **Portal URL + API key in TikTok config (recommended)** — Set `PORTAL_GATEWAY_URL` (e.g. `https://portal.sulala.ai/api/gateway`) and `PORTAL_API_KEY` in the TikTok skill config. Then just run the script (e.g. `node scripts/tiktok_list_videos.js 2`); the script fetches the token from the Portal automatically. No `--token` needed.
2. **Agent passes token** — If the agent has the `sulala-portal_request` tool: call `GET connections`, find the TikTok connection, then `POST connections/{id}/use`, and pass the returned `accessToken` to the script with `--token "<accessToken>"`.

If the script fails with “Missing: … PORTAL_GATEWAY_URL + PORTAL_API_KEY”, tell the user to set those in Dashboard → Skills → TikTok → Config (and to connect TikTok in the Portal if they haven’t). Do not ask them to “login to TikTok” in the chat.

## Setup
1. **Connect TikTok in Sulala Portal** — In [portal.sulala.ai](https://portal.sulala.ai), add a TikTok connection (OAuth is handled by the Portal).
2. **Add Portal URL and API key to TikTok skill** — In Dashboard → Skills → TikTok → Config, set **PORTAL_GATEWAY_URL** (e.g. `https://portal.sulala.ai/api/gateway`) and **PORTAL_API_KEY** (from portal.sulala.ai → API Keys). Then list/post scripts will fetch the token automatically.
3. **Scopes** — Connect TikTok in the Portal with **video.list** (for listing) and **video.upload** / **video.publish** (for posting). List and post both use **open.tiktokapis.com** (no graph.tiktok.com).

No `TIKTOK_CLIENT_KEY` or `TIKTOK_CLIENT_SECRET` in the skill; the Portal holds the OAuth app and connection.

## Getting the token (Portal)
- **Tool**: `sulala-portal_request`
- **List connections**: `GET` path `connections` (filter by `provider === "tiktok"` in the response).
- **Get token**: `POST` path `connections/{id}/use` (use the connection’s `id` or `connection_id` from the list). Response: `{ connectionId, provider, accessToken, scopes }`.

## Read: list videos (exec)
If **PORTAL_GATEWAY_URL** and **PORTAL_API_KEY** are set in TikTok config, run the script without `--token`; it will fetch the token from the Portal:

```json
{
  "skill_id": "tiktok",
  "command": "node scripts/tiktok_list_videos.js 10"
}
```

Limit is optional (default 10). Or pass `--token "<accessToken>"` if the agent obtained the token via sulala-portal_request.

## Post: upload video (exec)
Uses TikTok Content Posting API: init → chunked upload → publish (all on **open.tiktokapis.com**). If Portal config is set, run without `--token`:

```json
{
  "skill_id": "tiktok",
  "command": "node scripts/tiktok_post_after_list.js 'Your caption' '/path/to/video.mp4'"
}
```

Optional fourth arg: **privacy** — `SELF_ONLY` (default), `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, or `FOLLOWER_OF_CREATOR`. Arguments: `caption`, `videoPath` (required), `privacy` (optional).

## Check publish status (exec)
To see the status of an upload (e.g. `PROCESSING_UPLOAD`, `PUBLISH_COMPLETE`, or `FAILED` and `fail_reason`):

```json
{
  "skill_id": "tiktok",
  "command": "node scripts/tiktok_status.js <publish_id>"
}
```

Use the `publish_id` returned when a post was started (or from the post script output).

## Scripts
Token source (in order): `--token`, then `TIKTOK_ACCESS_TOKEN`, then `token.json`, then Portal (when **PORTAL_GATEWAY_URL** and **PORTAL_API_KEY** are set).
- `scripts/tiktok_list_videos.js` — list videos (scope video.list).
- `scripts/tiktok_post_after_list.js` — post video: init → chunked upload → status poll (scope video.publish). Optional privacy arg.
- `scripts/tiktok_status.js` — check status of a publish by `publish_id` (scope video.publish or video.upload).