Go back to dialerseat.comsales@dialerseat.com
Start here

Tutorial: an HTML dialer, from nothing to paid

Put the DialerSeat dialer on an ordinary HTML page, test it with no calls placed, take your first customer's payment, and switch on live dialing.


This walks one plain HTML page from nothing to a dialer your customers pay for. You need a web server you can add one route to (the example uses Node and Express; any language works the same way) and about thirty minutes. Nothing in steps 1 to 6 costs anything or places a real call.

Two kinds of payment appear here. Your customers pay you, in your own checkout, at your own price. You pay DialerSeat its cut of that, from your balance. Your customers never see a DialerSeat bill.

1. Make a project

Sign in at dev.dialerseat.com with any DialerSeat login, choose Activate developer account, and answer the short survey about what you are building. Pick Script tag when it asks how the dialer goes in. You land on Setup with your sandbox keys. Copy the secret key (dsk_test_...) now: it is shown once.

Put it in your server's environment, never in a web page:

.env
DIALERSEAT_SECRET_KEY=dsk_test_...

2. Allow your page's address

The dialer only opens inside pages you list. In the console, open Miniplayer, then Allowed origins, and add the address your page is served from, for example http://localhost:3000 while you build. Add your real domain and any staging domain later.

3. One route on your server

Your page asks your server for a dialer session; your server asks DialerSeat. The route makes sure the signed-in user has a seat (keyed on your own user id, so calling it again is safe), then opens a one-use, 15-minute session for them. It can also say what this person may dial.

server.js (Node 18+, Express)
import express from 'express'

const app = express()
const DS = 'https://api.dialerseat.com/v1'
const headers = {
  Authorization: `Bearer ${process.env.DIALERSEAT_SECRET_KEY}`,
  'Content-Type': 'application/json',
}

// Your own sign-in decides who this is. req.user is whatever your app uses.
app.post('/your-server/dialer-session', async (req, res) => {
  const user = req.user
  if (!user) return res.status(401).end()

  // 1. The user's seat: created the first time, updated after that.
  const seat = await fetch(`${DS}/seats`, {
    method: 'POST', headers,
    body: JSON.stringify({ external_user_id: user.id, name: user.name, email: user.email }),
  }).then(r => r.json())

  // 2. A session for this one dialer, with the leads to work.
  const session = await fetch(`${DS}/seats/${seat.id}/sessions`, {
    method: 'POST', headers,
    body: JSON.stringify({
      leads: [
        { external_id: 'c_5501', first_name: 'Dana', last_name: 'Ruiz', phone: '+15125550142', state: 'TX' },
        { external_id: 'c_5502', first_name: 'Marcus', last_name: 'Lee', phone: '+12145550183', state: 'TX' },
        { external_id: 'c_5503', first_name: 'Priya', last_name: 'Shah', phone: '+17135550117', state: 'TX' },
      ],
    }),
  }).then(r => r.json())

  res.json({ token: session.token })
})

app.use(express.static('public'))
app.listen(3000)

In a real app the leads come from your database: the contacts this person is working today. Up to 500 per session.

4. The page

One script tag and one element. The element asks your route from step 3 for a session by itself, with the visitor's cookies, so the page has no JavaScript of its own. Your publishable key (dpk_test_...) is under API keys; it is safe in a page.

public/index.html
<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Calls</title>
    <script src="https://dev.dialerseat.com/embed/v1.js" data-key="dpk_test_..."></script>
  </head>
  <body>
    <h1>Today's calls</h1>
    <dialerseat-dialer id="dialer" session-url="/your-server/dialer-session" height="680"></dialerseat-dialer>
  </body>
</html>

Open the page. You see the dialer: the same one dialerseat.com runs, in DialerSeat's colors (step 9 puts yours on it). Press SET AVAILABLE, then INITIATE DIAL SEQUENCE.

5. Watch it work, with nothing dialed

In sandbox mode no call is placed. Each call plays out by the last digit of the number, so you can make every path happen on purpose:

  • Ending in 0–6: A person answers
  • Ending in 7: Voicemail answers (AMD: machine)
  • Ending in 8: Rings out, no answer
  • Ending in 9: Busy

The leads above end in 2, 3 and 7: Dana and Marcus answer, Priya reaches voicemail. When a person answers, the lead's card and your script come up; press TERMINATE CALL, pick an outcome, and the dialer moves to the next lead by itself. Voicemail never reaches the agent: it is detected, hung up and the queue moves on.

6. Get the results on your server

In the console, open Webhooks and add an endpoint on your server, choosing call.dispositioned (or every event). Each delivery is signed; verify it, then write the outcome onto your record by its external_id.

server.js, continued
import crypto from 'node:crypto'

app.post('/webhooks/dialerseat', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('DialerSeat-Signature') || ''
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')))
  const expected = crypto.createHmac('sha256', process.env.DIALERSEAT_WEBHOOK_SECRET)
    .update(`${parts.t}.${req.body}`).digest('hex')
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300
  if (!fresh || !parts.v1 || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))) {
    return res.status(400).end()
  }
  const event = JSON.parse(req.body)
  if (event.type === 'call.dispositioned') {
    // event.data.call.lead.external_id is your contact; event.data.disposition.code your outcome
    saveOutcome(event.data.call.lead.external_id, event.data.disposition.code, event.data.notes)
  }
  res.status(200).end()
})

Press Send test event on the endpoint to check your signature code before a real call ever happens.

7. Your customer pays you

Charge your customers however you already do, at your own price. Each time one pays you, tell DialerSeat, and their seat dials for exactly the period they paid for. Either call the API where your billing confirms a payment:

bash
curl https://api.dialerseat.com/v1/subscriptions \
  -H "Authorization: Bearer $DIALERSEAT_SECRET_KEY" \
  -H "Idempotency-Key: invoice_8841" \
  -H "Content-Type: application/json" \
  -d '{ "external_user_id": "usr_829", "external_subscription_id": "sub_829", "amount": 4900, "currency": "usd", "interval": "month" }'

or, if you bill on Stripe, forward your Stripe webhook instead and write no code (Billing in the console shows the three clicks). Canceling keeps the days already paid for. In sandbox mode, Simulate a signup on the Billing page does this for you.

8. You pay DialerSeat, and go live

On the Billing page, choose Request live dialing. Sales agrees your rate with you at sales@dialerseat.com, priced by the dial modes your users need and your volume. Then:

  • Live dialing is switched on for your project. Make live keys under API keys and switch Sandbox mode off in Settings.
  • Put the live secret key on your server and the live publishable key on your page, and add your real domain under Allowed origins.
  • Each payment you report from then on records DialerSeat's cut on your balance. The Billing page shows every signup, renewal and payment, and you pay the balance by card there. GET /v1/balance returns the same figures.

Nothing dials for real until live dialing is on, and a seat whose paid days ran out shows its user why instead of dialing.

9. Make it yours

  • Your brand: under Miniplayer, design your name, logo and colors against a live preview. Putting them on your users' dialers is a premium add-on arranged with sales.
  • Your outcomes: under Dispositions, the buttons agents press after a call, by your own codes.
  • Who dials what: teams, roles and campaigns, so each person sees only their own lists (Teams and access).
  • Parts of the dialer anywhere on the page: <dialerseat-callbar>, <dialerseat-queue>, a manager's <dialerseat-team> board (Components).
  • Click to call: data-dialerseat-call="+15125550142" on any link in your CRM.

Related:Quickstart, Developer accounts, Authentication and API keys and Ways to put the dialer in.