Create or Update Event
Required plan: StarterDescription #
Requests conferencing details are added to an event. When creating or updating an event, add the conferencing
property as specified below. When the conferencing
property is not specified, we will not make changes to the event’s conferencing. Changes to the events summary, start time or end time will be reflected on the conference.
Please note: Conferencing services cannot be added to past events.
Example Requests #
POST /v1/calendars/cal_n23kjnwrw2_jsdfjksn234/events HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8
{
"event_id": "qTtZdczOccgaPncGJaCiLg",
"summary": "Board meeting",
"description": "Discuss plans for the next quarter.",
"start": "2023-10-02T15:30:00Z",
"end": "2023-10-02T17:00:00Z",
"conferencing": {
"profile_id": "default"
}
}
POST /v1/calendars/cal_n23kjnwrw2_jsdfjksn234/events HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8
{
"event_id": "qTtZdczOccgaPncGJaCiLg",
"summary": "Board meeting",
"description": "Discuss plans for the next quarter.",
"start": "2023-10-02T15:30:00Z",
"end": "2023-10-02T17:00:00Z",
"conferencing": {
"profile_id": "explicit",
"provider_description": "Custom conferencing",
"join_url": "https://conferencing.example.com/join/xyz"
}
}
Parameters #
data_center_url required
The URL for the data center you want to communicate with. Possible choices are:
api-au.cronofy.com
- π¦πΊ Australiaapi-ca.cronofy.com
- π¨π¦ Canadaapi-de.cronofy.com
- π©πͺ Germanyapi-sg.cronofy.com
- πΈπ¬ Singaporeapi-uk.cronofy.com
- π¬π§ United Kingdomapi.cronofy.com
- πΊπΈ United States
Find out more about Cronofy's data centers.
conferencing optional #
Object describing the desired conferencing details.
conferencing.profile_id required #
When provided defines the conferencing profile to use when provisioning the conference details.
This should equal one of the built-in values, or, to explicitly select a conferencing profile, a profile_id
taken from the
account’s Conferencing Profiles.
Built-in values
default
is a special value to ease integration. This has the following preference:- The default conferencing profile out of those authorized by the user. This will be the first conferencing profile that they have authorized unless the user has explicitly chosen a default.
- The integrated conferencing provider for the destination calendar, if available. (e.g. Meet for Google calendars or Teams for Microsoft 365 calendars)
- Anonymous, browser based video link.
none
explicitly removes conferencing from an event.explicit
is a special value which allows you to manually specify the conferencing join details. When usingexplicit
, you must also specify theconferencing.provider_description
andconferencing.join_url
parameters.integrated
is a special value which requests the integrated conferencing service for the destination calendar be used. Both Google Meet and Microsoft Teams are supported. Discover whether this is available by checking thecalendar_integrated_conferencing_available
value on the List Calendars API. If you wish to disable integrated conferencing for Google, this can be done via Google Workspace settings. For disabling MS Teams, please see our FAQ page.8x8
is a special value which allows 8x8 to be chosen explicitly.
conferencing.provider_description #
Required, and only used, when using the explicit
special conferencing.profile_id
.
Use this to specify the user-facing name of the conferencing provider. This displays in calendars that have native support for conferencing, for example on the Google Calendar conferencing join button.
conferencing.join_url #
Required, and only used, when using the explicit
special conferencing.profile_id
.
Use this to specify the URL to join the conference. This must be an HTTP/HTTPS URI.
Example Event With Conferencing Assigned #
{
"event_id": "qTtZdczOccgaPncGJaCiLg",
"summary": "Board meeting",
"description": "Discuss plans for the next quarter.",
"start": "2020-04-11T15:30:00Z",
"end": "2020-04-11T17:00:00Z",
"conferencing": {
"provider_name": "zoom",
"join_url": "https://zoom.us/00001111-222"
}
}
Conferencing details are added asynchronously. Your application can subscribe to a push notification when this is assigned. See Conferencing Services Push Notification documentation for more information.
Prior to conference generation
The event’s conferencing
value will be set to { "pending": true }
.
For explicit
conferencing, the pending status will still appear but it can be ignored as this only is relevant for conferencing values that will be generated by Cronofy.
After successful conference generation
The conferencing
value is set to an object containing details of the conference:
join_url
- the URL which can be used to join the conference.provider_name
- a value representing the service used. For conferencingprofile_id
values which rely on some resolution, such asdefault
, this will represent the service the value resolved to.
Possible provider_name
values include:
8x8
go_to
google_meet
when resolved from theintegrated
option against a Google calendarindeed
ms_teams
ms_teams_for_business
when resolved from theintegrated
option against a Microsoft calendarzoom
This value can also be null
when explicit
conferencing is defined.
The list should not be treated as exhaustive, as new services will be added over time.
Error Responses #
422 Unprocessable #
Requesting integrated
conferencing on a calendar which does not support it will result in the following error response.
This might be because the target calendar is not a Google calendar, or because Google Meet has been administratively disabled on that account in the case of a Google Workspace domain.
{
"errors": {
"conferencing.profile_id": [
{
"key": "errors.integrated_conferencing_not_available",
"description": "Integrated conferencing is not available on this calendar"
}
]
}
}