Using a third-party closed captioning service

As a meeting host, you can add closed captions to Zoom meetings by providing the third-party closed captioning service with the caption URL. The caption URL allows the third-party service to stream text from their closed captioning software to the Zoom meeting. This article defines the format used by Zoom to receive Closed Caption data.

If you are new to using closed captioning with Zoom, please refer to our closed captioning overview. 

This article covers:

• Obtaining the caption URL (API token)
• Using the URL for closed captioning over HTTP
• Content type and data
• Response codes
• Request retries
• HTTP POST returns timestamp
• Example POST

Prerequisites for integrating with a third-party closed captioning service

• Closed caption enabled with this option selected: Allow use of caption API Token to integrate with 3rd-party Closed Captioning services
• Access to third-party close captioning service

Obtaining the caption URL (API token)

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

1. In a Zoom meeting or webinar that you are hosting, click Closed Caption.
   
2. Click Copy the API token.

Using the URL for closed captioning over HTTP

Zoom expects closed caption data to arrive in a continuous sequence of POSTs. Every meeting and breakout room session has a special URL (breakout room sessions have an additional subconfid parameter). The URL of the POST will specify the destination of the data (the meeting that the closed captions are associated with).

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:

Content type and data

The content type (mimetype) for all POSTs must be in plain text format with UTF-8 encoding.

All HTTP POSTs sent to the closed caption ingestion point must contain only closed caption data within the content body. Data must not be form encoded.

The body of the POST will contain the text for the closed caption data.  A line break can be using \n (0x0D) in the closed caption text.

Examples:

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

Response codes

HTTP POSTs may return the following response codes:

Request retries

Zoom recommends that you retry all codes. This includes the response codes 405, 400, 403 shown above, as well as additional codes such as 408 Request Timeout, 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, and 504 Gateway Timeout.

All HTTP POST requests should be performed with a timeout. If a request times out, it should be retried.

When performing retry requests, use randomized binary exponential backoff:

Wait a random period between [0..100] milliseconds and retry; if that fails, wait a random period between [0..200] milliseconds and retry; if that fails, wait a random period between [0..400] milliseconds and retry, and so on. You should retry until it makes more sense to move on to the next closed caption packet (after approximately 5 seconds).

HTTP POST returns timestamp

A timestamp value is present in the POST return body and corresponds to the time the POST was processed.  It may be used to correct the local clock on a client driving the server. 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