Bot Sub Codes

Sub codes are a field (sub_code) added to certain bot status change events to provide extra context.

Here's an example of a status change object structure:

JSON

{
  "code": "call_ended",
  "sub_code": "bot_kicked_from_call", // machine readable
  "message": "The bot was kicked from the call.", // human readable description of the sub_code
  "created_at": "2023-04-28T08:51:37.741790Z"
}

Here, we can interpret this status change as follows:

• Code: call_ended - The status change event category (Call Ended)
• Sub Code: bot_kicked_from_call - The underlying reason for the status change (sub code

Sub Code Types

Currently there are 3 distinct sub code categories:

• Call Ended Sub Codes
• Fatal Sub Codes
• Recording Permission Denied (Zoom only)

Sub Code Type	Event	Platforms
Call Ended	call_ended	All
Fatal	fatal	All
Recording Permission Denied	recording_permission_denied	Zoom

Note: Platform specific sub_codeis prefixed with platform name (e.g zoom_sdk_credentials_missing)

🚧

We may add additional sub_codes

You should not treat the sub_code as an enum, as we may add values in the future without prior notice. We will never remove values without notifying all our customers and a long depreciation period, as we consider removing values a breaking change.

Recording Permission Denied Sub Codes

Since Zoom bots have a few extra requirements to meet for recording, there are more places that bots can run into trouble.

When a bot fails to record in a Zoom call, the recording_permission_denied webhook event will include a Zoom-specific sub code that provides more context into the reason it failed.

These sub_code will be added to the recording_permission_denied event.

Sub Code	Description
zoom_local_recording_disabled	The meeting host has their global user-level local recording setting disabled. More info The host was not presented with the recording consent popup.
zoom_local_recording_request_disabled	The meeting host has their user-level local recording setting enabled, but the has disabled the advanced recording option labelled "Hosts can give meeting participants permission to record locally". More info The host was not presented with the recording consent popup.
zoom_local_recording_request_disabled_by_host	The meeting host has disabled participants from requesting local recording permission or has denied all future requests. More info The host was not presented with the recording consent popup.
zoom_bot_in_waiting_room	The bot is in the waiting room due to which local recording cannot be requested. The host was not presented with the recording consent popup.
zoom_host_not_present	The host was not present in the meeting when the bot requested local recording permission. The host was not presented with the recording consent popup.
zoom_local_recording_request_denied_by_host	The host denied the bot's local recording request. The host was presented with the recording consent popup.
zoom_local_recording_denied	The Zoom SDK credentials are not configured in Recall dashboard.
zoom_local_recording_grant_not_supported	The meeting host is using Zoom Web client or a Zoom Room to host the meeting which does not support local recording permission.
zoom_sdk_key_blocked_by_host_admin	The Zoom SDK key used by the bot is blocked by the Zoom user's workspace admin.

Call Ended Sub Codes

The call_ended event signifies that a bot left, or was removed from, the call.

Recall attaches a sub_code to these events to expose the underlying reason why the bot is no longer in the call. This can be for obvious reasons such as the host ending the call (call_ended_by_host), but sometimes its less obvious why a bot left a call.

Below is a list of all call ended sub codes and what they mean.

Sub Code	Description
call_ended_by_host	The call has been ended by the meeting host.
call_ended_by_platform_idle	The call has been ended by the meeting platform, because it was idle.
call_ended_by_platform_max_length	The call has been ended by the meeting platform because it reached the maximum meeting length.
call_ended_by_platform_waiting_room_timeout	The bot could not join the call because meeting platform's maximum waiting room time exceeded. For Google Meet, this is 10 minutes. Zoom and Meet don't have a timeout.
timeout_exceeded_waiting_room	The bot left the call because it was in the waiting room for too long. This is the timeout specified by automatic_leave.waiting_room_timeout.
timeout_exceeded_noone_joined	The bot left the call because nobody joined the call for too long.
timeout_exceeded_everyone_left	The bot left the call because everyone else left.
timeout_exceeded_silence_detected	The bot left the call because all other participants were likely bots based off continuous silence detection heuristic.
timeout_exceeded_only_bots_detected_using_participant_names	The bot left the call because all other participants were likely bots based off participant names heuristic.
timeout_exceeded_only_bots_detected_using_participant_events	The bot left the call because all other participants were likely bots based off participant events heuristic.
timeout_exceeded_only_bots_in_call	The bot left the call because all other participants were likely bots.
timeout_exceeded_in_call_not_recording	The bot left the call because it never started recording e.g. remained in the in_call_not_recording state for longer than automatic_leave.in_call_not_recording_timeout
bot_kicked_from_call	The bot was removed from the call by the host.
bot_kicked_from_waiting_room	The bot was removed from the waiting room by the host.
bot_received_leave_call	The bot received leave call request.

Fatal Sub Codes

When a bot hits a fatal error, a fatal event is emitted with an attached sub_code that provides more context. Below is a list of possible fatal sub codes, their meaning, and any recommended action to take, if any.

sub_code	Message	Recommended action
bot_errored	The bot ran into an unexpected error.
meeting_not_found	No meeting was found at the given link.
meeting_not_started	The meeting has not started yet.
meeting_requires_sign_in	The meeting can only be joined by signed in users.	Incase of Zoom bots, this error message means that the Zoom meeting has only authenticated users can join enabled. By default, the bot is unauthenticated, so it cannot join these calls. To bypass this error, follow the steps in Joining "Sign In Required" Zoom Meetings.
meeting_link_expired	The meeting link has expired.
meeting_link_invalid	The meeting does not exist or the link is invalid.
meeting_password_incorrect	The meeting password is incorrect.
meeting_locked	The meeting is locked.
meeting_full	The meeting is full.
meeting_ended	The bot attempted to join a meeting that has already ended and can no longer be joined.
google_meet_sign_in_failed	The bot was not able to sign in to google.
google_meet_sign_in_captcha_failed	The bot was not able to sign in to google because of captcha.
google_meet_sign_in_missing_login_credentials	The bot was not able to sign in to google because login credentials were not configured.	Create an Authenticated Google Meet Bot to allow your bots to join sign-in-only Google Meet meetings.
google_meet_sign_in_missing_recovery_credentials	The bot was not able to sign in to google because recovery credentials were not configured.
google_meet_sso_sign_in_failed	The bot was not able to sign in to google with SSO.
google_meet_sso_sign_in_missing_login_credentials	The bot was not able to sign in to google with SSO because login credentials were not configured.
google_meet_sso_sign_in_missing_totp_secret	The bot was not able to sign in in to google with SSO because TOTP secret was missing from password.
google_meet_video_error	The bot was not able to join the call due to Google Meet video error.
google_meet_meeting_room_not_ready	The bot was not able to join the call as the meeting room was not ready.
google_meet_login_not_available	There were not enough available logins (Google accounts) in the supplied google_login_group_id for the bot to use.	Create additional Google logins as outlined here.
zoom_sdk_credentials_missing	The bot was not able to join because Zoom SDK credentials were not configured.
zoom_sdk_update_required	A newer version of the Zoom SDK is required to join this meeting.
zoom_sdk_app_not_published	The SDK credentials configured in Recall dashboard have not been approved by Zoom. Bots using unapproved Zoom credentials can only join meetings hosted in the workspace of the user that created the credentials.
zoom_email_blocked_by_admin	The Zoom account this bot is joining from has been disallowed to join this meeting by the Zoom workspace administrator.
zoom_registration_required	The bot failed to join because registration is required for this Zoom meeting.
zoom_captcha_required	The bot failed to join because captcha is required for this Zoom meeting.
zoom_account_blocked	The account this bot is joining from has been blocked by Zoom.
zoom_invalid_signature	The Zoom SDK was not able to generate a valid meeting-join signature. This could mean that the meeting link is malformed, or the Zoom SDK credentials provided are invalid.	If you haven't already, follow this guide to set up Zoom credentials. If these are already set up, ensure that the host of the meeting belongs to the same Zoom workspace the credentials were created in.
zoom_internal_error	The bot failed to join due to an internal Zoom error.
zoom_join_timeout	The request to join the Zoom meeting timed out.
zoom_email_required	The bot failed to join because providing an email is required to join this Zoom meeting.	Provide a zoom.user_email when creating the bot as outlined in Email Required Meetings.
zoom_web_disallowed	The Zoom meeting host has disallowed joining from the web which prevents the bot from joining the meeting.	Have the host disable E2E encryption for the meeting. If E2E encryption support is required by the user, you can use the Zoom Native bot to join these meetings.
zoom_meeting_not_accessible	The Zoom meeting was not accessible for the bot.
microsoft_teams_call_dropped	The bot got call dropped error from MS Teams and was unable to re-join the call.
microsoft_teams_sign_in_credentials_missing	The bot failed to join a Microsoft Teams meeting requiring all participants to be signed-in. The bot was not signed in and thus was not able to join the call.
webex_join_meeting_error	The bot failed to join a Webex meeting because the meeting was invalid, or Webex credentials are not set up properly.	If Webex credentials are not set up, follow the Webex Bot Setup guide.