Using PostMessage to interact with the Office for the web application iframe

  • Article

You can integrate your own UI into Office for the web applications. You can then use your UI for actions on Office documents, such as sharing.

To integrate with Office for the web in this way, set up the HTML5 Web Messaging protocol. The Web Messaging protocol, also known as PostMessage, lets Office for the web frame communicate with its parent host page, and vice-versa. The following example shows the general syntax for PostMessage. In this example, otherWindow is a reference to another window that msg posts to.

otherWindow.postMessage(msg, targetOrigin)

Arguments

  • msg (string) – A string (or JSON object) that contains the message data.

  • targetOrigin (string) – Specifies what the origin of otherWindow is for the event to be dispatched. This value is set to the PostMessageOrigin property provided in CheckFileInfo. The literal string *, while supported in the PostMessage protocol, isn't allowed by Office for the web.

Message format

All messages posted to and from the Office for the web application frame are posted using the postMessage() function. Each message (the msg parameter in the postMessage() function) is a JSON-formatted object of the form:

message

MessageId (string)

The name of the message being posted.

SendTime (long)

The time the message was sent, expressed as milliseconds since midnight, January 1, 1970, UTC.

Tip

You can get this value in most modern browsers using the Date.now() method in JavaScript.

Values (JSON-formatted object)

The data associated with the message. This varies per message.

The following example shows the msg parameter for the Host_PerfTiming message.

{
    "MessageId": "Host_PerfTiming",
    "SendTime": 1329014075000,
    "Values": {
        "Click": 1329014074800,
        "Iframe": 1329014074950,
        "HostFrameFetchStart": 1329014074970,
        "RedirectCount": 1
    }
}

Sending messages to the Office for the web iframe

To send messages to the Office for the web iframe, set the PostMessageOrigin property in your WOPI CheckFileInfo response to the URL of your host page. If you don't do this, Office for the web ignores any messages you send to its iframe.

You can send the following messages; all others are ignored:

  • App_PopState
  • Blur_Focus
  • CanEmbed
  • Grab_Focus
  • Host_PerfTiming
  • Host_PostmessageReady

App_PopState

OneNote Online

Note

This message is only used by OneNote Online and isn't required to integrate with Office for the web or Microsoft 365 for mobile. It's included for completeness but doesn't need to be implemented.

OneNote Online integration isn't included in the Office 365 - Cloud Storage Partner Program.

The App_PopState message signals the Office for the web application that state has been popped from the HTML5 History API to which the application should navigate using the URL. This message should be triggered from an onpopstate listener in the host page.

Values

Url (string)

The URL associated with the popped history state.

State (JSON-formatted object)

The data associated with the state.

Example message

{
    "MessageId": "App_PopState",
    "SendTime": 1329014075000,
    "Values": {
        "Url": "https://www.contoso.com/abc123/contents?wdtarget=pagexyz",
        "State": {
            "Value": 0
        }
    }
}

Blur_Focus

The Blur_Focus message signals the Office for the web application to stop aggressively grabbing focus. Hosts should send this message whenever the host application UI is drawn over the Office for the web frame, so that the Office application doesn't interfere with the UI behavior of the host.

This message only affects Office for the web edit modes. It doesn't affect view modes.

Tip

When the host application displays UI over Office for the web, it should put a full-screen dimming effect over the Office for the web UI, so that it's clear that the Office application isn't interactive.

Values

Empty.

Example Message

{
    "MessageId": "Blur_Focus",
    "SendTime": 1329014075000,
    "Values": { }
}

CanEmbed

The CanEmbed message is sent by the host in response to a request to create a HostEmbeddedViewUrl using the UI_FileEmbed message.

Values

HostEmbeddedViewUrl (string)

A URI to a web page that provides access to a viewing experience for the file that can be embedded in another HTML page. This string is equivalent to the HostEmbeddedViewUrl in CheckFileInfo.

Example message

{
    "MessageId": "CanEmbed",
    "SendTime": 1329014075000,
    "Values": {
        "HostEmbeddedViewUrl": "https://www.contosodrive.com/documents/1234/embedded/"
    }
}

Grab_Focus

The Grab_Focus message signals the Office for the web application to resume aggressively grabbing focus. Hosts should send this message whenever the host application UI that's drawn over the Office for the web frame is closing. This lets the Office application resume functioning.

This message only affects Office for the web edit modes. It doesn't affect view modes.

Values

Empty.

Example message

{
    "MessageId": "Grab_Focus",
    "SendTime": 1329014075000,
    "Values": { }
}

Host_IsFrameTrusted

The Host_IsFrameTrusted message is sent by the host in response to App_IsFrameTrusted message.

Values

isTopFrameTrusted (boolean)

A boolean value indicating whether the top frame is trusted.

Example message

{
    "MessageId": "Host_IsFrameTrusted",
    "SendTime": 1329014075000,
    "Values": {
        "isTopFrameTrusted": true
    }
}

Host_PerfTiming

Provides performance related timestamps from the host page. Hosts should send this message when the Office for the web frame is created so load performance can be more accurately tracked.

Values

Click (integer)

The timestamp, in ticks, when the user selected a link that launched the Office for the web application. For example, if the host exposed a link in its UI that launches an Office for the web application, this timestamp is the time the user originally selected that link.

Iframe (integer)

The timestamp, in ticks, when the host created the Office for the web iframe at the time the user selected the link.

HostFrameFetchStart (integer)

The result of the PerformanceTiming.fetchStart attribute, if the browser supports the W3C NavigationTiming API. If the NavigationTiming API isn't supported by the browser, this value must be 0.

RedirectCount (integer)

The result of the PerformanceNavigation.redirectCount attribute, if the browser supports the W3C NavigationTiming API. If the NavigationTiming API isn't supported by the browser, this value must be 0.

Example message

{
    "MessageId": "Host_PerfTiming",
    "SendTime": 1329014075000,
    "Values": {
        "Click": 1329014074800,
        "Iframe": 1329014074950,
        "HostFrameFetchStart": 1329014074970,
        "RedirectCount": 1
    }
}

Host_PostmessageReady

Office for the web delay-loads much of its JavaScript code, including most of its PostMessage senders and listeners. You might choose to follow this pattern in your WOPI host page. So, your outer host page and the Office for the web iframe must coordinate to ensure that each is ready to receive and respond to messages.

To enable this coordination, Office for the web sends the App_LoadingStatus message only after all its message senders and listeners are available. In addition, Office for the web listens for the Host_PostmessageReady message from the outer frame. Until it receives this message, some UI, such as the Share button, is disabled.

Until your host page receives the App_LoadingStatus message, the Office for the web frame cannot respond to any incoming messages except Host_PostmessageReady. Office for the web does not delay-load its Host_PostmessageReady listener; it is available almost immediately upon iframe load.

If you're delay-loading your PostMessage code, ensure that your App_LoadingStatus listener is not delay-loaded. This ensures that you can receive the App_LoadingStatus message even if your other PostMessage code hasn't yet loaded.

Following is the typical flow:

  1. Host page begins loading.

  2. Office for the web frame begins loading. Some UI elements are disabled, because Host_PostmessageReady hasn't yet been sent by the host page.

  3. Host page finishes loading and sends Host_PostmessageReady. No other messages are sent because the host page hasn't received the App_LoadingStatus message from the Office for the web frame.

  4. Office for the web frame receives Host_PostmessageReady.

  5. Office for the web frame finishes loading and sends App_LoadingStatus to host page.

  6. Host page and Office for the web communicate by using other PostMessage messages.

Values

Empty.

Example message

{
    "MessageId": "Host_PostmessageReady",
    "SendTime": 1329014075000,
    "Values": { }
}

Listening to messages from the Office for the web iframe

The Office for the web iframe sends messages to the host page. On the receiving end, the host page receives a MessageEvent. The origin property of the MessageEvent is the origin of the message, and the data property is the message being sent. The following code example shows how you might consume a message.

function handlePostMessage(e) {
    // The actual message is contained in the data property of the event.
    var msg = JSON.parse(e.data);

    // The message ID is now a property of the message object.
    var msgId = msg.MessageId;

    // The message parameters themselves are in the Values
    // parameter on the message object.
    var msgData = msg.Values;

    // Do something with the message here.
}
window.addEventListener('message', handlePostMessage, false);

The host page receives the following messages, all others are ignored:

  • App_LoadingStatus
  • App_PushState
  • Edit_Notification
  • File_Rename
  • UI_Close
  • UI_Edit
  • UI_FileEmbed
  • UI_FileVersions
  • UI_Sharing
  • UI_Workflow

Common values

In addition to message-specific values passed with each message, Office for the web sends the following common values with every outgoing PostMessage:

ui-language (string)

The LCID of the language Office for the web was loaded in. This value won't match the value provided using the UI_LLCC placeholder. Instead, this value is the numeric LCID value (as a string) that corresponds to the language used. For mor einformation, see What languages does Office for the web support?.

This value might be needed in the event that Office for the web renders using a language different than the one requested by the host. This might occur if Office for the web isn't localized in the language requested. In that case, the host might choose to draw its own UI in the same language that Office for the web used.

wdUserSession (string)

The ID of the Office for the web session. This value is logged by the host and used when troubleshooting issues with Office for the web. For more information on this value, see Session IDs.

App_IsFrameTrusted

The App_IsFrameTrusted message posts by the Office for the web application frame to initiate handshake flow. The host is expected to check whether the top frame is trusted and post Host_IsFrameTrusted message back to Office for the web application. The host first needs to include a query string: &sftc=1 to url of POST request sent to Office for the web application, to indicate to Office for the web application that the host supports frame trust post Message.

sftc stands for SupportsFrameTrustedPostMessage. Only when &sftc is included in the query string, will the App_IsFrameTrusted message be posted by Office for the web application frame to initiate handshake flow.

Values

Common values only.

Example Message

{
    "MessageId": "App_IsFrameTrusted",
    "SendTime": 1329014075000,
    "Values": {
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

App_LoadingStatus

The App_LoadingStatus message posts after the Office for the web application frame has loaded. Until the host receives this message, it must assume that the Office for the web frame can't react to any incoming messages except Host_PostmessageReady.

Values

DocumentLoadedTime (long)

The time that the frame was loaded.

Example message

{
    "MessageId": "App_LoadingStatus",
    "SendTime": 1329014075000,
    "Values": {
        "DocumentLoadedTime": 1329014074983,
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

App_PushState

OneNote Online

Note

This message is only used by OneNote Online and isn't required to integrate with Office for the web or Microsoft 365 for mobile. It's included for completeness but doesn't need to be implemented.

OneNote Online integration isn't included in the Office 365 - Cloud Storage Partner Program.

The App_PushState message posts when the user changes the state of Office for the web application in such a way as to return to it later, requesting to capture it in the HTML 5 History API. In receiving this message, the Host page should use history.pushState to capture the state for a potential later state pop.

To send this message, the AppStateHistoryPostMessage property in the CheckFileInfo response from the host must be set to true. Otherwise, Office for the web doesn't send the message.

Values

Url (string)

The URL associated with the message.

State (JSON-formatted object)

The data associated with the state.

Example message

{
    "MessageId": "App_PushState",
    "SendTime": 1329014075000,
    "Values": {
        "Url": "https://www.contoso.com/abc123/contents?wdtarget=pagexyz",
        "State": {
            "Value": 0
        },
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

Edit_Notification

The Edit_Notification message posts when the user first makes an edit to a document, and every five minutes thereafter, if the user has made edits in the previous five minutes. Hosts can use this message to gauge whether users are interacting with Office for the web. In coauthoring sessions, hosts can't use the WOPI calls for this purpose.

To send this message, the EditNotificationPostMessage property in the CheckFileInfo response from the host must be set to true. Otherwise, Office for the web won't send this message.

Values

Common values only.

Example message

{
    "MessageId": "Edit_Notification",
    "SendTime": 1329014075000,
    "Values": {
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

File_Rename

The File_Rename message posts when the user renames the current file in Office for the web. The host can use this message to optionally update the UI, such as the title of the page.

Note

If the host doesn't return the SupportsRename parameter in their CheckFileInfo response, the rename UI won't be available in Office for the web.

Values

NewName (string)

The new name of the file.

Example message

{
    "MessageId": "File_Rename",
    "SendTime": 1329014075000,
    "Values": {
        "NewName": "Renamed Document",
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

UI_Close

The UI_Close message posts when the Office for the web application is closing, either due to an error or a user action. Typically, the URL specified in the CloseUrl property in the CheckFileInfo response is displayed. However, hosts can intercept this message instead and navigate in an appropriate way.

To send this message, the ClosePostMessage property in the CheckFileInfo response from the host must be set to true. Otherwise, Office for the web won't send this message.

Values

Common values only.

Example message

{
    "MessageId": "UI_Close",
    "SendTime": 1329014075000,
    "Values": {
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

UI_Edit

The UI_Edit message posts when the user activates the Edit UI in Office for the web. This UI is only visible when using the view action.

To send this message, the EditModePostMessage property in the CheckFileInfo response from the host must be set to true. Otherwise, Office for the web won't send this message and redirects the inner iframe to an edit action URL instead.

Hosts can choose to use this message in cases where they want more control over the user’s transition to edit mode. For example, a host might wish to prompt the user for some additional host-specific information before navigating.

Values

Common values only.

Example message

{
    "MessageId": "UI_Edit",
    "SendTime": 1329014075000,
    "Values": {
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

UI_FileEmbed

The UI_FileEmbed message posts when the user activates the Embed UI in Office for the web. The host should use this message to trigger the creation of a HostEmbeddedViewUrl, which the host then passes back to the WOPI client using the CanEmbed message.

To send this message, the FileEmbedCommandPostMessage property in the CheckFileInfo response from the host must be set to true, and FileEmbedCommandUrl must be provided. Otherwise, Office for the web won't send this message.

Also, Office for the web won't send the message if a HostEmbeddedViewUrl is provided in the CheckFileInfo response. In this case, since a HostEmbeddedViewUrl is already provided, there's no need to retrieve it from the host via PostMessage.

Values

Common values only.

Example message

{
    "MessageId": "UI_FileEmbed",
    "SendTime": 1329014075000,
    "Values": {
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "en-us"
    }
}

UI_FileVersions

The UI_FileVersions message posts when the user activates the Previous Versions UI in Office for the web. The host should use this message to trigger any custom file version history UI.

To send this message, the FileVersionPostMessage property in the CheckFileInfo response from the host must be set to true. Otherwise, Office for the web won't send this message.

Values

Common values only.

Example message

{
    "MessageId": "UI_FileVersions",
    "SendTime": 1329014075000,
    "Values": {
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

UI_Sharing

The UI_Sharing message posts when the user activates the Share UI in Office for the web. The host should use this message to trigger any custom sharing UI.

To send this message, the FileSharingPostMessage property in the CheckFileInfo response from the host must be set to true. Otherwise, Office for the web won't send this message.

Values

Common values only.

Example message

{
    "MessageId": "UI_Sharing",
    "SendTime": 1329014075000,
    "Values": {
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

UI_Workflow

The UI_Workflow message posts when the user activates the Workflow UI in Office for the web. The host should use this message to trigger any custom workflow UI.

To send this message, the WorkflowPostMessage property in the CheckFileInfo response from the host must be set to true. Otherwise, Office for the web won't send this message.

Values

WorkflowType (string)

The WorkflowType associated with the message. This matches one of the values provided by the host in the WorkflowType property in CheckFileInfo.

Example message

{
    "MessageId": "UI_Workflow",
    "SendTime": 1329014075000,
    "Values": {
        "WorkflowType": "Submit",
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}