Embed SDK

The @convoship/embed-sdk package builds to a small IIFE (~15 kB) served as /embed/v1.js. It supports two authentication models — choose the path that matches your bot type.

AI Agent embed (recommended for /app/agents)

1. Publish the agent from Deploy (/app/agents/{slug}/publish).
2. Copy publicToken from the embed snippet (UUID, not cdp_*).
3. Add the script to your site; set channel to a value listed on the agent (e.g. web).

<script src="https://app.convoship.org/embed/v1.js" async></script>
<script>
  window.ConvoshipQueue = window.ConvoshipQueue || [];
  window.ConvoshipQueue.push(['init', {
    publicToken: '550e8400-e29b-41d4-a716-446655440000',
    channel: 'web',
    apiUrl: 'https://api.convoship.org',
    stream: true,
    theme: { primaryColor: '#5b6cf5', position: 'bottom-right' },
    user: { id: 'user-123', name: 'Jane' }
  }]);
</script>

Runtime: POST /v1/public/ai-agents/{publicToken}/turn. With stream: true, the SDK consumes SSE token events. Rotate the token from Deploy if leaked.

Assistant embed (scripted /app/assistants)

1. Publish assistant version.
2. Channels → create Web deployment → copy cdp_* token.
3. Use agentId (assistant UUID) + token in init.

<script src="https://app.convoship.org/embed/v1.js" async></script>
<script>
  window.ConvoshipQueue = window.ConvoshipQueue || [];
  window.ConvoshipQueue.push(['init', {
    token: 'cdp_...',
    agentId: 'ASSISTANT_UUID',
    channel: 'web',
    apiUrl: 'https://api.convoship.org',
  }]);
</script>

Runtime: POST /v1/public/runtime/* with Bearer cdp_* token. Origin allowlist enforced per deployment.

Imperative API

Events

Build & host the script

pnpm --filter @convoship/embed-sdk build
pnpm prebuild:web   # copies to apps/web/public/embed/v1.js
pnpm verify:embed

npm package

npm i @convoship/embed-sdk
import Convoship from "@convoship/embed-sdk";
Convoship.init({ publicToken: "...", channel: "web", stream: true });