Building Blocks / Conversations

Shared Inbox

One inbox for texts, chat, voicemail, and calls.

Drop-in widget. Load https://webforms.dropcowboy.com/latest/dropcowboy-shared-inbox.min.js and pass it a site token your server mints. Do not rebuild the shared inbox, conversation assignment, or voicemail playback; the widget already does it.

When to use this vs REST

Use Shared Inbox when a team answers texts, chat, voicemail, and calls in one place inside your app. Use REST to read or send individual messages from a backend.

Do not rebuild

Conversation assignment and task lists.
Voicemail playback and call history in the thread.

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-shared-inbox.min.js"></script>
<div id="inbox-slot"></div>
<script>
(async function () {
  const minted = await fetch('/dropcowboy/token', { method: 'POST' }).then(function (r) { return r.json(); });
  await DropCowboy.inbox.init({
    token: minted.token,
    from: '+15125550100'
  });
  DropCowboy.inbox.setTheme({ theme: 'LIGHT', primaryColor: '#009efb' });
  DropCowboy.inbox.addTaskListener(function (event) {
    highlightCrmContact(event);
  });
  await DropCowboy.inbox.openInbox({ container: '#inbox-slot' });
})();
</script>

JS API / HTML tag

Method	What it does
`init({ token, from })`	from is the business DID used as caller_id on replies.
`setTheme({ theme, primaryColor })`	LIGHT/DARK plus accent.
`openInbox({ container })`	Mounts the inbox UI. container is a selector or element.
`addTaskListener(fn) -> stop`	Fires when a conversation/task is selected.
`addErrorListener(fn) -> stop`	Fires on load or reply errors.
`close()`	Unmounts the inbox.

HTML tag:

<dc-shared-inbox from="+15125550100"></dc-shared-inbox>

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.
from must be one of your business numbers. Replies go out from that number.

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.

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 Shared Inbox

<script src="https://webforms.dropcowboy.com/latest/dropcowboy-shared-inbox.min.js"></script>
<div id="inbox-slot"></div>
<script>
(async function () {
  const minted = await fetch('/dropcowboy/token', { method: 'POST' }).then(function (r) { return r.json(); });
  await DropCowboy.inbox.init({
    token: minted.token,
    from: '+15125550100'
  });
  DropCowboy.inbox.setTheme({ theme: 'LIGHT', primaryColor: '#009efb' });
  DropCowboy.inbox.addTaskListener(function (event) {
    highlightCrmContact(event);
  });
  await DropCowboy.inbox.openInbox({ container: '#inbox-slot' });
})();
</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-shared-inbox from="+15125550100"></dc-shared-inbox>