Sending basics

Four routes each send one message to one person. Use them when something happens in your system: an order ships, a form comes in, an appointment is booked. To send to a whole list, use Campaigns. For email, see Email.

All four answer 202 when the request is queued. The recipient, consent, calling hours and your balance are checked after that, so a 202 doesn't mean the message went out. See What a 202 means.

Choose a recipient

Give one of these:

If you send both, we use to and ignore contact_id. Send contact_id when you want merge fields filled in: a send to to has no contact data to merge.

When the recipient can't be resolved, the send fails after the 202. The reason and reason_code arrive on your callback_url and the status webhook:

Fields every send accepts

Send an Idempotency-Key header on every send so a retry can't send twice. See Retry safely with Idempotency-Key.

Merge fields

With contact_id, {{ }} tokens are filled from the contact before sending. Tokens work in body on texts, tts_body on ringless voicemail, and the tts_on_* fields on voice broadcasts.

Add a default after | for when the field is empty: {{contact.first_name|there}}. Put a default with spaces in quotes: {{contact.company|"your company"}}. A token with no value and no default becomes empty, so give every token a default.

Square brackets with / pick one option at random per message: [Hi/Hello/Hey] {{contact.first_name|there}}. This works in texts and spoken text, not in RCS templates.

Act on the result

Each send ends in one status webhook: contact.rvm.status for ringless voicemail, voice broadcasts and AI calls, or contact.sms.status for texts. Branch on data.reason_code. The full list is in Outcomes.

These handlers verify the signature, answer quickly, then act on the code. Subscribe them to contact.rvm.status and contact.sms.status; see Webhooks. Signature checks are explained in Verify the signature.

Node.js (Express)

Node 18 or later. Set DC_KEY, DC_SECRET, DC_SIGNING_SECRET and DC_PHONE_LINE_ID.

const express = require('express');
const crypto = require('crypto');

const API = 'https://api-v2.dropcowboy.com';
const NOT_ALLOWED = [4016, 4017, 6005, 6011];

function apiHeaders(idempotencyKey) {
  const headers = { 'x-key': process.env.DC_KEY, 'x-secret': process.env.DC_SECRET, 'Content-Type': 'application/json' };
  if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
  return headers;
}

function verified(req) {
  const ts = req.get('X-Timestamp');
  const sig = req.get('X-Signature') || '';
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.DC_SIGNING_SECRET)
    .update(ts + '.').update(req.body).digest('hex');
  return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

async function canText(contactId) {
  const res = await fetch(`${API}/contact/public/contacts/${contactId}/consent`, { headers: apiHeaders() });
  if (!res.ok) return false;
  const { data } = await res.json();
  const latest = data.find(r => ['sms_optin', 'sms_optin_confirmed', 'sms_optout'].includes(r.consent_type));
  return Boolean(latest) && latest.consent_type !== 'sms_optout' && latest.consent_status === 'granted';
}

async function handle({ data }) {
  const code = data.reason_code;
  if (code === 0) return console.log('sent', data.drop_id);
  if ((code === 4001 || code === 4002) && data.contact_id && await canText(data.contact_id)) {
    await fetch(`${API}/sms`, {
      method: 'POST',
      headers: apiHeaders(data.drop_id),
      body: JSON.stringify({
        contact_id: data.contact_id,
        phone_line_id: process.env.DC_PHONE_LINE_ID,
        body: 'We tried to leave you a voicemail. Reply here if texting is easier.'
      })
    });
    return;
  }
  if (code === 4005 || code === 4006) return console.log('retry later', data.contact_id);
  if (NOT_ALLOWED.includes(code)) return console.log('stop contacting', data.contact_id);
  if (code >= 3000 && code < 4000) return console.error('fix setup', code, data.reason);
}

const app = express();
app.post('/webhooks/dropcowboy', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verified(req)) return res.sendStatus(401);
  res.sendStatus(200);
  handle(JSON.parse(req.body)).catch(err => console.error(err));
});
app.listen(3000);

Python (Flask)

Uses requests. Set the same environment variables.

import hashlib, hmac, os, time
import requests
from flask import Flask, request, abort

API = "https://api-v2.dropcowboy.com"
HEADERS = {"x-key": os.environ["DC_KEY"], "x-secret": os.environ["DC_SECRET"]}
NOT_ALLOWED = {4016, 4017, 6005, 6011}
app = Flask(__name__)

def verified(raw, headers):
    ts, sig = headers.get("X-Timestamp", ""), headers.get("X-Signature", "")
    if not ts or abs(time.time() - int(ts)) > 300:
        return False
    expected = "sha256=" + hmac.new(os.environ["DC_SIGNING_SECRET"].encode(),
                                    ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)

def can_text(contact_id):
    res = requests.get(f"{API}/contact/public/contacts/{contact_id}/consent", headers=HEADERS, timeout=3)
    if not res.ok:
        return False
    types = ("sms_optin", "sms_optin_confirmed", "sms_optout")
    latest = next((r for r in res.json()["data"] if r["consent_type"] in types), None)
    return bool(latest) and latest["consent_type"] != "sms_optout" and latest["consent_status"] == "granted"

@app.post("/webhooks/dropcowboy")
def webhook():
    if not verified(request.get_data(), request.headers):
        abort(401)
    data = request.get_json()["data"]
    code = data["reason_code"]
    if code == 0:
        print("sent", data["drop_id"])
    elif code in (4001, 4002) and data.get("contact_id") and can_text(data["contact_id"]):
        requests.post(f"{API}/sms", timeout=3,
                      headers={**HEADERS, "Idempotency-Key": data["drop_id"]},
                      json={"contact_id": data["contact_id"],
                            "phone_line_id": os.environ["DC_PHONE_LINE_ID"],
                            "body": "We tried to leave you a voicemail. Reply here if texting is easier."})
    elif code in (4005, 4006):
        print("retry later", data["contact_id"])
    elif code in NOT_ALLOWED:
        print("stop contacting", data["contact_id"])
    elif 3000 <= code < 4000:
        print("fix setup", code, data["reason"])
    return "", 200

Using drop_id as the Idempotency-Key means a repeated webhook delivery can't send the follow-up text twice. Answer within 5 seconds: if your follow-up work is slow, put it on a job queue and answer first.

A contact with no consent record for texting gets no text from these handlers. Record consent when a contact agrees; see Consent.

---

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.