Schedule a Meeting Agent BETA

Required plan: Emerging

In addition to attaching a Meeting Agent to an event it is possible to directly schedule a Meeting Agent to join a meeting either immediately or in the future.

Immediate dispatch #

When dispatching immediately, only a join_url is required, and the response will contain the Meeting Agent state at the point of creation.

Future state changes and meeting artefacts are available as part of notification callbacks.

Meeting Agents created this way will be dispatched as soon as possible. Scheduling for a future time, when possible, will give you a more reliable timing as it allows us to provision the required resources ahead of time.

Example Request #

POST /v1/meeting_agents HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}
Content-Type: application/json; charset=utf-8

{
  "join_url": "https://teams.microsoft.com/meet/00000000000000?p=abcdefg",
  "subscriptions": [
    {
      "type": "webhook",
      "uri": "https://example.com/notification",
      "interactions": [
        { "type": "meeting_agent_activated" },
        { "type": "meeting_agent_complete" },
        { "type": "meeting_agent_failed" }
      ]
    }
  ]
}

Example Response #

HTTP/1.1 200 OK

{
    "sub": "agt_692702a100ccd07000000000",
    "state": "created",
    "resources": [
      {
        "category": "cronofy",
        "type": "dashboard",
        "url": "https://..."
      }
    ]
  }

Future scheduling #

When scheduling for the future, scheduling_key and join_time parameters are provided and a 202 Accepted response is generated. Status information, and meeting artefacts will provided as part of notification callbacks.

Example Request #

POST /v1/meeting_agents HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "scheduling_key": "your-identifier-for-this-unique-meeting",
  "join_time": "2026-01-25T15:30:00Z",
  "join_url": "https://teams.microsoft.com/meet/00000000000000?p=abcdefg",
  "subscriptions": [
    {
      "type": "webhook",
      "uri": "https://example.com/notification",
      "interactions": [
        { "type": "meeting_agent_activated" },
        { "type": "meeting_agent_complete" },
        { "type": "meeting_agent_failed" }
      ]
    }
  ]
}

Example Response #

HTTP/1.1 202 Accepted

Request Parameters #

data_center_url required

The URL for the data center you want to communicate with. Possible choices are:

  • api-au.cronofy.com - 🇦🇺 Australia
  • api-ca.cronofy.com - 🇨🇦 Canada
  • api-de.cronofy.com - 🇩🇪 Germany
  • api-sg.cronofy.com - 🇸🇬 Singapore
  • api-uk.cronofy.com - 🇬🇧 United Kingdom
  • api.cronofy.com - 🇺🇸 United States

Find out more about Cronofy's data centers.

scheduling_key optional  #

Required when including a join_time.

The scheduling_key identifies the Meeting Agent for rescheduling or cancelling a previously-scheduled Meeting Agent.

Providing the same scheduling_key as a previous call to this API enables you to update the join_url, join_time, and subscriptions of an already scheduled Meeting Agent.

If the previously-scheduled Meeting Agent has already begun joining the meeting, then it will remain active, and a new Meeting Agent will be scheduled.

If no scheduling key is provided a new Meeting Agent is created each time and cannot be rescheduled.

join_time optional  #

Required when including a scheduling_key.

The date and time at which the Meeting Agent should join the meeting, provided as a Time string.

It must represent a future point in time.

The Meeting Agent will schedule itself to join the meeting on or slightly before the join_time.

If no join time is provided the Meeting Agent will join the meeting as soon as possible.

join_url required  #

The URL of the meeting that the Meeting Agent should attempt to join.

Must be a valid HTTPS URL for a Microsoft Teams, Google Meet, or Zoom meeting.

subscriptions optional  #

Object containing an array of subscriptions.

subscriptions[].type optional  #

Only one value of webhook is supported.

subscriptions[].uri optional  #

The URI within your application you want Cronofy to send notifications to when the interaction is triggered. Must be an externally accessible HTTP or HTTPS URI.

subscriptions[].interactions optional  #

An array of interactions that should trigger a call to the uri.

subscriptions[].interactions[].type optional  #

The type of interaction. Currently supported are:

  • meeting_agent_activated - sent when the Meeting Agent is preparing to join the meeting. This will be up to 5 minutes before the join_time.
  • meeting_agent_complete - sent when the Meeting Agent has successfully joined the meeting, captured data from it, and processed those into resources it has made available for download
  • meeting_agent_failed - sent when the Meeting Agent was unable to run successfully

Example callbacks #

meeting_agent_activated #

This notification is fired when a Meeting Agent is preparing to join the meeting.

POST /notification HTTP/1.1
Host: example.com
Content-Type: application/json; charset=utf-8
Cronofy-HMAC-SHA256: {Base64(HmacSHA256(body_bytes, CLIENT_SECRET))}

{
  "notification": {
    "type": "meeting_agent_subscription",
    "interactions": [
      {
        "type": "meeting_agent_activated"
      }
    ]
  },
  "meeting_agent": {
    "sub": "agt_692702a100ccd07000000000",
    "state": "created",
    "resources": [
      {
        "category": "cronofy",
        "type": "dashboard",
        "url": "https://..."
      }
    ]
  }
}

meeting_agent_complete #

Meeting Agent resource download for how to pull a copy of resources into your application as desired.

POST /notification HTTP/1.1
Host: example.com
Content-Type: application/json; charset=utf-8
Cronofy-HMAC-SHA256: {Base64(HmacSHA256(body_bytes, CLIENT_SECRET))}

{
  "notification": {
    "type": "meeting_agent_subscription",
    "interactions": [
      {
        "type": "meeting_agent_complete"
      }
    ]
  },
  "meeting_agent": {
    "sub": "agt_692702a100ccd07000000000",
    "state": "complete",
    "resources": [
      {
        "category": "cronofy",
        "type": "dashboard",
        "url": "https://..."
      },
      {
        "category": "transcript",
        "type": "cronofy",
        "url": "https://..."
      },
      {
        "category": "audio",
        "type": "voice",
        "url": "https://..."
      },
      {
        "category": "video",
        "type": "conference",
        "url": "https://..."
      }
    ]
  }
}

meeting_agent_failed #

POST /notification HTTP/1.1
Host: example.com
Content-Type: application/json; charset=utf-8
Cronofy-HMAC-SHA256: {Base64(HmacSHA256(body_bytes, CLIENT_SECRET))}

{
  "notification": {
    "type": "meeting_agent_subscription",
    "interactions": [
      {
        "type": "meeting_agent_failed",
        "subtype": "meeting_agent_joining_meeting_failed"
      }
    ]
  },
  "meeting_agent": {
    "sub": "agt_692702a100ccd07000000000",
    "state": "complete",
    "resources": [
      {
        "category": "cronofy",
        "type": "dashboard",
        "url": "https://..."
      }
    ]
  }
}