Publisher API

You already have a Discord bot with commands, buttons, and interaction handlers. You do not replace your bot with ours. You hook into your own interactions — whenever it makes sense in your bot's flow (a command, a button, a menu) — and call our three endpoints to deliver an ad.

Your bot sends the captcha, your bot sends the ad embed, your bot confirms delivery. Our API handles everything else: ad selection, billing, targeting, and payout. You keep your existing commands and features completely intact.

Standard payout is 35% of what the advertiser pays per event. Send optional member data (member_data_provided, user_roles, is_booster) and earn 45%. Payout applies to views, clicks, joins, and stays — whatever campaign type the ad uses.

Authentication

There are no auth headers. Pass your api_key and external_bot_id in the body of every request.

The 3-step flow

Drop-in snippets for your existing bot. Copy the helper and the three handlers into your existing interaction handler — do not replace your bot. All snippets use a cv: prefix on customIds so they never clash with your own. The API key and base URL are pre-filled if you arrived from the dashboard.

Generates a captcha challenge. Returns a PNG image (base64 data URI) containing 6 characters the user must type to prove they're human.

{
  "ok": true,
  "captcha_token": "a3f8c2...",          // pass this to ads/request
  "challenge_text": "data:image/png;base64,...",  // render as an image
  "prompt_text": "Type the 6 characters shown (left to right).",
  "expires_in_seconds": 60
}

Verifies the captcha answer and returns an ad. Always check if ad is null before sending anything to Discord.

{
  "ok": true,
  "ad": {
    "ad_id": "123",
    "banner_url": "https://...",         // embed image
    "button_name": "Visit site",         // link button label
    "click_url": "https://.../c/TOKEN",  // link button URL — tracks clicks
    "embed_color": "#6D5EFC",
    "target_type": "views"               // "views" | "clicks" | "surveys"
  },
  "view_token": "eyJ...",                // pass to views/confirm
  "expires_in_seconds": 120
}

{
  "ok": true,
  "ad": null,
  "view_token": null,
  "denied_reason": "user_daily_cap"  // see Errors section
}

When ad is null, skip silently — do not send any embed.

Records the delivery and triggers billing. Call this after the Discord message is sent. This is when your earnings are recorded.

// Billed
{ "ok": true, "billed": true, "ad_id": "123", "auto_paused": false, "daily_cap_reached": false }

// Not billed
{ "ok": true, "billed": false, "reason": "token_expired" }

Campaign types

The ad.target_type field in the ads/request response tells you what kind of campaign was served. Your integration code does not need to change per type — the flow is always the same. Payouts differ because advertisers pay different rates per action.

Joins & stays

Join and stay campaigns pay when a user joins the advertiser's Discord server (and optionally stays for a set duration). Your integration is identical to any other campaign — run the normal 3-step flow. No extra code needed.

A stay campaign requires the user to remain in the server for a set duration before payout is recorded. This is tracked automatically by our backend after the join — no additional code or events needed from your bot.

Premium data — 45% payout

Standard payout is 35% of advertiser spend. If your bot has the Server Members Intent (a privileged intent from the Discord Developer Portal), you can send per-user member data on each ad request and earn 45%.

User roles are passed through an AI classifier that infers demographic signals — gender, age range, device type, language, interests — based on role names (e.g. "He/Him", "Mobile", "PlayStation", "18+"). These signals improve ad targeting accuracy over time, which raises advertiser CPMs, which raises your earnings. The data is never sold and is only used for targeting within Cordvertise.

Errors & denials

Rate limits & delivery caps

Idempotency

Calling views/confirm multiple times with the same event_id returns already_confirmed and does not double-bill. Safe to retry on network failure.