Bot Webhooks

Use bot webhook events to trigger server logic and create a real-time experience.

Bot Status Changes


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:

Bot Logs


Bot webhooks also include events for bot logs, providing detailed information about certain failure modes.

Events

You should listen to these to detect errors that occur in your bots.

Status codeDescription
bot.logDetailed information about certain failure modes of the bot.
bot.output_logDetailed information about certain failure modes of the bot, related to a specific output of the bot.

There are several warnings/errors that can trigger bot.log events:

  • Failure to send chat messages

There are several warnings/errors that can trigger bot.output_log events:

The shape of the log payloads are as follows:

{
  "event": "bot.log"|"bot.output_log",
  "data": {
    "bot_id": string | absent, // Present for all but async transcription job logs
    "job_id": string | absent, // Present for async transcription job logs
    "log": {
      "level": string,
      "message": string,
      "output_id": string | null,
      "created_at": string
    }
  }
}

Real-time transcription errors

If you configure your bot for real-time transcription, and the bot receives a fatal error communicating with the transcription provider, Recall will emit a bot.output_log event for the bot with details about the error.

For example, if I provide an invalid API key for a transcription provider, I will receive a log event notifying me about this:

{
  "data": {
    "bot_id": "fc75fbf8-4a87-4438-bca8-83200962a1eb",
    "log": {
      "created_at": "2024-03-10T19:16:16+00:00",
      "level": "error",
      "message": "Failed to connect to transcription provider: Error connecting to transcription provider: Http(Response { status: 401, version: HTTP/1.1, headers: {\"content-type\": \"application/json\", \"dg-error\": \"Invalid credentials.\", \"content-length\": \"112\", \"access-control-allow-credentials\": \"true\"}",
      "output_id": "9aac7fc7-f4fc-4d70-8845-d9cc371cbe17"
    }
  },
  "event": "bot.output_log"
}

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.

Why is my webhook endpoint disabled?

If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled. The clock only starts after multiple deliveries failed within a 24 hour span, with at least 12 hours difference between the first and the last failure.