Video call

Internal

These endpoints are internal to Hailer and not part of the supported public API.

Video call sessions.

Endpoints

Endpoint	Arguments	Returns
v3.videoCall.decline	discussionId: string	object
v3.videoCall.getStatus	discussionIds: string[]	object
v3.videoCall.getToken	discussionId: string	object
v3.videoCall.join	discussionId: string, options?: { silent?: boolean; requireActiveCall?: boolean; takeOver?: boolean }	object
v3.videoCall.leave	discussionId: string	object
v3.videoCall.ping	discussionId: string	object

v3.videoCall.decline

Description

Decline an incoming video call. Notifies other participants that the user declined.

Parameters

Argument 1 (discussionId, optional): discussionId

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.videoCall.decline', [
  '507f1f77bcf86cd799439011', // discussionId
]);
console.log(result);

Returns

Field	Type	Required	Description
success	boolean	yes

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

v3.videoCall.getStatus

Description

Get video call status for multiple discussions (batch query). devices lists every live participant entry; current marks the caller's own device. A device that registered for push (devices.register) is labelled from that registration: name, client (web, ios or android) and the browser and operatingSystem it registered from. A device without one carries no label fields. otherDeviceActive is true when a web session with a device id has an entry from a different device that pinged within 45 seconds (1.5 ping intervals); it is always false for other clients.

Parameters

Argument 1 (discussionId[], required):

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.videoCall.getStatus', [
  ['507f1f77bcf86cd799439011'],
]);
console.log(result);

Returns

Record<discussionId, object>

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

v3.videoCall.getToken

Description

Get a JWT token for authenticated Jitsi access. Requires user to be a discussion participant with an active call.

Parameters

Argument 1 (discussionId, optional): discussionId

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.videoCall.getToken', [
  '507f1f77bcf86cd799439011', // discussionId
]);
console.log(result);

Returns

Field	Type	Required	Description
token	string	yes
expiresAt	integer	yes

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

v3.videoCall.join

Description

Join a video call in a discussion. Creates the call room if it does not exist. Returns room configuration. When options.silent is true the call starts without an in-app ring/snackbar and without push notifications; the chat system message and join pill still appear so others can join when they notice. When options.requireActiveCall is true the call is NOT created if none is active - the request fails with code NotFound instead. Used by the client ping-recovery path to re-register into an existing call without resurrecting one that has already ended. A web session that reports its device id in the socket handshake (device_id query) has one participant entry per device, labelled with the browser and OS parsed from its user agent; other clients keep one entry per socket. When options.takeOver is true the caller's entries from other devices are ended and each of those devices gets a videoCall.takenOver signal ({ discussionId }) so it tears down without rejoining. takenOver in the result is the number of other-device entries that were ended.

Parameters

Argument 1 (discussionId, optional): discussionId

Argument 2 (object, optional):

Field	Type	Required	Description
silent	boolean	no
requireActiveCall	boolean	no
takeOver	boolean	no

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.videoCall.join', [
  '507f1f77bcf86cd799439011', // discussionId
  {
    silent: false,
    requireActiveCall: false,
  },
]);
console.log(result);

Returns

Field	Type	Required	Description
callId	ObjectId	yes
roomName	string	yes
jitsiDomain	string	yes
isNewCall	boolean	yes
participantCount	integer	yes
takenOver	integer	yes

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

v3.videoCall.leave

Description

Notify that user has left a video call in a discussion. A web session with a device id leaves only its own device's entry, so the user's other devices stay in. Any other client ends the user's first live entry that has no device, as before.

Parameters

Argument 1 (discussionId, optional): discussionId

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.videoCall.leave', [
  '507f1f77bcf86cd799439011', // discussionId
]);
console.log(result);

Returns

Field	Type	Required	Description
success	boolean	yes
participantCount	integer	yes

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.

v3.videoCall.ping

Description

Ping to indicate user is still in a video call. Updates lastSeen for stale participant cleanup. A web session with a device id refreshes only its own device's entry (NotFound once it was ended, e.g. taken over); any other client refreshes the user's first live entry that has no device, as before.

Parameters

Argument 1 (discussionId, optional): discussionId

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.videoCall.ping', [
  '507f1f77bcf86cd799439011', // discussionId
]);
console.log(result);

Returns

Field	Type	Required	Description
success	boolean	yes

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, retryAfter?, debug? }. retryAfter is a delay in milliseconds.