Skip to main content

Manage room links

This example demonstrates how to set and retrieve room invitation or external links in ONLYOFFICE DocSpace using the API. These links provide access to rooms based on specified permissions.

Before you start​

  1. Replace https://yourportal.onlyoffice.com and YOUR_API_KEY with your actual DocSpace portal URL and API key. Ensure you have the necessary data and permissions to perform migration operations.
  2. Before you can make requests to the API, you need to authenticate. Check out the Personal access tokens page to learn how to obtain and use access tokens.
Full example
// Set API base URL
const API_HOST = 'https://yourportal.onlyoffice.com';
const API_KEY = 'your_api_key';

// Headers with API key for authentication
const HEADERS = {
  Authorization: `Bearer ${API_KEY}`,
  'Content-Type': 'application/json',
};

// Step 1: Set a room access link
async function setRoomLink(roomId, accessLevel = 2, expirationDate = null, internal = true, primary = false) {
  const url = `${API_HOST}/api/2.0/files/rooms/${roomId}/links`;
  const body = JSON.stringify({
    access: accessLevel,
    expirationDate,
    internal,
    primary,
  });

  const res = await fetch(url, { method: 'PUT', headers: HEADERS, body });
  if (!res.ok) {
    const text = await res.text();
    console.log(`Room link set failed. Status code: ${res.status}, Message: ${text}`);
    return null;
  }
  return res.json();
}

// Step 2: Retrieve all links for a room
async function getRoomLinks(roomId) {
  const url = `${API_HOST}/api/2.0/files/rooms/${roomId}/links`;
  const res = await fetch(url, { method: 'GET', headers: HEADERS });
  if (!res.ok) {
    const text = await res.text();
    console.log(`Room link set failed. Status code: ${res.status}, Message: ${text}`);
    return null;
  }
  return res.json();
}

// Run example
(async () => {
  try {
    const roomId = '123456'; // Replace with your actual room ID

    const setResp = await setRoomLink(roomId, 2, null, true, false);
    console.log('Link set:', setResp);

    const links = await getRoomLinks(roomId);
    console.log('Links:', links);
  } catch (err) {
    console.error(err.message);
  }
})();

A PUT request is sent to /api/2.0/files/rooms/:roomId/links with:

  • access: Access level (e.g., 2 for editing).
  • expirationDate: Optional expiration date (ISO 8601 format).
  • internal: Indicates if the link is internal.
  • primary: Marks the link as primary if true.
async function setRoomLink(roomId, accessLevel = 2, expirationDate = null, internal = true, primary = false) {
  const url = `${API_HOST}/api/2.0/files/rooms/${roomId}/links`;
  const body = JSON.stringify({
    access: accessLevel,
    expirationDate,
    internal,
    primary,
  });

  const res = await fetch(url, { method: 'PUT', headers: HEADERS, body });
  if (!res.ok) {
    const text = await res.text();
    console.log(`Room link set failed. Status code: ${res.status}, Message: ${text}`);
    return null;
  }
  return res.json();
}

A GET request is sent to the same endpoint to retrieve all configured room links.

async function getRoomLinks(roomId) {
  const url = `${API_HOST}/api/2.0/files/rooms/${roomId}/links`;
  const res = await fetch(url, { method: 'GET', headers: HEADERS });
  if (!res.ok) {
    const text = await res.text();
    console.log(`Room link set failed. Status code: ${res.status}, Message: ${text}`);
    return null;
  }
  return res.json();
}