Building Blocks / Conversations
Messenger (SMS/MMS/RCS)
Two-way SMS from your app, sent from your business number.
Drop-in widget. Load
https://webforms.dropcowboy.com/latest/dropcowboy-messenger.min.jsand pass it a site token your server mints. Do not rebuild the text thread view or sender selection; the widget already does it.
When to use this vs REST
Use Messenger when a person in your app is having an SMS conversation. Use POST /sms from your server for one-off or automated texts.
Do not rebuild
- A thread view with delivery status.
- Sender number selection and opt-out handling.
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-messenger.min.js"></script>
<script>
(async function () {
const minted = await fetch('/dropcowboy/token', { method: 'POST' }).then(function (r) { return r.json(); });
await DropCowboy.messenger.init({
token: minted.token,
from: '+15125550100'
});
DropCowboy.messenger.setTheme({ theme: 'LIGHT', primaryColor: '#009efb' });
DropCowboy.messenger.addMessageListener(function (event) {
saveSmsToCrm(event.to, event.body, event.sms_id, event.direction);
});
document.getElementById('sms-send').addEventListener('click', function () {
var contact = window.currentContact;
DropCowboy.messenger.sendMessage(contact.phone, {
body: document.getElementById('sms-body').value,
contactId: contact.id,
consentId: contact.consentId
});
});
})();
</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-messenger.js. It covers dropcowboy-messenger.min.js as well, because both names serve the same bytes.
<script src="https://webforms.dropcowboy.com/vX.Y.Z/dropcowboy-messenger.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, consentId }) |
from is your business DID. Optional consentId is used on every send unless overridden. 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. |
sendMessage(to, { body, from, contactId, consentId }) |
Sends SMS. Requires consentId. Returns the queued message. |
addMessageListener(fn) -> stop |
Fires { to, body, sms_id, status, direction } after a send. |
addErrorListener(fn) -> stop |
Fires on send or init errors. |
close() |
Tears down the session. |
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, sendMessage() rejects with status 400 and
detail.code: sms_registration_required; show your user that the number needs registering. - 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 messenger skill teaches an AI coding assistant to add this block to your 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.