Click-to-Call

A button that calls you, or requests a callback.

Drop-in widget. Load https://webforms.dropcowboy.com/latest/dropcowboy-click-to-call.min.js and pass it a site token your server mints. Do not rebuild browser calling or the callback request; the widget already does it.

When to use this vs REST

Use Click-to-Call for a button that calls your business or asks for a callback. There is no REST equivalent for the visitor side.

Do not rebuild

• Browser calling.
• The callback request flow.

Drop-in

1. 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.
# site_id is one UUID per app; generate your own in place of the example.
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":"00000000-0000-4000-8000-000000000000","scope":["dialer:webrtc"],"ttl_seconds":900}'

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

<script src="https://webforms.dropcowboy.com/latest/dropcowboy-click-to-call.min.js"></script>
<script>
(async function () {
  const minted = await fetch('/dropcowboy/token', { method: 'POST' }).then(function (r) { return r.json(); });
  await DropCowboy.clickToCall.init({ token: minted.token });
  DropCowboy.clickToCall.setTheme({ theme: 'LIGHT', primaryColor: '#009efb' });
  DropCowboy.clickToCall.addCallEndedListener(function (event) {
    console.log('ended', event.disposition);
  });
  document.getElementById('call-us').addEventListener('click', function () {
    DropCowboy.clickToCall.startCall('+15125550100');
  });
  document.getElementById('call-me-back').addEventListener('click', function () {
    DropCowboy.clickToCall.startCall(document.getElementById('phone').value, {
      mode: 'callback',
      consentId: window.lastConsentId
    });
  });
})();
</script>

JS API / HTML tag

HTML tag:

<dc-click-to-call number="+15125550100"></dc-click-to-call>

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.
• Callback mode needs a consent_id from Consent Capture.
• Calls belong to the Drop Cowboy® user who created the API key that minted the site token. They need no dialer seat, and any number of your users can be on calls at once with tokens from the same key. A token minted from a key with no creator is refused with 403 acting_user_required.
• To tell your users apart, pass your own user id as sub when you mint the token. The contact.call.* webhooks for the call carry it back as external_user_id, along with site_id.

Related REST

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

• POST /phone/public/embed/token - mint the site token

Full reference: Embed site tokens.