Click-to-Text

A button that starts an SMS to your business number.

Drop-in widget. Load https://webforms.dropcowboy.com/latest/dropcowboy-click-to-text.min.js and pass it a site token your server mints. Do not rebuild the compose box or the send flow; the widget already does it.

When to use this vs REST

Use Click-to-Text for a button that starts a text thread with your business. Use POST /sms to text from your server.

Do not rebuild

  • The compose box and send 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-text.min.js"></script>
<script>
(async function () {
  const minted = await fetch('/dropcowboy/token', { method: 'POST' }).then(function (r) { return r.json(); });
  await DropCowboy.clickToText.init({ token: minted.token });
  DropCowboy.clickToText.setTheme({ theme: 'LIGHT', primaryColor: '#009efb' });
  document.getElementById('text-us').addEventListener('click', function () {
    DropCowboy.clickToText.sendMessage('+15125550100', {
      body: 'Hi, I have a question about pricing.',
      consentId: window.lastConsentId
    });
  });
})();
</script>

JS API / HTML tag

Method What it does
init({ token, number }) Default business DID.
setTheme({ theme, primaryColor }) LIGHT/DARK plus accent.
sendMessage(to, { body, consentId }) Sends the SMS. consentId is required.
addMessageListener(fn) -> stop Fires after a queued send.
addErrorListener(fn) -> stop Fires on send errors.
close() Tears down the session.

HTML tag:

<dc-click-to-text number="+15125550100" prefill="Hi"></dc-click-to-text>

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.
  • Outbound SMS needs a consent_id captured with Consent Capture for that phone number.
  • US carriers deliver business texts only from a number on a registered brand and campaign (10DLC). Until the sending number is registered, a send fails with 400 and detail.code: sms_registration_required, and the block tells the user to register it.
  • Each site has its own conversation with a phone number. A text sent from this site never joins a conversation started in Drop Cowboy® or on another site, and the site inbox lists only this site's conversations. A reply goes to whichever conversation texted that number last.

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

  • POST /sms - send a text from your server
  • POST /phone/public/embed/token - mint the site token

Full reference: Embed site tokens, Texts API.


While Drop Cowboy provides tools to support compliance efforts, customers remain solely responsible for obtaining proper consent, maintaining opt-out lists, and complying with all federal and state telemarketing regulations. Consult with your legal counsel to ensure your specific use case and consent mechanisms comply with applicable laws.

This information is for educational purposes only and does not constitute legal advice. Regulations vary by jurisdiction and use case. Always consult with qualified legal counsel to ensure your specific practices comply with applicable federal and state laws.

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 Click-to-Text
<script src="https://webforms.dropcowboy.com/latest/dropcowboy-click-to-text.min.js"></script>
<script>
(async function () {
  const minted = await fetch('/dropcowboy/token', { method: 'POST' }).then(function (r) { return r.json(); });
  await DropCowboy.clickToText.init({ token: minted.token });
  DropCowboy.clickToText.setTheme({ theme: 'LIGHT', primaryColor: '#009efb' });
  document.getElementById('text-us').addEventListener('click', function () {
    DropCowboy.clickToText.sendMessage('+15125550100', {
      body: 'Hi, I have a question about pricing.',
      consentId: window.lastConsentId
    });
  });
})();
</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.
# 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}'
HTML tag
<dc-click-to-text number="+15125550100" prefill="Hi"></dc-click-to-text>