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:

🚧

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.

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.