Joining a call

When a booked call is about to start, the patient joins it from your website and stays on your page. You add one script and one backend route. The script shows the Bespoke call page inside your page and hands it a single-use ticket. The call page does the rest: it checks the patient's microphone (and camera, for a video call), waits until the prescriber lets the patient in, and runs the call.

Overview

• The address bar stays on your website. The call page shows no Bespoke branding and sets no cookies. You can match it to your colours.
• A video call asks for the camera and microphone, an audio call for the microphone only.
• The patient waits in a waiting room until the prescriber lets them in.
• A call can be joined from 10 minutes before it starts until 30 minutes after its booked end (the join window). A call the patient or the prescriber entered in time is not cut off then: it stays open for 60 more minutes, so a patient waiting for a prescriber who runs late still gets the call. After that the call closes for everyone.
• If the patient leaves or loses the connection, they can rejoin from the same page while the call is open, without a new ticket.
• What the call page reports to your page carries no patient data.

Before you start

Quick start

This is the whole of your page. /your-backend/call-ticket is your own route.

<button id="join">Join your visit</button>
<div id="call"></div>

<script src="https://a-nirwan.bespoke-consults.designingit.co/video/embed.js"></script>
<script>
  async function getTicket() {
    const response = await fetch('/your-backend/call-ticket', { method: 'POST' });
    if (!response.ok) throw new Error('No ticket');
    return (await response.json()).ticket;
  }

  document.getElementById('join').addEventListener('click', () => {
    BespokeCall.mount(document.getElementById('call'), {
      callPageUrl: 'YOUR_CALL_PAGE_URL',
      getTicket,
      onEnd: () => { /* show the patient your next step */ },
    });
  });
</script>

• YOUR_CALL_PAGE_URL is call_page_url from any ticket response. It is the same for every call on your account, so keep it in your settings.
• Give #call a height in your styles. The call fills it, and needs at least 600px; on a phone, use most of the screen.
• Show the button only inside the join window: from 10 minutes before the call's starts_at.

Your backend route

The route asks Bespoke for a ticket with your API key, which stays on your server, and returns it to your page. Your page calls it each time the call page needs a ticket.

PHP

<?php
// POST /your-backend/call-ticket
// Your own login check decides which consultation this patient may join.
$consult = your_logged_in_patients_consult();

$request = curl_init('https://a-nirwan.bespoke-consults.designingit.co/v1/visits/' . rawurlencode($consult) . '/video/patient-ticket');
curl_setopt_array($request, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-Api-Key: ' . getenv('BESPOKE_KEY'),
        'X-Api-Secret: ' . getenv('BESPOKE_SECRET'),
        'X-Source-Domain: your-site.example',
    ],
]);
$body = json_decode((string) curl_exec($request), true) ?: [];
$status = curl_getinfo($request, CURLINFO_HTTP_CODE);

header('Content-Type: application/json');
header('Cache-Control: no-store');

if ($status !== 201) {
    http_response_code($status ?: 502);
    echo json_encode([
        'error' => $body['error']['code'] ?? 'api_error',
        'join_window' => $body['join_window'] ?? null,
    ]);
    exit;
}

echo json_encode(['ticket' => $body['ticket']]);

Node

With Express and Node 18 or later. requireLogin is your own login check.

app.post('/your-backend/call-ticket', requireLogin, async (req, res) => {
  // Your own login decides which consultation this patient may join.
  const consult = req.user.consultId;

  const api = await fetch(`https://a-nirwan.bespoke-consults.designingit.co/v1/visits/${encodeURIComponent(consult)}/video/patient-ticket`, {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      'X-Api-Key': process.env.BESPOKE_KEY,
      'X-Api-Secret': process.env.BESPOKE_SECRET,
      'X-Source-Domain': 'your-site.example',
    },
    signal: AbortSignal.timeout(15000),
  });
  const body = await api.json();

  res.set('Cache-Control', 'no-store');

  if (api.status !== 201) {
    return res.status(api.status).json({
      error: body.error?.code ?? 'api_error',
      join_window: body.join_window ?? null,
    });
  }

  res.json({ ticket: body.ticket });
});

X-Source-Domain is one of your registered websites, without https://. A 403 origin_not_allowed means this website or your server's source IP is not registered yet.

The script

https://a-nirwan.bespoke-consults.designingit.co/video/embed.js gives your page BespokeCall.mount(element, options), which adds the call inside element and returns { destroy() }. Load it from this address rather than keeping a copy: fixes then reach you by themselves.

• If getTicket fails, returns anything but a ticket, or takes more than 30 seconds, the patient sees "We could not open the call" with a "Try again" button, and you get onError('ticket_failed').
• destroy() removes the call from your page and stops the camera and microphone.
• A second mount on an element that already holds a call returns that same call, so a double click does not open two.

The ticket endpoint

POST https://a-nirwan.bespoke-consults.designingit.co/v1/visits/{id}/video/patient-ticket, from your backend, with the usual API headers. {id} is the consultation id or your external_ref. No body.

curl -X POST "https://a-nirwan.bespoke-consults.designingit.co/v1/visits/your-consult-2001/video/patient-ticket" \
  -H "X-Api-Key: $BESPOKE_KEY" \
  -H "X-Api-Secret: $BESPOKE_SECRET" \
  -H "X-Source-Domain: your-site.example"

201:

{
  "ticket": "vt_…",
  "expires_at": "2026-11-05T14:55:00Z",
  "visit_id": "…",
  "appointment_id": "…",
  "modality": "video",
  "join_window": { "opens_at": "2026-11-05T14:50:00Z", "closes_at": "2026-11-05T15:40:00Z" },
  "call_page_url": "https://…/video/call/…"
}

• A ticket works once and for 5 minutes. Get a new one each time the call page needs one, not when the call is booked.
• Asking again gives a new ticket; earlier unused ones still work until they expire.
• call_page_url is the same for every call on your account. The ticket never goes in this URL.

Errors

The codes onError receives. On "Try again" the script gets a new ticket by itself.

Call states

Each state names the screen the patient sees. Use them to update your own page, or just use onEnd.

Your colours

Optional theme, for example { accent: '#0f766e', radius: 12 }. A value that is missing or not valid keeps the default.

Without the script

The script is the simple way. If you would rather write this part yourself, it does only this: an iframe and postMessage.

<iframe id="bespoke-call" title="Your call" allow="camera; microphone"></iframe>

• allow="camera; microphone" is required. Without it the browser blocks the devices and the patient sees "Allow camera and microphone".
• Start listening for messages before you set the iframe's src to your call_page_url, so you do not miss bespoke-call:ready.
• Opened directly, outside an iframe, the page only says to open the call from your website.

Accept messages only from the iframe (event.source) and its origin (the origin of call_page_url), and send only to that origin. The call page accepts your messages only from a registered website, and after the first one talks only to the origin that sent it.

<iframe id="bespoke-call" title="Your call" allow="camera; microphone"></iframe>

<script>
  const callPageUrl = 'YOUR_CALL_PAGE_URL';
  const callOrigin = new URL(callPageUrl).origin;
  const frame = document.getElementById('bespoke-call');

  window.addEventListener('message', async (event) => {
    if (event.source !== frame.contentWindow || event.origin !== callOrigin) return;
    const message = event.data || {};

    if (message.type === 'bespoke-call:ready') {
      const response = await fetch('/your-backend/call-ticket', { method: 'POST' });

      frame.contentWindow.postMessage(response.ok
        ? { type: 'bespoke-call:start', ticket: (await response.json()).ticket }
        : { type: 'bespoke-call:no-ticket' }, callOrigin);
    }

    if (message.type === 'bespoke-call:state' && message.state === 'ended') {
      // Show the patient your next step.
    }
  });

  // Listen first, then load the page.
  frame.src = callPageUrl;
</script>

Integration checklist

1. Ask Bespoke to enable video visits and to register every website that will show the call, and your server's source IPs.
2. Show the patient a "Join" button from 10 minutes before the start. On 409 join_window_closed, show when the call opens.
3. Get tickets from your backend only; your API key never goes to the browser.
4. Take the consultation from the patient's login, never from the browser.
5. Give the call's element a height, at least 600px.
6. On onEnd, show the patient what happens next.
7. Test on your site over https:// with a phone as well as a computer.

← Booked calls API reference →