How to Use a third-party closed captioning service in Zoom

This post was most recently updated on July 28th, 2022

In order to add closed captions, you need to provide a third-party closed captioning service with the caption URL, which then allows you to add closed captions. This URL enables the third-party caption service to stream text from their closed captioning software to the Zoom meeting through the closed caption URL. According to this article, Zoom uses a specific data format to receive Closed Caption data.

We have an overview of closed captioning with Zoom for those who are new to using closed captions with Zoom.

Prerequisites for integrating with a third-party closed captioning service

  • Using this option, closed captioning services from 3rd parties can be integrated with caption API tokens, allowing integration with closed captioning services from 3rd parties.
  • Access to third-party closed captioning services will be available with this option.

Obtaining the caption URL (API token)

Alternatively, the host can copy the caption URL and send it via in-meeting chat to someone else. The host must enter the caption URL into closed captioning software that supports Zoom’s REST API in order to establish a connection.

  1. You can turn on closed captioning while hosting a Zoom meeting or a webinar.
  2. From the API tokens menu, click Copy.

Using the URL for closed captioning over HTTP

A continuous sequence of POSTs will be expected by Zoom for the closed caption data. There is a special URL that each meeting and breakout room session has which shows which parameters are relevant (breakout rooms have an additional parameter called subconfid). As the URL of the POST will specify the destinted of the data (the meeting that the close captions are associated with), it should specify the meeting name.

In order to add the following parameter to the URL of every POST request, it must be added as follows:

Name Description Example fragment
 seq The fragment seq must be included in all posts. There should be a counter for each closed caption data post. Between posts of new caption data, the counter must be incremented by one (it should not be incremented for retrying).

You can retrieve the seq number of the last successful send using the following API method: /closedcaption/seq [GET]

&seq
 lang This is separated by the hyphen by the language code and country code linked to the language code.

For example:

  • German: de-DE
  • English:en-US
  • Japanese: jp-JP
  • Spanish: es-ES
  • French: fr-FR
  • Chinese: zh-CN
&lang=en-US

Content type and data

All post types (mimetypes) for all POST requests need to be in plain text format with UTF-8 encoding.

Closed caption content must be the only thing sent with the HTTP POST to the closed caption ingestion point within the body of the content. Form-encoding must not be used to encode the data.

This will be the body of the post where the closed caption data will be added.  The closed caption text can be broken up with the use of the /n (0x0D).

Examples:

  • 1st HTTP post data: I’M SENDING
  • 2nd HTTP post data: SEVERAL CAPTIONS.\n

Response codes

The following response codes may be returned by HTTP POSTs:

Response code Description
405 The method you are trying to use isn’t permitted. Posting is not allowed.
400 Internal Server Error. There has been no start of the meeting yet.
403 Unauthorized access. There is a possibility that &seq may be missing from the query, &id, &signature, &expire, or &ns could be missing during the execution.

 

Request retries

Please retry all of your codes according to Zoom’s recommendation. There are several different types of response codes that can be attributed to this, which include error codes such as 408 Request Timeout, 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, and 504 Gateway Timeout.

There should be a timeout applied to all HTTP POST requests. This would allow retrying of a failed request if it times out.

Whenever you are retrying a request, you should use randomized binary exponential backoff:

Upon receiving a response, wait for a random period between [0..100] milliseconds before retrying; if that fails, wait a random period between [0..200] milliseconds before retrying; if that fails, wait a random period between [0..400] milliseconds before retrying, and so on. The retrying process should continue until it becomes increasingly important to move on to the next closed caption packet (approximately after 5 seconds).

HTTP POST returns timestamp

Upon completing a POST request, the response body contains a timestamp value, which reflects the time when the POST request was processed.  If a client drives the server from the client’s computer, the time on the client may need to be corrected. Due to the fact that local clocks are often not synchronized with each other, Zoom recommends using this value.

This is an example of a timestamp returned by the API: 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