PostMessage API

PostMessage API is used to interact with parent frame when Collabora Online’s browser part is enclosed in one. This is useful for hosts wanting to integrate Collabora Online in them.

This API is mostly based on WOPI specification with few extensions/modifications. All messages sent are in this form :

{
    "MessageId": "<MessageId>",
    "SendTime": "<Timestamp when message is sent>",
    "Values": {
         "<key>": "<value>"
    }
}

SendTime is the timestamp returned by browsers’ Date.now(). The post messages sent from the WOPI host should also be in same form.

It is to be noted that as mentioned in WOPI specs, Collabora Online frame will ignore all post messages coming from the host frame if Host_PostmessageReady has not been received. Further, since for embedding Collabora Online as an iframe WOPI implementation is a must, it is required that PostMessageOrigin property is present in WOPI host’s CheckFileInfo response. Otherwise, no post messages will be emitted.

Initialization

Editor to WOPI host

MessageId	Values	Description
App_LoadingStatus	Status: <String> DocumentLoadedTime: <Timestamp>	If status is Frame_Ready, Collabora Online frame is loaded and UI can be shown. Accompanying keys: Features: This client’s capabilities. Supported values are: VersionStates. Tells the host that client supports different version states. See Version Restore for more details. When Status is Document_Loaded, document has been completely loaded and host can also start using PostMessage API. Accompanying keys: DocumentLoadedTime. When Status is Failed, document hasn’t been loaded but host can show the Collabora Online frame to present an error for a user. When Status is Initialized, postMessage listener in editor has been initialized. WOPI host can start to send postMessages. It is used to send early postMessages even before Frame_Ready.

WOPI host to editor

MessageId	Values	Description
Host_PostmessageReady		See WOPI docs for detail.

Query

You can query data from the editor using post message API. All responses are returned with query’s MessageId suffixed with ‘_Resp’ as shown below Getters

WOPI Host to Editor

MessageId	Values	Description
Get_Views		Queries the editor for currently active views of the document. Response is returned in form of Get_Views_Resp
Get_Export_Formats		Queries the editor for all the supported export formats for currently opened document. Response is returned in form of Get_Export_Formats_Resp
Get_User_State		Queries the editor for current user activity state (is idle or active). Response is returned in form of Get_User_State_Resp

Getters response

Editor to WOPI host

MessageId	Values	Description
Get_Views_Resp	ViewId: <Number> UserId: <String> UserName: <String> Color: <Number> ReadOnly: <Boolean> IsCurrentView: <Boolean>	Give details of all current views when queried using Get_Views
Get_Export_Formats_Resp	Label: <String> Format: <String>	Response to query Get_Export_Formats. Label would contain a localized string explaining about the format. Format is the file extension of the format which is required while requesting export of the document.
Get_User_State_Resp	State: <String> Elapsed: <Number>	Response to query Get_User_State. State would contain a non-localized string with the activity state (“active” or “idle”). Elapsed is the number of seconds since the last activity of the user.

Session Management

WOPI Host to editor

MessageId	Values	Description
Action_RemoveView	ViewId: <Number>	Remove the session.
Reset_Access_Token	token: <accesstoken>	Reset the access token. The new one will be used from now on.

Editor to WOPI Host

MessageId	Values	Description
View_Added	ViewId: <Number> UserId: <String> UserName: <String> Color: <Number> ReadOnly:<Boolean> Deprecated: true;	A new member is added. ViewId is unique integer identifying a session/view. UserId is user identity. UserName is display name of the user. Color is RGB color integer value. ReadOnly tells if the new view is opened as read-only. This message is deprecated, opened as read-only. This message is deprecated, instead implement just handling of Views_List which holds the same payload as Get_Views_Resp.
View_Removed	ViewId: <Number> Deprecated: true;	View with ViewId has closed the document. This message is deprecated, instead implement just handling of Get_Views_Resp and if you need the info which view has been added / removed, check against the previous state. This message is deprecated, instead implement just handling of Views_List which holds the same payload as Get_Views_Resp.
Session_Closed	Reason: <String>	The session has closed. The reason fied details the origin: OwnerTermination, DocumentIdle, OOM Out-of-memory, ShuttingDown server is shutting down for maintenance, DocumentDisconnected an issue with the document
Views_List	See Get_Views_Resp.	Complete information about the currently connected views.
User_Idle		Indicates that user become idle. It happens after longer inactivity time defined in the configuration file /etc/coolwsd/coolwsd.xml
User_Active		Indicates that user become active again. It happens after user clicked on the idle screen.

Actions

WOPI host to editor

MessageId	Values	Description
Action_Save	DontTerminateEdit: <boolean> DontSaveIfUnmodified: <boolean> Notify: <boolean> ExtendedData: <String>	Saves the document. DontTerminateEdit is relevant for spreadsheets where saving a document can terminate the edit mode (text cursor disappearing). Setting this to true won’t terminate the edit mode and can be used to save document without disrupting user’s editing session in spreadsheets. DontSaveIfUnmodified prevents coolwsd to save the file back to storage if document is unmodified (only cursor position changed etc.) but still saved. This can be helpful to prevent creating unnecessary file revisions. Notify when present and set to true notifies the host when document is saved. See Action_Save_Resp for details. ExtendedData optional data carried over to the WOPI host if provided in the X-COOL-WOPI-ExtendedData header. The contents are preserved as-is, however, care must be taken to avoid using anything that HTTP headers do not allow, also, special values such as new-line, null character, non-printable characters, etc. are not allowed. The client can use this to pass multiple values to the WOPI host which can then act on them.
Action_SaveAs	Filename: <String> Notify: <boolean>	Creates copy of the document with given Filename. Filename is the requested filename for the new file. Notify when present and set to true notifies the host when document is saved. See Action_Save_Resp for details.
Action_FollowUser	Follow: <Boolean> ViewId: <Number>	Turn on or off the follow user feature. When Follow is set to true or is not define set to true or is not enables following the editor, disables following when set to false When Follow is set to true or is not defined ViewId parameter specifies user to follow. When ViewId is not defined, the current editor is followed.
Action_Close		Closes the document.
Close_Session		Allows closing documents before they are completely loaded.
Action_Fullscreen		Switch to fullscreen mode.
Action_FullscreenPresentation	StartSlideNumber: <Number> CurrentSlide: <Boolean>	Start the presentation in Impress. StartSlideNumber optionally specify the starting slide (from 0) If CurrentSlide is true, then the presentation starts from the current slide.
Action_Print		Prints the document.
Action_Export	Format: <String> Notify: <boolean>	Downloads the document in format specified by Format. Format must be from the list returned in Get_Export_Formats. Notify when present and set to true notifies the host when document is saved. See Action_Save_Resp for details.
Action_InsertGraphics	url: <String>	Downloads image from the url and inserts it to the document. This is usually the response to a successful UI_InsertGraphic
Action_InsertMultimedia	url: <String>	Downloads multimedia from the url and inserts it to the document. This may be the response to a successful UI_InsertFile. Since 24.04.10.
Action_ShowBusy	Label: <String>	Shows an in-progress overlay, just like what appears when saving the document, with the given Label.
Action_HideBusy		Hides any in-progress overlay, if present.
Action_ChangeUIMode	Mode: 'classic' | 'notebookbar'	Changes the user interface: Classic Toolbar or Notebookbar.
Action_Paste	Mimetype: <string> Data: <string>	Pastes the data directly to the document bypassing the internal paste mechanism. Example: Values: {Mimetype: "text/plain;charset=utf-8", Data: "foo"}};

WOPI editor to host (Response)

MessageId	Values	Description
Action_Load_Resp	success: <boolean> result: <string> errorMsg: <string> errorType: <string>	Acknowledgment when load finishes. success tells if COOL was able to load the document successfully. result contains the reason the document was not loaded. errorMsg contains a detailed error message in case loading failed. Probably it will contain the error message returned from the WOPI host. errorType contains optional error identifier based on which WOPI host can customize error message.
Action_Save_Resp	success: <boolean> result: <string> errorMsg: <string> fileName: <string>	Acknowledgment when save finishes. This response is only emitted if Notify parameter is mentioned by Action_Save PostMessage API. success tells if COOL was able to save the document successfully. result contains the reason the document was not saved. In case, document was not saved because it was not modified, then this parameter contains the string ‘unmodified’. In this case, WOPI hosts can be sure that there are no changes pending in the document to be saved to the storage. errorMsg contains a detailed error message in case saving failed. Probably it will contain the error message returned from the WOPI host. fileName if success equals true then contains saved file name.
FollowUser_Changed	FollowedViewId: <Number> IsFollowUser: <Boolean> IsFollowEditor: <Boolean>	Notification about current following state. FollowedViewId tells which user is followed. IsFollowUser determines if following the specific user is activated. IsFollowEditor determines if following the editor is activated. If both IsFollowUser and IsFollowEditor are false then following is inactive.
Action_ChangeUIMode_Resp	Mode: <string>	Notification about UI mode switch (Tabbed/Compact) Mode tells which mode will be used.

Version Restore

WOPI host to editor

MessageId	Values	Description
Host_VersionRestore	Status: <string>	The Only possible value is Pre_Restore. This message is sent by the host before actually restoring the document and after user showed the intent to restore the document. This is so such that if there are any unsaved changes, Online can save them to storage before document is restored.

Editor to WOPI host

MessageId	Values	Description
App_VersionRestore	Status: <string>	This is the reply for the Host_VersionRestore message. Possible values for Status (for now) is: Pre_Restore_Ack. It means that host can go ahead with restoring the document to an earlier revision.

Note

These messages are only emitted if App_LoadingStatus contains VersionStates in Features. Otherwise, host can immediately restore the version to earlier revision.

Miscellaneous

WOPI host to editor

MessageId	Values	Description
Insert_Button	id: <string> imgurl: <string> hint: <string> accessKey: <string> mobile: <boolean> tablet: <boolean> label: <string> insertBefore: <string> unoCommand: <string>	Inserts a button to the top toolbar. It responds with Clicked_Button post message event on which hosts can react accordingly (except when the unoCommand id parameter is a unique id of the toolbar button. It is recommended to prefix such ids given here given here with some host namespace so that it doesn’t conflict with existing toolbar IDs. In case of conflict, button is not added. imgurl parameter is the link to the image that will be set as button image in the toolbar. The ideal size of the image is 24x24px. The image must be hosted on the host URL to not violate Content-Security-Policy. hint This is used as a tooltip of the button. This is used by accelerator definitions class. Users can press alt or alt+shift and use this key. One should be careful to not introduce conflicting access keys. mobile whether the button should be shown when the interface switches to mobile mode. tablet whether the button should be shown in tablet mode (true if absent) label When a read-only document is opened, we don’t have the toolbar at all. In this case, this newly added button is present in file menubar. The text against this label is used as text of the menubar item. insertBefore Specify the position where the button should be inserted. insertBefore is the button ID (see Finding toolbar button IDs). unoCommand UNO Command to be executed on button click (Reference). When this property is set, no ‘Clicked_Button’ response is sent. The button click will be handled by LibreOffice.
Hide_Button	id: <string>	Hides a button from the toolbar. id is the button ID (see Finding toolbar button IDs).
Show_Button	id: <string>	Hides a button from the toolbar. id is the button ID (see Finding toolbar button IDs).
Remove_Button	id: <string>	Removes a button from the toolbar. id is the button ID (see Finding toolbar button IDs).
Hide_Command	id: <string>	Hide the UI for a command. This include the menu items and toolbar buttons. id is the command (see Finding toolbar button IDs).
Show_Command	id: <string>	Show the UI for a command. The reverse of Hide_Command. id is the command (see Finding toolbar button IDs).
Collapse_Notebookbar		Hide the notebook bar buttons. This is equivalent to double clicking on the name. Click on the name will show it again. This also hide the button strip in the classic UI.
Extend_Notebookbar		Show the notebook bar buttons. This is the equivalent of clicking on the name. This also show the button strip in classic UI.
Hide_StatusBar		Hides the status bar
Show_StatusBar		Shows the status bar
Remove_Statusbar_Element	id: <string>	Removes an element from the status bar. id is the element ID (see Finding status bar element IDs).
Hide_Menubar		Hides the menu bar.
Show_Menubar		Shows the menu bar.
Grab_Focus		This restores focus to the application, activating it, and removing any overlay indicating quiescence, and re-connecting to the server if necessary. Useful after leaving the application for a lengthy period, or when wanting to restore browser focus after presenting an overlaid dialog.
Hide_Ruler		Hides the horizontal document ruler (Writer only)
Show_Ruler		Shows the horizontal document ruler (Writer only)
Hide_Menu_Item	id: <string>	Hides an item from the menu. id is the item ID as defined in the browser/src/control/Control.Menubar.js.
Show_Menu_Item	id: <string>	Shows an item from the menu. id` is the item ID as defined in the browser/src/control/Control.Menubar.js.
Disable_Default_UIAction	action: <string> disable: <Boolean>	Disable the default handler and action for a UI command. action is the action name to enable/disable the default action for. disable controls whether to disable (true) or enable (false) the default action. When set to true, the given UI command will only issue a postMessage without invoking the default action, leaving it up to the client to intercept the postMessage event and handle as necessary. Notice that some actions do not have any default handler to begin with (such as UI_SaveAs and UI_Share) and therefore this will have no effect on them; they only issue postMessage notification anyway without taking any action beyond that. For example, UI_Save will be issued for invoking the save command (from the menu, toolbar, or keyboard shortcut) and no action will take place if UI_Save is disabled via the Disable_Default_UIAction command. Clients who disable UI_Save should then issue Action_Save themselves, when and if they desire to save the document. Similarly, when disabling UI_Close, the document will not close upon invoking the UI_Close action, instead a postMessage notification will be issued and it will be up to the client to issue Action_Close when they desire. Clients must be careful not to issue duplicate actions when the default handler is enabled, instead, they should only issue actions themselves when the default is disabled. Note: currently only UI_Save and UI_Close are supported.
Send_UNO_Command	Command: <string> Args: <object>	Send an UNO command to the editor. See examples in browser/html/framed.doc.html.
Error_Messages	list: [{ type: <identifier>, msg: <string> }, { type: <identifier>, msg: <string> }.....]	Send list to override error messages available in the editor. type identifies which message to override For example to override loadfailed: list: [{ type: 'loadfailed', msg: 'your custom msg' }] To get list of error messages available to override, please checkout browser/src/errormessages.js.
Hint_OnscreenKeyboard		Indicate that the device uses on screen keyboard (like a tablet). This is useful if the detection failed to identify the device is a tablet. This is useful if the device environment is unusual, and should only be used with great caution.
Hint_NoOnscreenKeyboard		Indicate that the device is not a tablet. This is the opposite of Hint_OnscreenKeyboard

Finding toolbar button IDs

Toolbar button IDs are defined in getToolItems/create functions in:

• Control.TopToolbar.js for the top toolbar on desktop or tablet.

• Control.MobileTopBar.ts for the top toolbar on smartphone.

• Control.MobileBottomBar.js for the bottom toolbar on smartphone.

• Control.StatusBar.js for the statusbar on desktop.

Note that they usually don’t change but there is no guarantee that they are stable.

Finding status bar element IDs

Status bar button IDs are defined in the onDocLayerInit function in Control.StatusBar.js. Note that they usually don’t change but there is no guarantee that they are stable.

Editor to WOPI host

MessageId	Values	Description
Clicked_Button	id: <string>	This event is emitted when the custom button added via Insert_Button is clicked.
Download_As	Type: 'print'|'slideshow'|'export' URL: <string>	This event is emitted when the user chooses ‘Print’ or ‘Show slideshow’ or ‘Download As [some type'] and the integration indicates via DownloadAsPostMessage in the CheckFileInfo that it wants to handle the downloading of pdf for printing or svg for slideshows or exported document. This is in situations when the integration cannot rely on browser’s support for downloading like in mobile apps that use the Online in a Web View.
UI_OpenDocument		Requests WOPI host to open a popup window where user can pick another document to view & edit.
UI_CreateFile		Requests WOPI host to open a new browser tab and create a new document. The document type is passed as DocumentType argument, and can be ‘text’,’spreadsheet’,’presentation’ or ‘drawing’.
UI_SaveAs	Args: {format: '<extension>' }	Requests WOPI host to create appropriate UI, so that the user can choose path and File name for creating a copy of the current file. Response to this query is sent via Action_SaveAs message. Optional arguments: file extension. When this parameter is passed a dropdown appears and the newly saved file is loaded in the integration instead of downloaded.
UI_InsertGraphic		Requests WOPI host to open a popup window where user can pick an image to insert. A successful pick would lead to the WOPI host sending a Action_InsertGraphics postMessage back.
UI_InsertFile	callback: <string> mimeTypeFilter: <array_of_strings>	Requests WOPI host to open a popup window where user can pick a file to insert. A successful pick would lead to the WOPI host sending a postMessage defined in ‘callback’ argument back. Required arguments: callback: the name of the postMessage to send back on success. It must take a single ‘url’ argument. mimeTypeFilter: an array of MIME types that the host uses to filter the assets suggested to the user in the window. Since 24.04.10.
UI_Cancel_Password		Notifies WOPI host that the user clicked on the ‘cancel’ option when opening a password protected file, instead of providing the password to decrypt it.
UI_Hyperlink		Notifies WOPI host that the user clicked a hyperlink and confirmed they really want to leave the document to follow the hyperlink. This is especially useful for integrations that embed Collabora Online into an iframe in a mobile app, where actually trying to open a new window should trigger starting a new Activity on Android (or something similar on iOS). The integration using this most probably also wants to trigger the Disable_Default_UIAction for UI_Hyperlink.
Doc_ModifiedStatus		Notification to update the modified status of the document. Values.Modified will be true, if the document has been modified since the last save, otherwise, it will be false if the document has been saved. Note that this notification may be published without a change from the prior value, so care must be taken to check the Values.Modified value and not assume the notification itself implies the modified state of the document on its own.

Calling Python scripts

WOPI host to editor

MessageId	Values	Description
CallPythonScript	script. The Values ScriptFile: <string> Function: <string> Values: <object>	Calls a Python parameter contains an object with named parameters that are passed to the script.

Editor to WOPI host

MessageId	Values	Description
CallPythonScript-Result	commandName: <string> Values: <object>	Returns the result The URL of the script called is in the commandName parameter.

Mentions

Note

Mentions are only working in Writer for now

Editor to WOPI host

MessageId	Values	Description
UI_Mention	type: autocomplete text: <string>	When user starts typing with “@”, CollaboraOnline will send this postMessage with partial text followed by “@” to get the list of usernames from the integrator
	type: selected username: <string>	When user selects the a username from list given by the integrator this message gets fired

WOPI host to editor

MessageId	Values	Description
Action_Mention	list: [{ username: "example-username1", profile: "link-to-the-profile" }, { username: "example-username2", profile: "link-to-the-profile" }.....]	Based on UI_Mention message of type autocomplete, integrator should send this message with list of user object. Each user object contains username and profile