🚧

Not applicable if you're using Recall's Zoom OAuth Integration

As part of the Recall Zoom OAuth Integration, we do this automatically for you.

Therefore, this is not relevant and you can skip this section.

If you already have an OAuth integration and don't require Recall's Zoom OAuth integration, you can also provide join tokens for local recording to bots yourself.

Setup Guide

To obtain a Join Token for Local Recording, and provide it to the Recall bot, you must:

1. Create a Zoom OAuth application, which requests the scope meeting_token:read:local_recording
2. Create an endpoint on your server, which does the following:
   1. Validates incoming requests to see if they're coming from Recall.
      1. We recommend using a query parameter for this, as the request from Recall to retrieve the Join Token will not set any specific headers, but will preserve all query parameters contained in the URL.
      2. For example, you could check for the presence of a query parameter called endpoint_secret containing a long random string.
   2. Associates an incoming request with a specific Zoom Meeting
      1. We recommend using a query parameter containing some identifier. For example, it could be the Zoom Meeting ID itself, or it could be the primary key of a row in your database containing the Zoom Meeting ID.
   3. Uses your OAuth credentials to call the "join token for local recording" endpoint to obtain the token for the specified Zoom meeting
   4. Returns the "join token for local recording" as a plain-text string

      🚧

      If a Join Token cannot be generated, your endpoint should return an HTTP 404

      In some circumstances, you may be unable to generate a Join Token, such as if the user has not connected their Zoom account.

      If this is the case, you must return an HTTP error code such as 404. If you return an HTTP 200 and the response body does not contain a valid Join Token, the bot will fail to join the call.
      
      

3. Specify the previously mentioned endpoint zoom.join_token_url parameter when you call create_bot
   1. Immediately before the bot joins the Zoom meeting, the bot will make an HTTP GET request to the specified URL. This GET request will not contain an Authorization header, we recommend implementing authorization through a query parameter in the specified URL.
   2. The bot will provide the data contained in the HTTP response body to Zoom as the join token.
   3. If the join token is valid, the bot will immediately begin recording when it joins the call.

We have developed a simple CLI for interacting with Zoom OAuth, that allows you to connect your Zoom Account, retrieve a Join Token, and provide it to a bot. This can be helpful during development.

Troubleshooting

Bots emit fatal with zoom_invalid_join_token sub-code

This happens if your endpoint is returning an invalid join token. Common causes of this include:

1. Quotation marks (") or JSON formatting around the join token will cause the token to be invalid. The request body must contain only the join token and no other characters.
2. Expired join tokens are invalid. Join tokens are short lived (60 seconds) so extra care must be taken to ensure they are fresh.