Build a voice button

Add a Talk to us button to your website, with a small server endpoint that creates calls, in plain JavaScript or React.

By the end of this page a visitor can click a button on your site and talk to one of your agents. You need an account, an API key, and an agent with a voice (see Prompt agents).

Allow your website

Dialgem only starts calls for websites you list. Add the origin your page is served from. While developing, add your local address too.

bash

curl -X PUT https://api.dialgem.com/v1/web-calls/settings \
  -H "X-API-Key: $DIALGEM_API_KEY" -H "Content-Type: application/json" \
  -d '{ "allowed_origins": ["http://localhost:3000", "https://www.example.com"] }'

You can also do this in the dashboard under Settings, Web calls. Until at least one origin is listed, creating a call answers 409 web_origins_not_configured.

Add a server endpoint

Your server creates the call and returns the token. Keep the API key in an environment variable on the server.

import express from "express"
import { Dialgem } from "@dialgem/sdk"

const dialgem = new Dialgem({ apiKey: process.env.DIALGEM_API_KEY })
const app = express()

app.post("/api/start-call", async (req, res) => {
  const { access_token } = await dialgem.webCalls.create({ agent_id: "AGENT_ID" })
  res.type("text").send(access_token)
})

app.listen(3000)

Decide here who is allowed to start a call. Your endpoint is the gate, so check your own session, rate limit it, and never return the token to someone you did not mean to serve.

Add the browser package

bash

npm install @dialgem/client

Wire up the button

import { DialgemCall } from "@dialgem/client"

const call = new DialgemCall({
  accessToken: () => fetch("/api/start-call", { method: "POST" }).then((r) => r.text()),
})

call.on("transcript", (t) => addLine(t.role, t.text, t.final))
call.on("agent_speaking", ({ speaking }) => orb.classList.toggle("talking", speaking))
call.on("ended", ({ reason }) => showEnded(reason))
call.on("error", (e) => showError(e.message))

talkButton.onclick = () => call.start() // must run straight from the click
hangUpButton.onclick = () => call.stop()

The token function runs after the visitor has allowed the microphone, because the token lives only 60 seconds and a permission prompt can take longer.

Try it

Open your page, click the button and allow the microphone. You should see the transcript fill in and hear the agent. Afterwards the call appears in your call list with call_type: "web_call", with its transcript, recording and cost.

If it does not work

You see	Likely cause
`409 web_origins_not_configured` from your server	No website is allowed yet. Do step 1.
`refused` with `origin_not_allowed` in the page	The page's origin is not in the allow-list. Match the scheme, host and port exactly.
The agent connects but is silent	The agent has no `voice_id`. See Voices.
`unsupported`	An old browser, or a Content-Security-Policy that blocks `blob:`.

The full list is in Errors and troubleshooting.

Pass data to the agent

Greet the visitor by name and tag the call with your own ids.

Tokens and allowed websites

How the token and the allow-list keep calls safe.