Launch an app with persona accounts with OpenAI Codex

Q: How do I attribute installs per persona?

Distinct `link_in_bio` per account with UTM/deep-link parameters; read clicks/installs in your attribution tool and post metrics from `get_analytics_dashboard` (`account` filter).

Q: How do managers keep the voice consistent?

Captions are yours (`description`), visuals are yours (`video_url`); the manager posts as instructed and does not improvise copy. Express the persona in the warming phase through `advanced_warming_terms` — the niche searches the account is made to perform are what give it a believable history.

Q: What if a persona underperforms?

Stop adding slots to it, extend winners with `add_video_slots`, and reuse the account later with a `videos_only` bundle — accounts stay managed and warm.

An app launch on short video usually runs on personas — "the productivity nerd", "the student", "the parent" — each a real account with its own voice, bio link and content plan. From OpenAI Codex, each persona is one TokPortal bundle: create_bundle in the launch country, configure_bundle_account with the persona's handle, bio and link_in_bio (your store or deep link), warming terms in the persona's niche, and 30 days of configure_bundle_video slots showing the app in that persona's life. Human managers hold the accounts, so there is no OAuth per persona and no audit; get_analytics_dashboard compares personas.

Connect TokPortal to OpenAI Codex

OpenAI Codex is a terminal agent: OpenAI's coding agent (Codex CLI and IDE extension); MCP servers live in ~/.codex/config.toml.

Add the remote server to ~/.codex/config.toml:

[mcp_servers.tokportal]
url = "https://app.tokportal.com/api/ext/mcp"
# either OAuth (run `codex mcp login tokportal` once) …
# … or a static key from your environment:
# bearer_token_env_var = "TOKPORTAL_API_KEY"

Then codex mcp login tokportal for the OAuth flow. Recent Codex builds also accept the one-liner codex mcp add tokportal --url https://app.tokportal.com/api/ext/mcp; the stdio form always works:

codex mcp add tokportal --env TOKPORTAL_API_KEY=sk_... -- npx -y tokportal-mcp

Snippet status: verified against OpenAI Codex's documentation (source).

Once connected, sanity-check the setup with a read-only call — "What is my TokPortal credit balance?" should trigger tokportal_get_credit_balance. Every tool runs as your TokPortal account and spends your credits; read-only tools (get_*, list_*, export_*) never do.

How it works

Design the cast first: 3–6 personas, each with a country (the app's launch markets), a platform (TikTok, Instagram or both), a handle, a one-line bio ending with a call to action, and a link — TokPortal supports link_in_bio as a URI, so use a tracked link per persona (?utm_content=persona_a) to attribute installs. Create each with create_bundle (account_and_videos, videos_quantity 30–60), or all at once with create_bundles_bulk if they share a country, then personalize each account with configure_bundle_account (username, visible_name, biography, profile_picture_url uploaded via upload_image_from_url, link_in_bio).

Warming matters for personas because the account should look like the person: generate_warming_terms from "college student who studies with Pomodoro apps" gives terms a student would search. Content is per persona: screen recordings of the app, talking-head style clips, before/after — uploaded once via upload_video, then placed with batch_configure_bundle_videos at ≤3 posts per day, captions in the persona's voice, disclose_as_ads: true where your legal team says so. publish_bundle per persona.

Then run it as a portfolio from OpenAI Codex: get_analytics_dashboard and get_analytics_series per account (account filter) show which persona converts, list_analytics_account_comments reveals objections to answer in the next batch, and add_video_slots extends the winners. Register account.finalized, video.finalized and account.banned webhooks so the agent (or your Slack) knows the state of every persona without polling.

Run it from OpenAI Codex

Start a OpenAI Codex session in the project folder and paste the prompt below. Every tokportal_* call is shown before it runs; approve read-only tools freely and review write tools (create_*, configure_*, publish_*) before accepting.

Tool sequence

tokportal_get_credit_costs — Personas × (setup + slots + warming) before committing.
tokportal_create_bundle — One per persona: platform, country, videos_quantity, wants_advanced_warming + terms.
tokportal_upload_image_from_url — Persona avatar → profile_picture_url (purpose profile_picture).
tokportal_configure_bundle_account — username, visible_name, biography, link_in_bio (tracked per persona).
tokportal_batch_configure_bundle_videos — 30-day plan per persona, ≤3/day, persona-voice captions.
tokportal_publish_bundle — Per persona.
tokportal_create_webhook_endpoint — account.finalized, video.finalized, account.banned → your Slack/agent.
tokportal_get_analytics_dashboard — Compare personas (account filter, from/to).
tokportal_list_analytics_account_comments — Objections and questions per persona to feed the next batch.

Prompt to paste

Use the TokPortal MCP tools. App launch, US, TikTok. Personas: (A) college student "kai.studies",
(B) remote worker "desk.by.dana", (C) parent "mornings.with.mo". For each: create_bundle
(account_and_videos, 30 videos, advanced warming with 3 terms from generate_warming_terms),
configure_bundle_account with a tracked link https://focusapp.example/get?utm_content=<persona>.
Quote everything with get_credit_costs first and stop before publish_bundle.

Run codex in your project, paste the prompt; Codex lists the tokportal_* calls it wants to make and asks for approval unless you run with full-auto.

REST equivalent (same operations, X-API-Key header, base URL https://app.tokportal.com/api/ext)

# Persona A — student, US, TikTok
curl -X POST https://app.tokportal.com/api/ext/bundles \
  -H "X-API-Key: sk_..." -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"bundle_type":"account_and_videos","platform":"tiktok","country":"US","videos_quantity":30,"title":"Persona A – student",
       "wants_advanced_warming":true,"advanced_warming_terms":["study with me","pomodoro","college productivity"],"external_ref":"launch-persona-a"}'

curl -X PUT https://app.tokportal.com/api/ext/bundles/BUNDLE_A/account \
  -H "X-API-Key: sk_..." -H "Content-Type: application/json" \
  -d '{"username":"kai.studies","visible_name":"Kai","biography":"finals survivor · my study stack ↓","link_in_bio":"https://focusapp.example/get?utm_content=persona_a","profile_picture_url":"https://.../kai.jpg"}'

curl -X POST https://app.tokportal.com/api/ext/webhooks \
  -H "X-API-Key: sk_..." -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/tokportal","events":["account.finalized","video.finalized","account.banned"]}'

Key parameters

Parameter	Values	Notes
`link_in_bio`	URI	One tracked link per persona for attribution.
`profile_picture_url`	public URL or TokPortal storage URL	Upload with upload_image_from_url (purpose profile_picture).
`biography`	≤80 TikTok · ≤120 Instagram	Persona voice + CTA.
`external_ref`	≤200 chars	e.g. launch-persona-a; filter list_bundles by it.
`videos_quantity`	0–500	30 = ~10 posting days at 3/day, or 30 days at 1/day.
`platform`	tiktok · instagram	One bundle per platform per persona.

Full schemas: OpenAPI reference · openapi.json.

Example configurations

Persona on Instagram (FR)

{"bundle_type":"account_and_videos","platform":"instagram","country":"FR","videos_quantity":24,"title":"Persona B – parent",
 "wants_advanced_warming":true,"advanced_warming_terms":["organisation famille","routine du matin","astuces parents"],"external_ref":"launch-persona-b"}

Persona account config

{"username":"lea.organise","visible_name":"Léa","biography":"2 enfants, 0 chaos (presque). Mon app ↓","link_in_bio":"https://focusapp.example/fr?utm_content=persona_b"}

Reel slot

{"video_type":"video","instagram_content_type":"reel","description":"le matin en 3 étapes ✨","target_publish_date":"2026-09-10","video_url":"https://.../morning.mp4"}

Credits

A persona with 30 posts and 3 warming targets is 32 + 60 + 15 = 107 credits at standard rates; four personas ≈ 430 credits. Nothing is charged before publish_bundle. Live rates: get_credit_costs — see Credits & Pricing.

Why not the official API

The official APIs would make each persona a separate real user who signs up, authorizes your audited app, and stays under per-token and per-day caps — and none of it creates the account or the persona's history. TokPortal makes a persona an ordered, warmed, human-operated account with a bio link, which is the actual job.

As of August 2026 the first-party routes look like this. TikTok's Content Posting API (Direct Post) requires each account owner to authorize your app with the video.publish scope, limits every user access token to 6 requests per minute, keeps all posts from unaudited apps in private viewing mode until TikTok audits the app, and enforces an unpublished daily post cap per user (spam_risk_too_many_posts) that integrators commonly report at roughly 15–25 posts per account per day. Meta's Instagram Content Publishing API allows 100 API-published posts per professional account in a 24-hour moving window and only for accounts you own and connect via OAuth. Neither creates accounts, warms them, or reports third-party bans. TokPortal is human-operated infrastructure: accounts created and run by managers in the target country, one X-API-Key for all of them, dated slots (max 3 per day per bundle) instead of per-account tokens.

Sources: TikTok Content Posting API – Direct Post, TikTok Content Posting API – Get started, Instagram Platform – Content Publishing.

FAQ

How do I attribute installs per persona?

Distinct link_in_bio per account with UTM/deep-link parameters; read clicks/installs in your attribution tool and post metrics from get_analytics_dashboard (account filter).

Can one persona exist on TikTok and Instagram?

Yes — two bundles (one per platform) with the same handle if available; create_bundles_bulk with platforms: ["tiktok","instagram"] does it in one call.

How do managers keep the voice consistent?

Captions are yours (description), visuals are yours (video_url); the manager posts as instructed and does not improvise copy. Express the persona in the warming phase through advanced_warming_terms — the niche searches the account is made to perform are what give it a believable history.