Contact Us
Log inStart Free Trial

Building Blocks / Capture & Consent

Consent Capture

Capture a yes before you call or text, tied to the number.

Drop-in widget. Load https://webforms.dropcowboy.com/latest/dropcowboy-embed-consent.min.js and pass it a site token your server mints. Do not rebuild the consent form or proof-of-consent storage; the widget already does it.

When to use this vs REST

Use Consent Capture to record a yes before you call or text. Other blocks need the consent_id it returns.

Do not rebuild

  • Consent storage and proof (origin, time, text shown).

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.
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}'
  1. Load the script, init with the token, and call a method:
<script src="https://webforms.dropcowboy.com/latest/dropcowboy-embed-consent.min.js"></script>
<script>
(async function () {
  const minted = await fetch('/dropcowboy/token', { method: 'POST' }).then(function (r) { return r.json(); });
  await DropCowboy.consent.init({ token: minted.token });
  DropCowboy.consent.addConsentListener(function (event) {
    window.lastConsentId = event.consent_id || event.id;
  });
  document.getElementById('opt-in').addEventListener('click', async function () {
    var record = await DropCowboy.consent.captureConsent(
      document.getElementById('phone').value,
      { text: 'I agree to receive calls and texts.' }
    );
    window.lastConsentId = record.consent_id || record.id;
  });
})();
</script>

JS API / HTML tag

Method What it does
init({ token }) Site token. Origin is captured with the record.
setTheme({ theme, primaryColor }) LIGHT/DARK plus accent.
captureConsent(phone, { text, channels }) Saves the yes. Returns the consent record; keep consent_id for SMS and callback.
addConsentListener(fn) -> stop Fires after a successful capture, including from <dc-consent>.
addErrorListener(fn) -> stop Fires on validation or save errors.
close() Tears down the session.

HTML tag:

<dc-consent text="I agree to receive calls and texts."></dc-consent>

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.
  • The page origin is stored with the consent. Capture it on the page the visitor actually sees.

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

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

Full reference: Embed site tokens.

Copy the code

The snippets on this page. Your server keeps the API key pair (KEY and SECRET for curl, DC_KEY and DC_SECRET for Node); the browser only sees the short-lived site token.

Load the Consent Capture
<script src="https://webforms.dropcowboy.com/latest/dropcowboy-embed-consent.min.js"></script>
<script>
(async function () {
  const minted = await fetch('/dropcowboy/token', { method: 'POST' }).then(function (r) { return r.json(); });
  await DropCowboy.consent.init({ token: minted.token });
  DropCowboy.consent.addConsentListener(function (event) {
    window.lastConsentId = event.consent_id || event.id;
  });
  document.getElementById('opt-in').addEventListener('click', async function () {
    var record = await DropCowboy.consent.captureConsent(
      document.getElementById('phone').value,
      { text: 'I agree to receive calls and texts.' }
    );
    window.lastConsentId = record.consent_id || record.id;
  });
})();
</script>
Mint a site token (your server)
// 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 });
});
Mint a site token (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}'
HTML tag
<dc-consent text="I agree to receive calls and texts."></dc-consent>