Put WOCOM Meet inside your product

Quick start

Three requests: prove your key works, create a meeting, get someone in.

1. Get a key

   Keys are issued by an operator on the server. Ask whoever runs your WOCOM Meet instance, and tell them what the integration is for and which scopes it needs — they run:

   php artisan meet:api-token issue \
       --tenant=your-tenant \
       --name="Billing portal" \
       --user=you@example.com \
       --scopes=meetings:* --scopes=join:create

   The secret is shown once and stored hashed. Nobody can print it again, including the person who issued it — if it is lost, it is reissued.

2. Check it

   curl -H "Authorization: Bearer $WOCOM_KEY" \
        https://example.com/api/v1/me

   Comes back with your tenant, your scopes and the limits a meeting runs under.

3. Create a meeting and get a link

   curl -X POST https://example.com/api/v1/meetings \
        -H "Authorization: Bearer $WOCOM_KEY" \
        -H "Content-Type: application/json" \
        -d '{"title": "Kickoff call"}'

   The response carries a join_url. Send it to whoever should attend — that is the whole integration for most people. Read on if you want them inside your interface instead.

Authentication

Every request carries a bearer token. There is no session, no cookie and no CSRF token to fetch first.

Authorization: Bearer wocom_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A key belongs to a tenant, and everything it can see or change belongs to that tenant. No endpoint takes a tenant id — there is nothing to pass, and therefore nothing to tamper with.

Scopes

Ask for the narrowest set that does your job.

meetings:* covers every verb on meetings. * covers everything.

Request & response shape

Success is always wrapped in data. Lists add meta.

{
  "data": [ { "code": "wocom-abc-def", "title": "Kickoff call" } ],
  "meta": { "page": 1, "per_page": 25, "total": 1, "pages": 1 }
}

Failure is always wrapped in error.

{
  "error": { "code": "insufficient_scope",
             "message": "This token does not carry the 'meetings:write' scope." }
}

• Timestamps are ISO-8601 with an offset, always. Send them the same way.
• Meetings are addressed by their code (wocom-abc-def), not their id.
• PATCH changes only the fields you send.
• Rate limit: 120 requests per minute per key.

Meetings

Creating

POST /api/v1/meetings

{
  "title": "Q3 Partner Review",
  "starts_at": "2026-09-01T14:00:00-05:00",
  "duration_minutes": 45,
  "lobby_enabled": true,
  "pin": "4821",
  "owner_email": "you@example.com",
  "guests": ["alex@example.com"]
}

Leave out starts_at for an instant meeting — one that is joinable now and stays joinable. That is usually what you want when a call is already happening and you are making a room for it. Everything else is optional; owner_email defaults to the user your key was issued for.

On PATCH, sending "starts_at": null turns a scheduled meeting back into an instant one.

Filtering the list

from and to (ISO-8601, against starts_at), type, q, per_page, page.

Instant meetings have no start time, so a date range would drop them without saying so. They are included by default — pass include_instant=0 if you genuinely only want the diary.

Deleting

Removes the booking and its recordings. Anyone currently in the call stays in it — cancelling a booking and hanging up on people are different acts, and this is the first one.

Joining a meeting

Three ways in, and the right one depends on who is arriving.

POST /api/v1/meetings/wocom-abc-def/join

{ "name": "Alex Chen" }

→ {
  "data": {
    "token":      "eyJhbGciOi...",
    "server_url": "wss://sfu.example.com",
    "room":       "t_019fe..._wocom-abc-def",
    "identity":   "api:JjZZmwj93SwD",
    "is_host":    false,
    "waiting":    false,
    "expires_at": "2026-08-12T00:08:00+00:00"
  }
}

Using the token in a browser

import { Room } from 'livekit-client';

// Minted by YOUR server, which is where the API key lives.
const { token, server_url } = await fetch('/your-backend/meeting-token')
  .then(r => r.json());

const room = new Room();
await room.connect(server_url, token);
await room.localParticipant.enableCameraAndMicrophone();

Participants

Read live from the media server, which is the only thing that knows who is actually connected. If nobody is in the meeting you get 409 — that is a state, not a mistake.

admit releases someone from the lobby. mute affects audio only, and there is no unmute: a server that can switch on a microphone in a room somebody is sitting in is not a feature we are willing to ship.

Recordings

Recording happens on the server: a recorder joins the room, renders it, and writes one file. It does not depend on anyone's laptop staying awake.

Recording is included for every tenant. Recordings are deleted after 30 days.

Errors

Recipes

Click-to-meet from a phone system or CRM

Make a room for a call that is already happening, and hand both sides a link.

$meeting = $http->post("$base/meetings", [
    'title'         => "Call with {$customer->name}",
    'mute_on_entry' => false,
])['data'];

// Agent goes straight in; customer gets the link by SMS.
$sms->send($customer->mobile, "Join the video call: {$meeting['join_url']}");

An embedded room, with your own controls

// On your server — the key never leaves it.
$access = $http->post("$base/meetings/{$code}/join", [
    'name'     => $user->name,
    'identity' => "crm-user-{$user->id}",   // stable across reloads
    'is_host'  => $user->isAgent(),
    'ttl'      => 300,
])['data'];

return response()->json([
    'token'      => $access['token'],
    'server_url' => $access['server_url'],
]);

Record a call and file it against the customer

$http->post("$base/meetings/{$code}/recording/start");
// ... the meeting happens ...
$http->post("$base/meetings/{$code}/recording/stop");

// Encoding runs on after the room closes, so poll rather than assume.
do {
    sleep(15);
    $rec = $http->get("$base/recordings", ['meeting_code' => $code])['data'][0];
} while (! $rec['playable']);

$file = $http->getRaw($rec['download_url']);   // send the key with this too

A staffed waiting room

// Meeting created with lobby_enabled: true.
foreach ($http->get("$base/meetings/{$code}/participants")['data'] as $p) {
    if ($p['waiting'] && $this->isExpected($p['name'])) {
        $http->post("$base/meetings/{$code}/participants/{$p['identity']}/admit");
    }
}

Rules of the road

• Meeting codes are capabilities. Anyone holding wocom-abc-def can reach the join page. Treat them like unlisted URLs — and when that is not good enough, set a PIN or turn the lobby on.
• Poll for anything asynchronous. Recording completion and lobby admission both finish after the request that started them.
• Store the meeting code, not the join URL. The code is the identity; URLs can change shape.
• Handle 409 as normal life. "Nobody is in the meeting yet" is the usual answer to half these endpoints, not an error to alert on.
• The version is in the path. /api/v1 will not change shape underneath you. Breaking changes arrive as /api/v2, with both running side by side.