Bot Status Change Webhooks

Receive bot status webhook events to create a real-time experience.

Recall uses bot status changes to capture the lifecycle of a bot.

These status changes are exposed through webhooks, which your application can use to create a real-time experience or react to asynchronous events outside of the API request cycle.

For example, you may want to update something on your end when a bot transitions its status from joining_call to in_call_recording. When these asynchronous events happen, we'll make a POST request to the address you give us and you can do whatever you need with it on your end.

After a webhook is configured for an environment, notifications will be sent for all events for that environment.

🚧

Important webhook handler considerations

  • 2xx response: Your webhook handler should return a HTTP 2xx Code
  • Retries: If Recall doesn't receive a 2xx response from your server, we will continue to try the message for the next 24 hours, with an increasing delay between attempts.
  • Timeouts: Webhook events have a timeout of 15 seconds. If you plan to kick off longer running tasks upon receiving certain events, make sure to do this asynchronously so you respond to requests before they time out.

Events

This webhook is sent whenever the bot's status is changed and is delivered via Svix to the endpoints configured in your Recall dashboard.

{
  "event": "bot.status_change",
  "data": {
    "bot_id": string,
    "status": {
      "code": string,
      "created_at": string,
      "sub_code": string | null,
      "message": string | null,
      "recording_id": string | absent
    },
  }
}

The possible values for data.status.code are the following:

Status codeDescription
readyThis is an internal status and should be ignored
joining_callThe bot has acknowledged the request to join the call, and is in the process of connecting.
in_waiting_roomThe bot is in the "waiting room" of the meeting.
participant_in_waiting_roomA participant has joined the waiting room (The bot is in the call)
in_call_not_recordingThe bot has joined the meeting, however is not recording yet. This could be because the bot is still setting up, does not have recording permissions, or the recording was paused.
recording_permission_allowedThe bot has joined the meeting and it's request to record the meeting has been allowed by the host. (only for Zoom bots with New SDK)
recording_permission_deniedThe bot has joined the meeting and it's request to record the meeting has been denied. Refer to sub_code field for exact reason. (only for Zoom bots with New SDK)
in_call_recordingThe bot is in the meeting, and is currently recording the audio and video.
call_endedThe bot has left the call, and the real-time transcription is complete.
The data.status.sub_code will contain machine readable code for why the call ended & data.status.message will contain human readable description for the same.
recording_doneThe recording has completed.
doneThe bot has shut down. If bot produced in_call_recording event, the video is uploaded and available for download.
fatalThe bot has encountered an error that prevented it from joining the call. The data.status.sub_code will contain machine readable code for why bot failed. data.status.message will contain human readable description for the same.
analysis_doneAny asynchronous intelligence job (like transcription or audio intelligence) has been completed.
analysis_failedAny asynchronous intelligence job (like transcription or audio intelligence) has failed.
media_expiredThe video, audio, metadata, debug data, and transcription have been deleted from Recall's servers.

🚧

We may add additional Status Change event codes

You should not treat the data.status.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.

The list of sub_code & corresponding message values that may be produced for call_ended/fatal status changes can be found here here.

Bot Status Transition Diagram

This diagram provides a detailed view of bot statuses:

FAQ

Where do I find my signing secret?

Head over to the Recall webhooks dashboard and click into the endpoint.

You'll find the signing secret near the bottom right hand corner: