Translate Document Via Webhook

Purpose

This API allows you to post the translated document to the given webhook url.

Quick Reference

Property	Value
Method	POST
Request URL	https://{zohoapis_domain}/writer/api/v1/documents/{document_id}/translate/webhook
Scopes	ZohoWriter.documentEditor.ALL, ZohoPC.files.ALL, WorkDrive.files.ALL, WorkDrive.organization.ALL, WorkDrive.workspace.ALL
Rate Limit	See Writer API throttle limits

Parameters

Path Parameters

Parameter	Data Type	Mandatory/Optional	Description
document_id	String	Optional	Specify the unique id of the document that needs to be translated.

Body Parameters

Parameter	Data Type	Mandatory/Optional	Description
source_language	String	Mandatory	Specify the language code of the given original document.
target_language	String	Mandatory	Specify the language code in which the original document needs to be translated.
webhook	{ “invoke_url”: <URL>, “timeout”: 50, "retry_interval": "60”, “headers”:{...}, "http_method_type":"put/post" }, "timeout": 50, "retry_interval": "60", "headers":{...}, "http_method_type":"put/post" }	Mandatory	invoke_url - Specify the webhook url where the translated document needs to be posted. Below mentioned keys are optional; timeout - Set the timeout duration for posting bytes from Zoho server. By default, it will be set to 50 seconds. retry_interval - Specify the interval to retry the post operation in case of any failure when sending translated bytes to your server. Supported range is 60 seconds to 8 hours. By default, it will be set to 60 seconds. headers - Provide the necessary header key-value pairs in JSON format for posting translated bytes from our server to the provided webhook URL. http_method_type - Specify the http method type via this key. The default method will be POST.
folder_id	String	Mandatory	Specify the ID of the folder where you'd like to store the translated document. By default, it will be saved in the "My Folder" of WorkDrive.

webhook

Parameter	Type	Possible Values	Default Value
Mandatory Key
invoke_url	String	URL - Maximum length is 300 characters.	URL
Optional Keys
timeout	Integer	60 to 28800 seconds (8hrs)	60 seconds
retry_interval	Integer	1 to 120 seconds	50 seconds
headers	JSON	- Maximum key count - 10 - Allowed characters for - Alphabets, Numbers, Hyphen, Underscore and Dot. Maximum Length - 100 characters - Maximum length of - 2500 characters
http_method_type	String	put/post	post

Notes

You can check the possible errors list here.

Sample Request

Curl Deluge

Copiedcurl -X POST "https://www.zohoapis.com/writer/api/v1/documents/{document_id}/translate/webhook" \
  -H "Authorization: Zoho-oauthtoken <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_language": "en",
    "target_language": "es",
    "webhook": {
      "invoke_url": "https://your-webhook-url.com/endpoint",
      "timeout": 60,
      "retry_interval": 50,
      "headers": {"Authorization": "Bearer token"},
      "http_method_type": "post"
    },
    "folder_id": "optional_folder_id"
  }'

Copiedparam = Map();
param.put("source_language","en");
param.put("target_language","fr");
param.put("webhook",{"invoke_url":"https://webhook.example.com/callback","invoke_period":"oncomplete"});
param.put("folder_id","<folder_id>");
response = invokeurl
[
	url :"https://www.zohoapis.com/writer/api/v1/documents/{document_id}/translate/webhook"
	type :POST
	parameters:param
	connection:"<connection_name>"
];
info response;

Once the process is initiated, you will be provided with the 'status_url' initially. By invoking the 'status_url', you will be able to check the status of the scheduled job.

Sample Response

Copied{
    "status_url": "https://writer.zoho.com/writer/api/v1/documents/{{rid}}/translate/jobs/f931a01183b33
    "status": "inprogress"
}

While invoking the 'status_url', you will receive the below responses;

1. Success case:

Job completion status can be checked using the 'status' key. Once the status is changed to 'completed', you will be provided with a 'document_link'. Using which, you can view the translated document.

Success Response

Copied{
    "status": "completed"
    "document_link":"https://writer.zoho.com/writer/open/e8447fe5069440a15042f5a92d4f20"

      “webhook_response”: {
	“http_status_code”:<200>,
	”message”:<message>,
	"status":"success"
	}
}

2. Failure case:

After the translation process is completed, if there is an issue with the webhook delivery (e.g., due to your server being unavailable or down), we will attempt to retry the post operation up to three times. If your server remains unreachable, the response below will be provided, allowing the user to access the document via the document_link.

Failure Response

Copied{
      "document_link": "https://writer.zoho.com/writer/open/e8447fe5069440a15042f5a92d4f20",    //will be available only on translation process success
       “webhook_response”: {
	“http_status_code”:<4xx>,
	”message”:<message>,
	"status":"failed"
	},
       "status": "completed/inprogress/failed"
}