Using a third-party closed captioning service in zoom App
When you host a Zoom meeting, you can add closed captions by sending the caption URL to a third-party closed captioning service. Using the caption URL, the third-party service can stream text from their closed captioning software to the Zoom meeting. Zoom receives Closed Caption data in this format..
The Zoom closed captioning overview is a good place to start if you are new to using closed captioning.
Prerequisites for integrating with a third-party closed captioning service
- Enable Closed Captioning if this option is selected: Allow integration of Closed Captioning API Token with 3rd-party services
- Providing access to third-party close captioning services
Obtaining the caption URL (API token)
The host or co-host must copy the caption URL and paste it into a closed captioning software that supports Zoom’s closed captioning REST API. Alternatively, the host can copy the URL and share it using the in-meeting chat feature.
- In a Zoom meeting or webinar that you are hosting, click Closed Caption.
- Click Copy the API token.
Using the URL for closed captioning over HTTP
A continuous sequence of POSTs is expected by Zoom for closed caption data. Meetings and breakout rooms have their own URLs (breakout rooms have a subconfid parameter). A POST will specify the destination of the data (the meeting associated with the closed captions).
Example: https://wmcapi.zoom.us/closedcaption?id=200610693&ns=GZHkEA==&expire=86400&spparams=id%2Cns%2Cexpire&signature=nYtXJqRKCW
The following parameter needs to be added to the URL of every POST:
Name | Description | Example fragment |
seq | Must be contained in all POSTs. Counter for all closed caption data posts. Counter must increase by one between posts of new caption data (it must not be increased for retries).
The seq number of the last successful send can be obtained through the API: /closedcaption/seq [GET] |
&seq |
lang | The language code and ISO country code separated by a hyphen. Examples:
|
&lang=en-US |
Content type and data
For all POSTs, the content type (mimetype) must be plain text with UTF-8 encoding.
The content body of all HTTP POSTs sent to the closed caption ingestion point must contain only closed caption data. No form-encoding is allowed.
In the body of the post, the closed caption data will be included. Closed caption text can be broken up with /n (0x0D).
Examples:
- 1st HTTP post data: I’M SENDING
- 2nd HTTP post data: SEVERAL CAPTIONS.\n
Response codes
HTTP POSTs may return the following response codes:
Response code | Description |
405 | Method not allowed. Not a POST. |
400 | Bad request. The meeting has not started. |
403 | Unauthorized. Could be due to missing &seq query parameter or missing &id, &signature, &expire or &ns. |
Request retries
You should retry all codes, according to Zoom. The response codes 405, 400, and 403 shown above are included, as well as additional codes such as 408 Request Timeout, 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, and 504 Gateway Timeout.
A timeout should be applied to all HTTP POST requests. Retries should be performed if a timeout occurs.
Utilize randomized binary exponential back off when performing retry requests:
Retry after a random period between [00..100] milliseconds. If that fails, try again after a random period between [00..200] milliseconds. If that fails, try again after a random period between [00..400] milliseconds. You shoul After approximately 5 seconds, you should retry until it makes more sense to move on to the next closed caption packet.
HTTP POST returns timestamp
POST return bodies contain a timestamp that indicates when the request was processed. A client driving the server can use it to correct the local clock. Zoom strongly recommends using this value because local clocks are often poorly synchronized.
Example returned timestamp: 2012-12-24T00:00:06.873
Example POST
POST /closedcaption?id=200610693&ns=GZHkEA==&expire=86400&sparams=id%2Cns%2Cexpire&signature=nYtXJqRKCW&seq=41&lang=en-US Host: wmcapi.zoom.us:80 Accept: */* Content-Type: text/plain Content-Length: 11 I'M SENDING
POST /closedcaption?id=200610693&ns=GZHkEA==&expire=86400&sparams=id%2Cns%2Cexpire&signature=nYtXJqRKCW&seq=42&lang=en-US Host: wmcapi.zoom.us:80 Accept: */* Content-Type: text/plain Content-Length: 18 SEVERAL CAPTIONS.\n