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 HTTP2xx
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 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:
![](https://files.readme.io/17216cb-Bot_Status_Transition_Flow_Chart.png)
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 code | Description |
---|---|
bot.log | Detailed information about certain failure modes of the bot. |
bot.output_log | Detailed 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:
- Real-time transcription errors
- Zoom OAuth integration warnings
- RTMP connection errors
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.
Updated 26 days ago