Building Blocks / Contacts & Pipeline

Contacts & Pipeline

Open a contact card, timeline, and pipeline stage.

Drop-in widget. Load https://webforms.dropcowboy.com/latest/dropcowboy-contacts.min.js and pass it a site token your server mints. Do not rebuild the contact timeline or the pipeline board; the widget already does it.

When to use this vs REST

Use Contacts and Pipeline to show a Drop Cowboy® contact card, timeline, and stage in your app. Use REST to sync contacts in bulk.

Do not rebuild

The contact timeline (calls, texts, voicemails).
Pipeline boards and drag and drop.

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: ['contacts'], 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":["contacts"],"ttl_seconds":900}'

Load the script, init with the token, and call a method:

<script src="https://webforms.dropcowboy.com/latest/dropcowboy-contacts.min.js"></script>
<div id="contact-slot"></div>
<script>
(async function () {
  const minted = await fetch('/dropcowboy/token', { method: 'POST' }).then(function (r) { return r.json(); });
  await DropCowboy.contacts.init({ token: minted.token });
  DropCowboy.contacts.setTheme({ theme: 'LIGHT', primaryColor: '#009efb' });

  async function showContact(dcContactId) {
    await DropCowboy.contacts.openContact(dcContactId);
  }

  document.getElementById('contacts').addEventListener('click', function (e) {
    var row = e.target.closest('[data-dc-contact-id]');
    if (row) showContact(row.getAttribute('data-dc-contact-id'));
  });
})();
</script>

JS API / HTML tag

Method	What it does
`init({ token })`	Site token with contacts scope.
`setTheme({ theme, primaryColor })`	LIGHT/DARK plus accent.
`openContact(contactId)`	Loads the card and timeline for that contact.
`openBoard(boardId)`	Opens a pipeline board.
`createContact(input)`	Creates a contact from the host CRM payload.
`setDisposition(contactId, disposition)`	Writes a call/SMS disposition onto the contact.
`moveCard(contactId, fromListId, toListId)`	Moves the contact between pipeline lists.

HTML tag:

<dc-contact-card contact-id="6c7d8e9f-0a1b-4c2d-8e3f-4a5b6c7d8e9f"></dc-contact-card>

Auth and scopes

Site token with the contacts scope. Your API secret stays on your server.

Site token scope: contacts. 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.
Map each of your records to a Drop Cowboy contact id before you open it.

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

GET /contact/public/contacts
POST /contact/public/contacts
POST /phone/public/embed/token - mint the site token

Full reference: Embed site tokens, Contacts 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 Contacts & Pipeline

<script src="https://webforms.dropcowboy.com/latest/dropcowboy-contacts.min.js"></script>
<div id="contact-slot"></div>
<script>
(async function () {
  const minted = await fetch('/dropcowboy/token', { method: 'POST' }).then(function (r) { return r.json(); });
  await DropCowboy.contacts.init({ token: minted.token });
  DropCowboy.contacts.setTheme({ theme: 'LIGHT', primaryColor: '#009efb' });

  async function showContact(dcContactId) {
    await DropCowboy.contacts.openContact(dcContactId);
  }

  document.getElementById('contacts').addEventListener('click', function (e) {
    var row = e.target.closest('[data-dc-contact-id]');
    if (row) showContact(row.getAttribute('data-dc-contact-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: ['contacts'], 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":["contacts"],"ttl_seconds":900}'

HTML tag

<dc-contact-card contact-id="6c7d8e9f-0a1b-4c2d-8e3f-4a5b6c7d8e9f"></dc-contact-card>