postMessage API List

The postMessage APIs are broadly divided into major categories:

Note: To enable postMessage APIs, you need to register your domain(s) with us. Please refer this link to know how to allow or add your postMessage domain list.

Send Messages to Writer iFrame

Under the send message section, you can post content, review as well as control document save from your host page.

The list of send message methods and their categories are tabulated below:

Content

Fillable Fields

Named Range

Review

Document

Format

Content

Create Named Range

Purpose

To create a named range for a selected text in Zoho Writer iFrame and it will return a range ID to your web application's host page.

XDC.postMessage ( {
        "message": "CreateNamedRange",
        "data": {
            "name": <String> // Ex: "name": "My Content"
        },
        "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                    console.log("ID for the inserted named range", data.rangeId);
                } else {
                      // Handle Failure
                }
       },
       "onexception": function(data) {
            // Handle exception
       }
} );

Find and Replace

Purpose

To find a text and replace it with another text from your web application's host page to Zoho Writer iFrame.

XDC.postMessage ( {
        "message": "FindAndReplace",
        "data": {
            "findText": <String>,
            "replaceWith": <String>, 
            "isReplaceAll": <Boolean>
        },
        "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                } else {
                      // Handle Failure
                }
       },
       "onexception": function(data){
            // Handle exception
       }
} );

Get All Named Contents

Purpose

 To get the contents of all the named ranges in the document.              

XDC.postMessage ( {
        "message": "GetAllNamedContents",
        "data": {
            "contentType": "text" // or HTML
        },
        "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                } else {
                      // Handle Failure
                }
       },
       "onexception": function(data) {
            // Handle exception
       }
} );

Get Named Content by ID

Purpose

To get the content in the named range using Named Range ID.              

XDC.postMessage ( {
        "message": "GetNamedContentById",
        "data": {
            "rangeId": <String>,    
            "contentType": "text" // or HTML
        },
        "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                } else {
                      // Handle Failure
                }
       },
       "onexception": function(data) {
            // Handle exception
       }
} );

Get Named Contents by Name

Purpose

To get the contents in the named range using Named Range name.              

XDC.postMessage ( {
        "message": "GetNamedContentsByName",
        "data": {
            "rangeName": <String>,    
            "contentType": "text" // or HTML
        },
        "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                } else {
                      // Handle Failure
                }
       },
       "onexception": function(data) {
            // Handle exception
       }
} );

Get Document Stats

Purpose

To get the number of words, characters and pages present in the document.             

XDC.postMessage ( {
       "message": "DocumentStats",
        "oncomplete": function(data) {
              console.log(JSON.stringify(data));
              // {
              // "words": "75",
              // "characters": "522",
              // "pages": "1"
              // }
       },
       "onexception": function(data) {
              // Handle exception
       }
} );

Insert Content

Purpose

To insert text or HTML content from your web application's host page to Zoho Writer iFrame.

XDC.postMessage ( {
        "message": "InsertContent",
        "data": {
            "content": " Happy Writing!",
            "contentType": "text", // or HTML
            "htmlFormat": "SourceFormat", // or DestinationFormat (This data is applicable only when the 'contentType: HTML' and its default value will be 'SourceFormat')
            "scrollIntoView": "<Boolean>"
        },
        "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                } else {
                      // Handle Failure
                }
       },
       "onexception": function(data) {
            // Handle exception
       }
} );

Insert Named Content

Purpose

To insert a named text or HTML content in Zoho Writer iFrame and it will return a range ID to your web application's host page.

XDC.postMessage ( {
        "message": "InsertNamedContent",
        "data": {
            "name":<String>, // Ex: "name": "New Content"
            "content": " Happy Writing!",
            "contentType": "text", // or HTML
            "htmlFormat": "SourceFormat",  // or DestinationFormat (This data is applicable only when the 'contentType: HTML' and its default value will be 'SourceFormat')
            "scrollIntoView": "<Boolean>"
        },
        "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                    console.log("ID for the inserted named range", data.rangeId);
                } else {
                      // Handle Failure
                }
       },
       "onexception": function(data) {
            // Handle exception
       }
} );

Insert Merge Field

Purpose 

To insert a merge field from your web application's host page to Zoho Writer iFrame.

XDC.postMessage ( {
        "message": "InsertMergeField",
        "data": {
            "mergeFieldName":<String>,
            "mergeFieldDisplayName":<String>,
            "mergeFieldPlaceholderImage":<Url>,
            "mergeFieldType":<MergeFieldType>,
            "mergeFieldFormat":<MergeFieldFormat>
        },
        "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                } else {
                      // Handle Failure
                }
       },
       "onexception": function(data) {
            // Handle exception
       }
} );
 

Please refer the below table to insert different types of merge field with corresponding merge field format by replacing the values of <MergeFieldType> and <MergeFieldFormat>.

MergeFieldTypeMergeFieldFormatDescription

"barcode"

"code128",
"code39",
"ean13",
"upc",
"itf14",
"msi",
"pharmacode",
"codabar"		To insert barcode as a merge field from your web application's host page to Zoho Writer iFrame.

"checkbox"

NA To insert checkbox as a merge field from your web application's host page to Zoho Writer iFrame.

"image"

"fill_image_to_frame"
"fit_image_to_frame"
"resize_frame_to_image"
"stretch_image_to_frame"		To insert image as a merge field from your web application's host page to Zoho Writer iFrame.

"link"

NATo insert link as a merge field from your web application's host page to Zoho Writer iFrame.

"list"

"vertical"
"horizontal"		To insert list as a merge field from your web application's host page to Zoho Writer iFrame.

"multiline"

NATo insert multiline as a merge field from your web application's host page to Zoho Writer iFrame.

"number"

NATo insert number as a merge field from your web application's host page to Zoho Writer iFrame.

"phone"

"(###) ### ####"
"###-###-####"		To insert phone number as a merge field from your web application's host page to Zoho Writer iFrame.

"qrcode"

"plain_text"
"url"
"contact"
"phone"
"sms"
"wifi"		To insert qrcode as a merge field from your web application's host page to Zoho Writer iFrame.

"richtext"

NATo insert rich text as a merge field from your web application's host page to Zoho Writer iFrame.

"text"

NATo insert text as a merge field from your web application's host page to Zoho Writer iFrame.

Insert Signer Field

Purpose 

To insert a signer field from your web application's host page to Zoho Writer iFrame.

XDC.postMessage ( {
        "message": "InsertSignerField",
        "data": {
            "signerFieldType":<SignerFieldType>,
            "recipient":<String>,
            "signerFieldName":<String>,
            "signerFieldFormat":<SignerFieldFormat>,
            "dropdownOptions":<Array>,
            "isMandatory":<Boolean>
        },
        "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                } else {
                      // Handle Failure
                }
       },
       "onexception": function(data) {
            // Handle exception
       }
} );
 

Please refer the below table to insert different types of signer field with corresponding signer field format by replacing the values of <SignerFieldType> and <SignerFieldFormat>.

SignerFieldTypeSignerFieldFormatDescription

"checkbox"

NATo insert checkbox as a signer field from your web application's host page to Zoho Writer iFrame.

"company"

NATo insert company name as a signer field from your web application's host page to Zoho Writer iFrame.

"custom_date"

"dd MMM yyyy"
"MMM dd yyyy"		To insert custom date as a signer field from your web application's host page to Zoho Writer iFrame.

"dropdown"

NATo insert dropdown as a signer field from your web application's host page to Zoho Writer iFrame.

"email"

NATo insert email address as a signer field from your web application's host page to Zoho Writer iFrame.

"fullname"

NATo insert full name as a signer field from your web application's host page to Zoho Writer iFrame.

"initial"

NATo insert initial as a signer field from your web application's host page to Zoho Writer iFrame.

"job_title"

NATo insert job title as a signer field from your web application's host page to Zoho Writer iFrame.

"sign_date"

NATo insert the signing date as a signer field from your web application's host page to Zoho Writer iFrame.

"signature"

NATo insert signature as a signer field from your web application's host page to Zoho Writer iFrame.

"textfield"

NATo insert text field as a signer field from your web application's host page to Zoho Writer iFrame.

Lock Content

Purpose

To lock the selected or unselected content from Zoho Writer iFrame to your web application's host page.

XDC.postMessage ( {
        "message": "LockContent",
        "data": {
            "userInfo": [{"name": <String>, "id": <String>}, ..],
            "redact": "<Boolean>",
            "onselection": "<Boolean>" // By default, the value will be 'true' - to lock the selected content; 'false' - to lock the unselected content
        },
        "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                } else {
                      // Handle Failure
                }
       },
       "onexception": function(data) {
            // Handle exception
       }
} );

Replace Named Content

Purpose

To replace an existing named content in Zoho Writer iFrame with the given text or HTML content.

XDC.postMessage ( {
        "message": "ReplaceNamedContent",
        "data": {
            "contentType": "text", // or HTML
            "htmlFormat": "SourceFormat",  // or DestinationFormat (This data is applicable only when the 'contentType: HTML' and its default value will be 'SourceFormat')
            "rangeId": <String>, // or "rangeName": <String>
            "replaceWith": <String>
        },
        "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                } else {
                      // Handle Failure
                }
       },
       "onexception": function(data){
            // Handle exception
       }
} );

Submit Fillable Document

Purpose

To submit a fillable document after filling the fillable fields from Zoho Writer iFrame to your web application's host page.

XDC.postMessage ( {
        "message": "SubmitFillableDocument",
        "data": { },
         "oncomplete": function(data) {
              console.log(JSON.stringify(data));
              if (data.result === 1) {
                  // Handle Success
              } else {
                  // Handle Failure
              }
          },
         "onexception": function(data) {
               // Handle exception
          }
} );

Update Fillable Field Properties

Purpose

To update properties of the fillable fields inserted in the document from Zoho Writer iFrame to your web application's host page.

XDC.postMessage ( {
        "message": "UpdateFillableFieldProperties",
        "data": {
             "propertyName": "maxLength",
             "propertyValue": 1000,
             "fillableFieldNames": ["Text Field 1", "Text Field 2", "Text Field 3"]  //You can also pass the label of a single fillable field to update its property using the same key.
         },
         "oncomplete": function(data) {
              console.log(JSON.stringify(data));
              if (data.result === 1) {
                  // Handle Success
              } else {
                  // Handle Failure
              }
          },
         "onexception": function(data) {
               // Handle exception
          }
} );

Unlock Content

Purpose

To unlock the selected content from Zoho Writer iFrame to your web application's host page.

XDC.postMessage ( {
        "message": "UnlockContent",
        "data": {},
        "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                } else {
                      // Handle Failure
                }
       },
       "onexception": function(data) {
            // Handle exception
       }
} );

Fillable Fields

Insert Fillable Field

Purpose 

To insert a fillable field from your web application's host page to Zoho Writer iFrame.


XDC.postMessage ( {
        "message": "InsertFillableField",
        "data": {
             "fillableFieldType": <FieldType>,
             "fillableFieldName": <String>,
             "fillableFieldValue": <FieldValue>
        },
        "oncomplete": function(data) {
             console.log(JSON.stringify(data));
             if (data.result === 1) {
                 // Handle Success
             console.log("ID for the inserted fillable field", data.fillableFieldId);
             } else {
                 // Handle Failure
             }
        },
        "onexception": function(data) {
             // Handle exception
         }
} );
 

Please refer the below table to insert different types of fillable fields by replacing the values of <FieldType> and <FieldValue>.

FieldTypeData TypeFieldValueDescription

"checkbox"

Boolean

true / falseTo insert checkbox as a fillable field from your web application's host page to Zoho Writer iFrame.

"currency"

Number

IntegerTo insert currency as a fillable field from your web application's host page to Zoho Writer iFrame.

"date"

Number 

in MillisecondsTo insert date as a fillable field from your web application's host page to Zoho Writer iFrame.

"email"

String

Ex: xyz@zylker.comTo insert email as a fillable field from your web application's host page to Zoho Writer iFrame.

"number"

Number

IntegerTo insert number as a fillable field from your web application's host page to Zoho Writer iFrame.

"percent"

Number

IntegerTo insert percent as a fillable field from your web application's host page to Zoho Writer iFrame.

"phone"

Number

IntegerTo insert phone as a fillable field from your web application's host page to Zoho Writer iFrame.

"selectbox"

Array

["option1","option2"]To insert selectbox as a fillable field from your web application's host page to Zoho Writer iFrame.

"singleline"

String

NATo insert single line as a fillable field from your web application's host page to Zoho Writer iFrame.

Update Fillable Field by ID

Purpose 

To update a fillable field using the fillable field ID.


XDC.postMessage ( {
        "message": "UpdateFillableFieldById",
        "data": {
            "fillableFieldId": <String>,
            "fillableFieldValue": <String>
        },
        "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                } else {
                      // Handle Failure
                }
         },
         "onexception": function(data) {
              // Handle exception
          }
} );
 

Update Fillable Fields by Name

Purpose 

To update fillable fields with respect to fillable field name.


XDC.postMessage ( {
        "message": "UpdateFillableFieldsByName",
       "data": {
             "fillableFieldName": <String>,
             "fillableFieldValue": <String>
        },
       "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                } else {
                      // Handle Failure
                }
        },
        "onexception": function(data) {
             // Handle exception
        }
} );
 

Update Fillable Fields

Purpose 

To update multiple fillable fields at the same time.


XDC.postMessage ( {
        "message": "UpdateFillableFields",
        "data": {
             "fillableFieldValues": {
               field_label_1= field_value_1,
              field_label_2= field_value_2
              }
        },
       "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                } else {
                      // Handle Failure
                }
        },
        "onexception": function(data) {
             // Handle exception
        }
} );
 

Named Range

Get Named Range by ID

Purpose

To get or retrieve the named range for the given ID.

XDC.postMessage ( {
        "message": "GetNamedRangeById",
        "data": {
             "rangeId": <String>
        },
        "oncomplete": function(data) {
             console.log(JSON.stringify(data));
             if (data.result === 1) {
                 // Handle Success
             } else {
                   // Handle Failure
             }
       },
       "onexception": function(data) {
             // Handle exception
        }
);

Get Named Ranges by Name

Purpose

To get or retrieve the named ranges for the given name.

XDC.postMessage ( {
        "message": "GetNamedRangesByName",
        "data": {
                "rangeName": <String>
         },
        "oncomplete": function(data) {
                 console.log(JSON.stringify(data));
                 if (data.result === 1) {
                     // Handle Success
                 } else {
                       // Handle Failure
                 }
         },
         "onexception": function(data){
                // Handle exception
          }
);

Get All Named Ranges

Purpose

To get or retrieve all the named ranges.

XDC.postMessage ( {
        "message": "GetAllNamedRanges",
        "oncomplete": function(data) {
                 console.log(JSON.stringify(data));
                 if (data.result === 1) {
                    // Handle Success
                 } else {
                     // Handle Failure
                 }
        },
       "onexception": function(data) {
              // Handle exception
        }
);

Move Cursor To Named Range

Purpose

To move the cursor to the named range from your web application's host page and scroll to view in Zoho Writer iFrame.

XDC.postMessage ( {
        "message": "MoveCursorToNamedRange",
        "data": {
                "rangeId": <String>
         },
        "oncomplete": function(data) {
                 console.log(JSON.stringify(data));
                 if (data.result === 1) {
                     // Handle Success
                 } else {
                       // Handle Failure
                 }
         },
         "onexception": function(data){
                // Handle exception
          }
);

Remove Named Range by ID

Purpose

To delete a named range for the given ID.

XDC.postMessage ( {
        "message": "RemoveNamedRangeById",
        "data": {
                "rangeId": <String>,
                "deleteContent": <Boolean>
        },
        "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                } else {
                      // Handle Failure
                }
       },
       "onexception": function(data) {
              // Handle exception
       }
);

Remove Named Ranges by Name

Purpose

To delete the named ranges for the given name.

XDC.postMessage ( {
        "message": "RemoveNamedRangesByName",
        "data": {
                 "rangeName": <String>,
                 "deleteContent": <Boolean>
        },
        "oncomplete": function(data) {
              console.log(JSON.stringify(data));
              if (data.result === 1) {
                  // Handle Success
              } else {
                  // Handle Failure
              }
        },
        "onexception": function(data) {
             // Handle exception
        }
};

Format

Set Format

Purpose 

To set the data in a defined format (say JSON) and send to a Writer document from the host page.


XDC.postMessage ( {
        "message": "SetFormat",
        "data": {
            "format": <JSON>
        },
        "oncomplete": function(data) {
              console.log(JSON.stringify(data));
              if (data.result === 1) {
                  // Handle Success
              } else {
                  // Handle Failure
              }
        },
        "onexception": function(data) {
             // Handle exception
        }
} );
 

Review

Review Changes

Purpose 

To review the content and accept or reject changes in the Writer document.


XDC.postMessage ( {
        "message": "ReviewChanges",
        "data": {
             "action": "AcceptAll" // or "RejectAll"
         },
         "oncomplete": function(data) {
              console.log(JSON.stringify(data));
              if (data.result === 1) {
                  // Handle Success
              } else {
                  // Handle Failure
              }
          },
         "onexception": function(data) {
               // Handle exception
          }
} );
 

Document

Export Document

Purpose

To export the document in the required format from Zoho Writer iFrame to your web application's host page.

XDC.postMessage ( {
        "message": "ExportDocument",
        "data": {
            "format": <String> // pdf/doc/docx/rtf/odt/txt/html/zip/epub/zdoc
        },
        "oncomplete": function(data) {
                console.log(JSON.stringify(data));
                if (data.result === 1) {
                    // Handle Success
                } else {
                      // Handle Failure
                }
       },
       "onexception": function(data) {
            // Handle exception
       }
} );

Save Document

Purpose

To "save" the Writer document.


XDC.postMessage ( {
        "message": "SaveDocument",
       "data": {
           "hideSaveButton": <Boolean>, // Default value will be true
           "forceSave": <Boolean>, // Default value will be true 
           "saveUrlParams": <JSON>,
           "format": <String> // pdf/doc/docx/rtf/odt/txt/html/zip/epub/zdoc
       },
            // Use "SaveDocumentResponse" event for oncomplete
       "onexception": function(data) {
            // Handle exception
        }
} );
 

Receive Messages from Writer iFrame

Under the receive message section, you can obtain multiple notifications about document status from Writer iFrame to your host page. 

The list of receive message methods and their categories are tabulated below:

Document

Selection

Document

Document Load In Progress

Purpose 

To receive the "Document Load In Progress" notification from Writer iFrame to the host page.  


XDC.receiveMessage("DocumentLoadInProgress", function(data) {
        console.log(data);
} );
 

Document Load Complete

Purpose 

To receive the "Document Load Complete" notification from Writer iFrame to the host page.  


XDC.receiveMessage("DocumentLoadComplete", function(data) {
         console.log(data);
} );
 

Document Modified

Purpose 

To receive the "Document Modified" notification from Writer iFrame to the host page.


XDC.receiveMessage("DocumentModified", function(data) {
         console.log(data);
} );
 

Fillable Field Inserted

Purpose 

To receive a notification when the "Fillable Field" is inserted from Writer iFrame to the host page.


XDC.receiveMessage("FillableFieldInserted", function(data) {
       console.log(data);
} );
 

Fillable Field Updated

Purpose 

To receive a notification when the "Fillable Field" is updated from Writer iFrame to the host page.


XDC.receiveMessage("FillableFieldUpdated", function(data) {
       console.log(data);
} );
 

Fillable Fields Deleted

Purpose 

To receive a notification when the "Fillable Fields" are deleted from Writer iFrame to the host page.


XDC.receiveMessage("FillableFieldsDeleted", function(data) {
         console.log(data);
} );
 

Named Ranges Deleted

Purpose 

To receive a notification when the "Named Ranges" are deleted from Writer iFrame to the host page.


XDC.receiveMessage("NamedRangesDeleted", function(data) {
         console.log(data);
} );
 

Named Ranges In Selection

Purpose 

To receive a notification when the "Named Ranges" are selected from Writer iFrame to the host page.


XDC.receiveMessage("NamedRangesInSelection", function(data) {
         console.log(data);
} );
 

Save Document Response

Purpose 

To receive a save document response from Writer iFrame to the host page.


XDC.receiveMessage("SaveDocumentResponse", function(data) {
       console.log(data);
} );
 

Selection

Selection Changed

Purpose 

To receive a notification from Writer iFrame on a change of selected text in a document.


XDC.receiveMessage("SelectionChanged", function(data) {
         console.log(data);
} );
 

Note: To know about the list of error handling cases in postMessage API's, refer here.