Convoship Docs
Back to Studio

Publish, embed & versions

Go live, embed on your site with publicToken, rotate tokens, version history, and rollback.

AI Agents ship to end users through a published snapshot and a per-agent public_token. Configure everything under Operate → Deploy (/app/agents/{slug}/publish) or the header Deploy button.

Publishing

  1. Open Deploy tab or click Publish vN in the shell header.
  2. POST /v1/ai-agents/{slug}/publish runs the eval gate (if threshold > 0), sets status live, increments version label, creates AiAgentVersion snapshot.
  3. First publish mints a UUID public_token returned in the response and embed config.

Eval gate: Workspace Settings → AI Agent production → Eval pass threshold. 0 = disabled. 0.8 = at least 80% of evals must pass. Failed publish returns pass_rate and sample failures.

Embed on your website

After publish, copy the embed snippet from the Deploy tab. It uses publicToken (not the Assistant cdp_* deployment token).

<script src="https://app.convoship.org/embed/v1.js" async></script>
<script>
  window.ConvoshipQueue = window.ConvoshipQueue || [];
  window.ConvoshipQueue.push(['init', {
    publicToken: 'YOUR_PUBLIC_UUID',
    channel: 'web',
    apiUrl: 'https://api.convoship.org',
    stream: true
  }]);
</script>
  • Self-hosted script — build with pnpm prebuild:web; Studio serves /embed/v1.js from apps/web/public/embed/v1.js.
  • stream: true — token-by-token SSE from POST /v1/public/ai-agents/{token}/turn?stream=true.
  • channel must appear in agent.channels (e.g. Web) or the turn returns 403.
  • CORS — public routes allow browser origins per deployment config.

Assistant scripted bots still use Channels → deployment token (cdp_*). See /docs/embed-sdk for both paths.

Rotate public token

Deploy tab → Rotate confirms replacement. POST /v1/ai-agents/{slug}/rotate-public-token issues a new UUID; old embeds stop working until you update the snippet.

Version history & rollback

  • GET /v1/ai-agents/{slug}/versions — list snapshots with eval_pass_rate when gate ran on publish.
  • View evals — expands GET .../versions/{version_id}/eval-runs (per-eval pass/fail + rationale).
  • Rollback — POST .../rollback/{version_id} restores that snapshot as the live published config.

Public turn API

POST /v1/public/ai-agents/{public_token}/turn
  { "message": "...", "channel": "web", "session_id": "optional", "user_label": "embed" }

# SSE streaming
POST /v1/public/ai-agents/{public_token}/turn?stream=true

Rate limit: Workspace.rpm_cap_per_agent (Redis-backed when Redis is available). Playground uses the same cap; 0 = unlimited in studio testing.

Verify end-to-end

  1. Publish agent in Studio.
  2. Paste snippet on a test page (allowed origin if restricted).
  3. Send a message in the widget.
  4. Confirm conversation appears under /app/agents/{slug}/convos.