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.jsand 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.
# 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}'
- 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>
Pin a version with SRI
/latest/ changes whenever we ship. To pin a release, load the same file from /vX.Y.Z/ and add its Subresource Integrity hash. Each release lists its hashes at https://webforms.dropcowboy.com/vX.Y.Z/building-blocks-manifest.json: take the integrity of the entry whose file is dropcowboy-shared-inbox.js. It covers dropcowboy-shared-inbox.min.js as well, because both names serve the same bytes.
<script src="https://webforms.dropcowboy.com/vX.Y.Z/dropcowboy-shared-inbox.min.js"
integrity="sha384-INTEGRITY_FROM_MANIFEST"
crossorigin="anonymous"></script>
Do not put integrity on a /latest/ URL. The file changes under it and the browser will refuse to run it.
JS API / HTML tag
| Method | What it does |
|---|---|
init({ token, getToken, from }) |
from is the business DID used as caller_id on replies. Optional getToken returns a fresh site token (or { token, expires_at }) from your server; it runs before the token expires and once after a 401. |
setToken(token) |
Swaps in a site token you minted yourself. The next request uses it. |
window event 'dc-session-expired' |
Fires when the token expired and could not be refreshed. Mint a new one and call setToken(). |
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.
- 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. - To text or call back a contact who already gave consent in Drop Cowboy®, turn on "Use existing contact consent" on the Building Blocks page (or POST /register/public/building-blocks/contact-consent) and send contactId. The number must be one of that contact's numbers, and opt-outs, STOP, and Do Not Call still block the send. It is off by default.
- 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.
Related REST
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.
On GitHub: the sample CRM uses this block on its Inbox page, and the simple CRM skill teaches an AI coding assistant to build the same app.
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.