Quickstart

Learn how to send a bot to a meeting and retrieve the recording.

1. Initial setup

Create an API Key in the Recall dashboard. This will be used for API authentication.

2. Create a meeting

We recommend using Google Meet for this quickstart. You can create one quickly by navigating to meet.new. After you create the meeting, stay in the meeting you created, and save the meeting URL for the next step.

3. Send a bot to the meeting

Use the Create Bot endpoint to send a bot to a meeting.

  • Swap the $RECALLAI_API_KEY placeholder in Authorization with your API key
  • Swap the $RECALLAI_REGION placeholder with the region associated with your Recall account (e.g. us-west-2, us-east-1, eu-central-1, or ap-northeast-1)
  • Swap the placeholder in $MEETING_URL with the meeting URL from the previous step.
curl -X POST https://$RECALLAI_REGION.recall.ai/api/v1/bot \
    -H 'Authorization: Token $RECALLAI_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '
    {
      "meeting_url": "$MEETING_URL",
      "bot_name": "My Bot",
      "transcription_options": {"provider": "meeting_captions"}
    }'

The response will include a Bot ID (in id). Save it for the next few steps.
If everything works, the command-line displays a response in the following shape.

{
    "id": "5603dea-b633-4b35-995c-fec5415c8d",
    "video_url": null,
    "status_changes": [
        {
            "code": "ready",
            "message": null,
            "created_at": "2023-03-23T18:59:40.391872Z"
        }
    ],
    "meeting_metadata": null,
    "meeting_participants": [],
    "speaker_timeline": {
        "timeline": []
    },
    "calendar_meeting_id": null,
    "calendar_user_id": null,
    "calendar_meetings": []
}

4. Talk for a little bit

While you and the bot are in the meeting, make sure to turn on your video or talk for a little bit. This way, there will be actual content in the video recording the bot produces for you to look at after.

5. End the meeting

Once you feel like there is enough content in the meeting, end the meeting. The bot will automatically leave.

6. Wait for done

Once the meeting is done, Recall begins processing the video recording. This typically takes less than 10 seconds no matter the length of the meeting.

When the recording is ready to be downloaded, the bot status changes to done.

The best way to retrieve this is via webhooks. See the Webhook Overview for details.

If you can't use webhooks for some reason, you can manually poll Retrieve Bot to see the bot status.

7. Retrieve the recording

To retrieve the recording the bot created, use the Retrieve Bot endpoint.

  • Swap the $BOT_ID with the id you saved in Step 3.
  • Swap the $RECALLAI_API_KEY placeholder in Authorization with your API key
  • Swap the $RECALLAI_REGION placeholder with the region associated with your Recall account (e.g. us-west-2, us-east-1, eu-central-1, or ap-northeast-1)
curl -X GET https://$RECALLAI_REGION.recall.ai/api/v1/bot/$BOT_ID \
	-H 'Authorization: Token $RECALLAI_API_KEY'

The response will include a video url (in video_url). Copy and paste this URL into your web browser to view.

Recall deletes the recording files after 7 days, indicated by media_retention_end in the response. In practice, you should download the recording and upload to your own servers right after you receive the done webhook event.

{
    "id": "5603dea-b633-4b35-995c-fec5415c8d",
    "video_url": "https://recallai-prod-bot-data.s3.amazonaws.com/5603dea6-b633-4b35-995c-f5ec5415c8d9/video.mp4?AWSAccessKeyId=ASIAVO7R4VZXGRMCWGEG&Signature=MAcf%2BT60SRkLWsJGpCQFByiWUIk%3D&x-amz-security-token=IQoJb3JpZ2luX2VjEPb%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJHMEUCIAng4YEGGZ9OK804stMvVIp2AJTyBXshfAWnv9Hi7OQmcZSaIE3h8A36mZCNMRwi%2B6sixPO8%2BJ3izmtAwghcLnZLdK4v1xLhpWik0h8e1RVA2hb4t9KFmPKvAxecXc2KCONPYpUvF1V1KSmJzvYOBmcqAt7nKWZMjMWVW6C%2FcQPMo6tm65BlUdO8bSYpa6Wjs2CqfmytFpxxEr5RrFAG1NkMAKDZXvhcukjZfrJsC%2BppCOviIEGocdb6CtJTJrwFvuZ8DzRPmDiPemF2KLP2SA7nSiZH0UYgBmhokDT8Cjlc0B13Edf%2BrfH8xr8RlA5vFHKULYwi4O6Ls4YDD%2B7dMeDLjxC&Expires=1680203740",
    "media_retention_end": "2023-03-30T19:15:38.453951Z",
    "status_changes": [
        {
            "code": "ready",
            "message": null,
            "created_at": "2023-03-23T18:59:40.391872Z"
        },
        {
            "code": "joining_call",
            "message": null,
            "created_at": "2023-03-23T19:05:33.221294Z"
        },
        {
            "code": "in_waiting_room",
            "message": null,
            "created_at": "2023-03-23T19:05:36.773949Z"
        },
        {
            "code": "in_call_not_recording",
            "message": null,
            "created_at": "2023-03-23T19:05:46.118246Z"
        },
        {
            "code": "in_call_recording",
            "message": null,
            "created_at": "2023-03-23T19:05:46.129127Z"
        },
        {
            "code": "call_ended",
            "message": null,
            "created_at": "2023-03-23T19:15:34.127658Z"
        },
        {
            "code": "done",
            "message": null,
            "created_at": "2023-03-23T19:15:38.453951Z"
        }
    ],
    "meeting_metadata": null,
    "meeting_participants": [
      {
        "id": 100,
        "name": "John Doe",
        "events": [
          {
            "code": "join",
            "created_at": "2023-03-23T19:05:33.738402Z"
          }
        ],
        "is_host": true,
        "platform": "unknown",
        "extra_data": null
      }
    ],
    "calendar_meeting_id": null,
    "calendar_user_id": null,
    "calendar_meetings": []
}

8. Retrieve the transcript

To retrieve the transcript for the meeting, use the Get Bot Transcript endpoint.

  • Swap the $BOT_ID with the id you saved in Step 3.
  • Swap the $RECALLAI_API_KEY placeholder in Authorization with your API key
  • Swap the $RECALLAI_REGION placeholder with the region associated with your Recall account (e.g. us-west-2, us-east-1, eu-central-1, or ap-northeast-1)
curl -X GET https://$RECALLAI_REGION.recall.ai/api/v1/bot/$BOT_ID \
	-H 'Authorization: Token $RECALLAI_API_KEY'

The response will be in the following format:

[
  {
    "words": [
      {
        "text": "This is a transcription test!",
        "start_timestamp": 2.1823506355285645,
        "end_timestamp": 6.80250883102417,
        "language": null,
        "confidence": null
      }
    ],
    "speaker": "Test User 1",
    "speaker_id": 16778240,
    "language": "en",
    "participant": {...}
      }
    }
  },
  {
    "words": [
      {
        "text": "Sounds good to me!",
        "start_timestamp": 7.146152496337891,
        "end_timestamp": 13.166593551635742,
        "language": null,
        "confidence": null
      }
    ],
    "speaker": "Test User 2",
    "speaker_id": 16784384,
    "language": "en",
    "participant": {...}
      }
    }
  },
    ...
]

View the bot in the Explorer

You can view all the information produced by the bot in one place when viewing it in Recall's Explorer.

  • Swap the $BOT_ID with the id you saved in Step 3.
  • Swap the $RECALLAI_REGION placeholder with the region associated with your Recall account (e.g. us-west-2, us-east-1, eu-central-1, or ap-northeast-1)
https://$RECALLAI_REGION.recall.ai/dashboard/explorer/bot/$BOT_ID

Paste this link into your browser to get a full picture of everything the bot was able to record from your test meeting!


Next steps

Now that you have a sense of how to work with Recall's API, here are a few things to try next:

This will allow your bot to transcribe conversations in real-time, allowing you to react to conversation data as soon as it's spoken.

This will allow you to transcribe conversations after they've ended.

Learn how to start sending bots to Zoom calls!