Skip to main content

​
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: 
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: 
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: 
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:

ErrorDescription
ServerErrorAn unexpected error occurred. Please contact us if the issue persists.
InvalidMeetingUrlThe meeting URL provided is not a valid (Zoom, Meet, Teams) URL.
WaitingRoomTimeoutExceededThe agent was not admitted within the provided time. By default, this time is 15 minutes, but it can be configured via automaticLeave.waitingRoomTimeout
DeniedFromWaitingRoomThe agent was denied entry from the waiting room.
meetingNotFoundNo meeting was found at the given link.
cannotJoinMeetingThe bot could not join the meeting URL provided. .
meetingPasswordIncorrectThe 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.
  • Bash
  • JavaScript
  • Python
curl -X GET "https://your-hosted-ip/api/v1/agent/YOUR-AGENT-ID/meeting-data" \
-H "Authorization: Token YOUR_API_KEY"