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.

JSON

{
  "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 code	Description
ready	This is an internal status and should be ignored
joining_call	The bot has acknowledged the request to join the call, and is in the process of connecting.
in_waiting_room	The bot is in the "waiting room" of the meeting.
participant_in_waiting_room	A participant has joined the waiting room (The bot is in the call)
in_call_not_recording	The 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_allowed	The 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_denied	The 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_recording	The bot is in the meeting, and is currently recording the audio and video.
call_ended	The 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_done	The recording has completed.
done	The bot has shut down. If bot produced in_call_recording event, the video is uploaded and available for download.
fatal	The 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_done	Any asynchronous intelligence job (like transcription or audio intelligence) has been completed.
analysis_failed	Any asynchronous intelligence job (like transcription or audio intelligence) has failed.
media_expired	The 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:

Can I filter which events I subscribe to?

Currently, filtering events isn't supported. This means you will receive all bot status change events for the lifecycle of your bots. If you don't need to use certain bot status change events, you can simply return a 2xx success status code.