Building Blocks / Voice

AI Receptionist

Let visitors talk to your AI agent from your app.

Drop-in widget. Load https://webforms.dropcowboy.com/latest/dropcowboy-receptionist.min.js and pass it a site token your server mints. Do not rebuild browser audio capture or the agent session; the widget already does it.

This is the browser widget: a visitor talks to your AI agent from a web page. To have an agent answer your phone line, use the Receptionist API instead; nothing is embedded.

Calling setup comes with the site token. Your page never configures SIP, STUN, or TURN servers; the script does.

When to use this vs REST

Use this widget when a visitor should talk to your AI agent from a web page. To have the agent answer your phone line, use the hosted receptionist API instead: create a knowledge base, create the agent, then assign the line. See Receptionist API reference.

Do not rebuild

Browser audio capture and playback.
The agent itself. Configure it in AI Agents and pass its id.

Drop-in

On your server, trade your API key for a short-lived site token (the key needs numbers:write):

// Your server. Browser code never sees KEY/SECRET.
app.post('/dropcowboy/token', async function (req, res) {
  const r = await fetch('https://api-v2.dropcowboy.com/phone/public/embed/token', {
    method: 'POST',
    headers: {
      'x-key': process.env.DC_KEY,
      'x-secret': process.env.DC_SECRET,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ site_id: process.env.DC_SITE_ID, scope: ['dialer:webrtc'], ttl_seconds: 900 })
  });
  const body = await r.json();
  if (!r.ok) return res.status(r.status).json(body);
  // The API wraps results in data. Hand the browser just the token.
  res.json({ token: body.data.token, expires_at: body.data.expires_at });
});

Or test the mint with cURL:

# On your server: trade your API key (needs numbers:write) for a site token. 1 hour max.
curl -s -X POST https://api-v2.dropcowboy.com/phone/public/embed/token \
  -H "x-key: $KEY" -H "x-secret: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"site_id":"YOUR_SITE_ID","scope":["dialer:webrtc"],"ttl_seconds":900}'

Load the script, init with the token, and call a method:

<script src="https://webforms.dropcowboy.com/latest/dropcowboy-receptionist.min.js"></script>
<script>
(async function () {
  const minted = await fetch('/dropcowboy/token', { method: 'POST' }).then(function (r) { return r.json(); });
  await DropCowboy.receptionist.init({
    token: minted.token,
    agentId: 'a9c3e8f1-4b2d-4a7c-8e9b-1c2d3e4f5a6b'
  });
  DropCowboy.receptionist.setTheme({ theme: 'LIGHT', primaryColor: '#009efb' });

  DropCowboy.receptionist.addSessionEndedListener(function (event) {
    saveAgentSessionToCrm(event);
  });

  document.getElementById('talk-to-agent').addEventListener('click', function () {
    DropCowboy.receptionist.startSession();
  });
})();
</script>

JS API / HTML tag

Method	What it does
`init({ token, agentId })`	agentId is the portal AI agent UUID.
`setTheme({ theme, primaryColor })`	LIGHT/DARK plus accent.
`startSession(options)`	Starts the visitor session with that agent.
`addSessionEndedListener(fn) -> stop`	Fires when the session hangs up.
`addErrorListener(fn) -> stop`	Fires on mint or session errors.
`close()`	Ends the session.

Auth and scopes

Site token. Your API secret stays on your server.

Site token scope: dialer:webrtc. Mint it with POST https://api-v2.dropcowboy.com/phone/public/embed/token using an API key with numbers:write. Tokens last up to one hour.

Limits

Site tokens last at most one hour (the default). Mint a fresh one per page load or session; do not cache one across users.
Calls and texts need a connected carrier (BYOC) and prepaid balance. Without them the mint returns 402 or 403 for telephony scopes.
Sessions bill as AI agent minutes.

Routes are on https://api-v2.dropcowboy.com.

Receptionist API reference - hosted answering on your phone line
POST /phone/public/embed/token - mint the site token

Full reference: Embed site tokens, AI agents API.