Macros or AI functions? Understanding ONLYOFFICE Tools

ONLYOFFICE gives you powerful ways to automate your document work using macros and AI functions — helping you save time, reduce manual effort, and work more efficiently.

Both help you work faster and smarter, but they work differently and fit different needs. Whether you’re a developer building custom solutions or just someone who wants to work more efficiently, this guide will help you pick the right tool for your needs

Understanding the basics

What are ONLYOFFICE macros?

ONLYOFFICE macros are small scripts that automate repetitive tasks in documents, spreadsheets, and presentations. They use JavaScript and the Office API, letting you format content, update data, and build custom workflows directly in the editor.

How to use Macros:

1. Open the View tab and click Macros
2. Write JavaScript code using the Office API
3. Click Run to execute the macro.
4. The script manipulates the document directly

Note! Since version 7.1, macros run in strict mode. This means you must declare all variables with let or const before using them. You can’t use window, document, or alert functions.
Example: Color table rows

(function () {
  let worksheet = Api.GetActiveSheet();
  for (let i = 1; i < 200; i += 2) {
    let rowOdd = i,
      rowEven = i + 1;
    worksheet.GetRange(
      "A" + rowOdd + ":S" + rowOdd).SetFillColor(Api.CreateColorFromRGB(138, 181, 155)
      );
    worksheet.GetRange(
      "A" + rowEven + ":S" + rowEven).SetFillColor(Api.CreateColorFromRGB(216, 227, 220)
      );
  }
})();

This macro colors 200 rows alternately in less than a second – a task that would take some time to do manually.

What are ONLYOFFICE AI functions?

AI functions connect ONLYOFFICE to AI models like ChatGPT. They let you run AI‑driven document actions using prompts, so the editor can perform automated operations based on your request. AI functions are part of the AI plugin (currently in beta), introduced in version 2.4.2.

Setup

1. Clone the onlyoffice.github.io repository to your local machine.
2. Write your AI function in the helpers folder (sdkjs-plugins/content/ai/.dev/helpers).
3. Depending on the editor type, place it in the cell, slide, or word folder.
4. Update the current version of the AI plugin in config.js to avoid caching issues
   (for example, 3.0.3 → 3.0.4).
5. Run the helpers.py file.
6. Select all plugin files in the ai folder (sdkjs-plugins/content/ai), zip them, and rename the archive to ai.plugin.
7. Place the file back into sdkjs-plugins/content/ai/deploy.
8. Push the changes.
9. Build your GitHub Pages site from this repository (see the GitHub Pages documentation).
10. Prepare a link to your custom store by appending /store/index.html to your GitHub Pages URL:
    https://YOUR-USERNAME.github.io/onlyoffice.github.io/store/index.html
11. Go to Plugins → Plugin Manager.
12. Click the Store (</>) icon in the top-right corner of the Plugin Manager and enter your custom store URL.
13. Update the AI plugin.

Note! For more detailed instructions visit this article.

How to use AI functions

1. Configure your AI provider and API Key if needed.
2. Press Ctrl + / to open the AI chat.
3. Type what you want (like “Explain this text”).
4. The AI selects the right function and does the work.
5. The result appears in your document.

AI functions remember your conversation. You can ask follow-up questions or refine results. Press Ctrl + Alt + / to start fresh.

Example: Add AI comments

The commentText function adds smart comments to the selected text:

1. Select some text in your document.
2. Press Ctrl + / to open the AI chat.
3. Type: “Explain this text”.
4. Press Enter.

The AI reads your text, generates an explanation, and adds it as a comment in your document.

Here’s how it works behind the scenes:

// Simplified structure of an AI Function
func.call = async function (params) {
  // 1. Get the selected text
  let text = await Asc.Editor.callCommand(function () {
    let doc = Api.GetDocument();
    let range = doc.GetRangeBySelect();
    return range ? range.GetText() : "";
  });
  // 2. Ask the AI model
  let requestEngine = AI.Request.create(AI.ActionType.Chat);
  let argPrompt = params.prompt + ":\n" + text;
  // 3. Add the AI's answer as a comment
  await requestEngine.chatRequest(argPrompt, false, async function (data) {
    await Asc.Editor.callCommand(function () {
      let doc = Api.GetDocument();
      let range = doc.GetRangeBySelect();
      range.AddComment(data, model, "uid" + model);
    });
  });
};

You can see the full commentText function code here.

Why AI functions are more flexible

AI functions invoke CallCommand separately (see lines in the code above), which lets you execute custom logic before and after document operations. This makes them perfect for AI integration – you can send requests to the AI model, process the response, and then update the document. The Macros app wraps everything within CallCommand, which is simpler but less flexible.

Main differences

Macros are for direct, offline document manipulation. AI functions are for integrating AI models with ONLYOFFICE.

Here’s how they compare:

Aspect	Macros	AI Functions
Setup	Easy – already built in	More complex – AI provider setup + custom functions
Cost	Free	Paid (AI provider charges)
Internet	Works offline	Requires a connection to an AI service
Prerequisites	JavaScript + Office API	JavaScript + Office API + AI agent modifications
Learning Curve	Steep for non-programmers	Steep for non-programmers
Result Consistency	Always the same output	May vary
Flexibility	Limited – wrapped in CallCommand	More flexible – invoke CallCommand separately
Performance	Fast – direct execution	Variable – depends on AI response time
Version Support	Available since early versions	Beta (since v2.4.2)
Best for	Developers, precise control, offline automation	AI-assisted tasks, document operations, and processing
Privacy	Local execution only	Data sent to an external AI service

When to use each tool

Macros

Pick macros when you need to manipulate documents directly:

• Offline work – no internet connection required.
• No cost – automate as much as you want for free.
• Direct document operations – formatting, data manipulation, calculations.
• Exact results – same input always gives same output.
• Fast prototyping – write code and test immediately in the editor.
• Production work – financial reports, compliance docs, automated workflows.

AI functions

Choose AI functions when your automation needs AI capabilities:

• AI model integration – connect to AI services and use their output.
• Document automation –  apply AI results directly to the document.
• Context processing – handle content with awareness of selection or document structure.
• Advanced logic – need flexibility to execute custom code before/after document operations.

Conclusion

ONLYOFFICE macros and AI functions serve different purposes. The key distinction is simple:

Macros are for direct document manipulation. They’re free, work offline, and perfect for any automation that doesn’t need AI. Use them for formatting, calculations, data manipulation, and custom formulas.

AI functions are for integrating AI models with ONLYOFFICE. They’re more complex to develop than macros, require internet and AI provider costs, but they’re the right choice when you need AI capabilities. Use them for generating content, document processing, and automating document tasks with AI.

ONLYOFFICE keeps improving both tools. Macros are getting new features like async functions. AI functions are moving out of beta with better reliability and more capabilities. Understanding both gives you the full power of ONLYOFFICE automation.