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.

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.

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_E xport_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.

Session Management

WOPI Host to editor

MessageId

Values

Description

Action_RemoveView

ViewId: <Number>

Remove the session.

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.

Views_List

See Get_Views_Resp.

Complete information about the currently connected views.

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.

Action_Print

Prints the document.

Action_Export

 
Format: <String>

Downloads the document in format specified by Format. Format must be from the list returned in returned in Get_Export_Formats

Action_InsertGraphics

 
url: <String>

Downloads image from the url and inserts it to the document.

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>

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.

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>
mobile: <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. mobile Whether the button should be shown when the interface switches to mobile mode. 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).

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_Button

 
id: <string>

Hides a button from the toolbar.

id is the button ID, see Finding toolbar button IDs.

Show_Button

 
id: <string>

Shows a button from the toolbar.

id is the buttonID, see Finding toolbar button IDs.

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>
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 ``ommand. 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.

Finding toolbar button IDs

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

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 API above 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_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

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.

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