> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amongst.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting the data

> Learn how to receive and process meeting data through webhooks, including live events and post-meeting recordings <br></br><br></br> 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 call the Retrieve meeting data endpoint to get the meeting details.

## Webhook Overview

To access your meeting data, listen for POST requests sent to the webhook URL configured in the request. You will receive two types of data:

1. **Live Meeting:** Real-time updates as the agent interacts during the meeting. Currently, these events include agent status updates.
2. **Post-Meeting Data:** Information collected after the meeting concludes, including video recordings and speech time events.

### 1. Live Meeting Events

The live events sent to your webhook will follow this format:

```http theme={null}
POST /your-endpoint HTTP/1.1
Host: your-company.com
Content-Type: application/json

{
  "event": "agent.status_change",
  "data": {
    "agentId": "240b2f22-785d-451a-bb7f-3084344a96fb",
    "status": {
      "code": "in_waiting_room",
      "created_at": "2024-08-10T11:00:00.000Z"
    }
  }
}
```

#### Event Fields:

* **event:** The key-value pair indicating the type of event. This will always be `agent.status_update` for agent status events.
* **data:** Contains details about the agent's status:
  * **agentId:** The unique identifier of the agent.
  * **status:** An object containing the following properties:
    * **code:** Represents the current status of the agent. Possible values include:
      * **joining\_call:** The agent has acknowledged the request to join the call.
      * **in\_waiting\_room:** The agent is currently in the "waiting room" of the meeting.
      * **recording\_started:** The agent is in the meeting and actively recording audio and video.
      * **recording\_completed:** The agent has stopped recording the meeting.
      * **call\_ended:** The agent has left the call.
    * **created\_at:** An ISO 8601 formatted string representing the date and time when the event occurred.

### 2. Success Webhook

To receive the final meeting data, you need to listen for POST requests sent to the webhook URL you’ve set up in your account.
You will receive one of two event types:

* **"event": "complete"** – Indicates that the meeting recording and processing have successfully finished.
* **"event": "failed"** – Indicates that the agent encountered an error and the meeting data couldn't be processed.

#### Example: Complete Event

Here’s an example of the payload you'll receive for a successful event, assuming your webhook URL is `https://your-company.com/your-endpoint`:

```http theme={null}
POST /your-endpoint HTTP/1.1
Host: your-company.com
Content-Type: application/json

{
  "event": "complete",
  "data": {
    "agentId": "240b2f22-785d-451a-bb7f-3084344a96fb",
    "recording": {
        "url": "https://your-bucket-name/meeting-data/GMEET/ciy-ngkb-rpw/323121fa-f543-4559-ab2e-ef200...",
        "startedAt": "2024-12-13T22:15:19.309Z",
        "completedAt": "2024-12-13T22:17:22.942Z"
    },
    "participants": [{ "name": "Steve" }, { "name": "Diana" }],
    "transcript": [{
      "speaker": "Steve",
      "start_timestamp": 60.73544357800001,
      "end_timestamp": 62.246695605,
      "words": [
        {
          "start_timestamp": 60.73544357800001,
          "end_timestamp": 61.5,
          "text": "Hi, Diana!"
        },
        {
          "start_timestamp": 61.8,
          "end_timestamp": 62.246695605,
          "text": "How are you?"
        }
      ]
    },
    {
      "speaker": "Diana",
      "start_timestamp": 63.236073276,
      "end_timestamp": 65.90755039,
      "words": [
        {
          "start_timestamp": 63.236073276,
          "end_timestamp": 64.0,
          "text": "Hi, Steve!"
        },
        {
          "start_timestamp": 64.5,
          "end_timestamp": 65.90755039,
          "text": "I’m good, you?"
        }
      ]
    }],
    "speakerTimeline": [{ "speaker": "Steve", start_timestamp: 60.73, end_timestamp: 62.2 }, ...]
  }
}
```

### 3. Failed Webhook

Here’s an example of the payload you'll receive for a failed event, assuming your webhook URL is `https://your-company.com/your-endpoint`:

```http theme={null}
POST /your-endpoint HTTP/1.1
Host: your-company.com
Content-Type: application/json

{
  "event": "failed",
  "data": {
    agentId: "240b2f22-785d-451a-bb7f-3084344a96fb",
    error: "meetingNotFound"
  }
}
```

#### The failure types can be:

| **Error**                    | **Description**                                                                                                                                            |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ServerError`                | An unexpected error occurred. Please contact us if the issue persists.                                                                                     |
| `InvalidMeetingUrl`          | The meeting URL provided is not a valid (Zoom, Meet, Teams) URL.                                                                                           |
| `WaitingRoomTimeoutExceeded` | The agent was not admitted within the provided time. By default, this time is 15 minutes, but it can be configured via `automaticLeave.waitingRoomTimeout` |
| `DeniedFromWaitingRoom`      | The agent was denied entry from the waiting room.                                                                                                          |
| `meetingNotFound`            | No meeting was found at the given link.                                                                                                                    |
| `cannotJoinMeeting`          | The bot could not join the meeting URL provided. .                                                                                                         |
| `meetingPasswordIncorrect`   | The meeting password is incorrect.                                                                                                                         |

## Retrieve the Meeting Recording

To access the recording generated by the agent, use the Retrieve Meeting Data API endpoint. Replace the AGENT-ID with the ID you saved in Step 1, and substitute the Authorization placeholder with your API key.

<Tabs>
  <Tab label="cURL" title="Bash">
    ```bash theme={null}
    curl -X GET "https://your-hosted-ip/api/v1/agent/YOUR-AGENT-ID/meeting-data" \
    -H "Authorization: Token YOUR_API_KEY"
    ```
  </Tab>

  <Tab label="JavaScript" title="JavaScript">
    ```javascript theme={null}
    const agentId = 'YOUR-AGENT-ID'; // Replace with your Agent ID
    fetch(`https://your-hosted-ip/api/v1/agent/${agentId}/meeting-data`, {
        method: 'GET',
        headers: {
          'Authorization': `Token ${YOUR_API_KEY}`
        }
    })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));
    ```
  </Tab>

  <Tab label="Python" title="Python">
    ```python theme={null}
    import requests

    agent_id = 'YOUR-AGENT-ID' # Replace with your Agent ID
    url = f"https://your-hosted-ip/api/v1/agent/{agent_id}/meeting-data"
    headers = {
    "Authorization": f"Token {YOUR_API_KEY}"
    }

    response = requests.get(url, headers=headers)
    data = response.json()
    print(data)
    ```
  </Tab>
</Tabs>