Only show these results:

Add conferencing to events

📝 This page discusses both Nylas v2.x and v3. For more information about the newest version, see the Nylas v3 documentation.

While online calendar events can reflect in-person meetings, they are often used to schedule virtual and phone conferencing meetings. The Nylas Calendar API includes both the ability to read conferencing details from an event, and create conferences automatically when you create events.

A new Google Calendar event. Its subject is "Let's Celebrate", and a Zoom link is in the Conferencing section.

Nylas can natively read conferencing information, and you can manually write conferencing details into an event when you create it. You can also use a provider connector to automatically create and attach conference info when you create an event.

🔍 Both Nylas v2 and v3 support manually-added conferencing information. Nylas v2 does not support automatic conference creation, but v3 supports automatic conference creation with Google Meet and Microsoft Teams. Autocreate with additional conferencing providers is coming soon in v3.

The Conferencing object

The Event object contains conference details in the conferencing sub-object, as in the JSON example below.

"conferencing": {
"provider": "Google Meet",
"details": {
"url": "meet.google.com/***-****-***",
"pin": "xyz",
"phone": [
"+1 234 555 6789",
"+1 456 555 7890"
]
}
}

Each conferencing service provider structures the details differently, so the content of the conferencing object varies. See the Create Event schema (API v3 and API v2) for per-provider details.

Read conferencing details

Nylas automatically reads conferencing details on an event, when they're available. (Remember, not all events will have an associated conference!) Regardless of how they are formatted on the provider's Event, Nylas parses them into the conferencing object for easier reading.

Nylas v3 can currently read conferencing details from the following providers:

  • Microsoft Teams
  • Google Meet
  • Zoom
  • WebEx
  • GoToMeeting

Nylas v2 can read and write conferencing details from Google, GCal, and GSuite, and read only from Microsoft Exchange.

Manually add conferencing to an event

You can manually add conferencing to a meeting you create by adding the conferencing object with the required details. This is usually just the provider and URL.

This option requires no additional set up from you, and can be the most flexible if you work with many different conferencing providers. When you manually create conferencing details you must first create the conference on the provider, then copy the required details to the Event object before you make the Create Event API request. Nylas does not create the conference instance for you when you manually add the details.

⚠️ If you manually add conferencing details to an event, Nylas validates only that the required fields are included and that they contain a value in the expected format. Nylas cannot validate that the details are valid conference lines or URLs.

Enable autocreate for conferencing in v3

If you want your provider to automatically create conferences for you when you create an event, you can specify autocreate in the provider field instead of passing the details object.

Nylas v3 currently supports conferencing with Google Meet and Microsoft Teams, and reuses the Google and Microsoft Graph provider auth connectors you might already have for your application.

To automatically create conferences, you can add the conferencing object to new events and include the autocreate sub-object, as in the JSON snippet below.

"conferencing": {
"provider": "Google Meet",
"autocreate": {}
}

You must still pass the provider, but instead of the details object, you pass autocreate. The autocreate object is an optional dictionary of additional parameters that you can use to customize the conference. Because these are provider-specific, Nylas does not validate any additional parameters that you pass in this object.

Manually create an event with conferencing

To create an event with conferencing for Google, add the conferencing object to your POST /events request. The examples below use Google Meet as the conferencing platform.

You can create events that contain metadata. The response from the Nylas API includes the conferencing details object. The conferencing information can vary by provider. Review the Events reference documentation for examples and more information.

curl --request POST \
--url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<NYLAS_CALENDAR_ID> \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY_OR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"title": "Annual Philosophy Club Meeting",
"status": "confirmed",
"busy": true,
"participants": [
{
"name": "Aristotle",
"email": "[email protected]"
},
{
"name": "Jane Stephens",
"email": "[email protected]"
}
],
"description": "Come ready to talk philosophy!",
"when": {
"time": 1700060400
},
"location": "New York Public Library, Cave room",
"recurrence": [
"RRULE:FREQ=WEEKLY;BYDAY=MO",
"EXDATE:20211011T000000Z"
],
}'
curl --location --request POST 'https://api.nylas.com/events' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"title": "Birthday Party",
"location": "Roller Rink",
"calendar_id": "9ev16mzqlwux5vrxai6s2t4uf",
"status": "confirmed",
"busy": true,
"read_only": false,
"participants": [
{
"name": "Dorothy Vaughan",
"email": "[email protected]"
},
{
"name": "Katherine Johnson",
"email": "[email protected]"
},
{
"name": "Hedy Lamarr",
"email": "[email protected]"
}
],
"description": "Lets celebrate",
"when": {
"start_time": "1608241500",
"end_time": "1608245100"
},
"conferencing": {
"provider": "Google Meet",
"details": {
"phone": [
"+11234567890"
]
"pin": "1234"
"url": "meet.google.com/*************"
}
}
}'
{
"account_id": "5tgncdmczat02216u7d6uypyi",
"busy": true,
"calendar_id": "9ev16mzqlwux5vrxai6s2t4uf",
"conferencing": {
"details": {
"phone": [
"+11234567890"
],
"pin": "1234",
"url": "meet.google.com/*************"
},
"provider": "Google Meet"
},
"description": "Let's celebrate",
"ical_uid": null,
"id": "b54acjszoyhsxljnfr3lnhm2y",
"job_status_id": "73p1s2umn46ym77krav0qm8cx",
"location": "Roller Rink",
"message_id": null,
"object": "event",
"owner": "Jane Doe <[email protected]>",
"participants": [
{
"comment": null,
"name": "Hedy Lamarr",
"email": "[email protected]",
"status": "noreply"
}
],
"read_only": false,
"status": "confirmed",
"title": "Birthday Party",
"when": {
"end_time": 1608245100,
"object": "timespan",
"start_time": 1608241500
}
}

Get event conference data

When available, Nylas fetches conference data from the conferenceData field on Google Calendar or from location/description on Microsoft Graph, and parses it into the conferencing object in Nylas.

Get event conference data in v3

To view the conferencing object in v3, make either a GET /v3/grants/grant_id/events or GET /v3/grants/grant_id/events/event_id request.

The following examples show a v3 Get Event request, and a response from Nylas with the conference details included.

curl --request GET \
--url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<NYLAS_CALENDAR_ID>&start=<EPOCH_TIMESTAMP>&end=<EPOCH_TIMESTAMP> \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <NYLAS_API_KEY_OR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json'
{
"request_id": "cbd60372-df33-41d3-b203-169ad5e3AAAA",
"data": [
{
"busy": true,
"calendar_id": "primary",
"conferencing": {
"details": {
"meeting_code": "ist-****-tcz",
"url": "https://meet.google.com/ist-****-tcz"
},
"provider": "Google Meet"
},
"created_at": 1701974804,
"creator": {
"email": "[email protected]",
"name": ""
},
"description": null,
"grant_id": "1e3288f6-124e-405d-a13a-635a2ee54eb2",
"hide_participants": false,
"html_link": "https://www.google.com/calendar/event?eid=NmE0dXIwabQAAAA",
"ical_uid": "[email protected]",
"id": "6aaaaaaame8kpgcid6hvd",
"object": "event",
"organizer": {
"email": "[email protected]",
"name": ""
},
"participants": [
{
"email": "[email protected]",
"status": "yes"
},
{
"email": "[email protected]",
"status": "yes"
}
],
"read_only": true,
"reminders": {
"overrides": null,
"use_default": true
},
"status": "confirmed",
"title": "Holiday check in",
"updated_at": 1701974915,
"when": {
"end_time": 1701978300,
"end_timezone": "America/Los_Angeles",
"object": "timespan",
"start_time": 1701977400,
"start_timezone": "America/Los_Angeles"
}
}
]
}

Get event conference data in v2

To view the conferencing object in v2, make either a GET /events or GET /events/{id} request.

The examples below show a v2 Get Events request, and the responses Nylas sends when the event includes parseable conference details, and when it doesn't. In many cases, the information is still available as part of the event's location (its URL) and description (the additional conference details).

curl --location --request GET 'https://api.nylas.com/events' \
--header 'Authorization: Bearer <access_token>' \
[{
"account_id": "5tgncdmczat02216u7d6uypyi",
"busy": true,
"calendar_id": "cdv2pa13ogzd7x1fgb6bk0uy0",
"conferencing": {
"details": {
"meeting_code": "123 456 7890",
"phone": [
"+12345678901",
"+12532158782"
],
"url": "https://us02web.zoom.us/j/5668774452"
},
"provider": "Zoom Meeting"
},
"description": "\n──────────\nAda Lovelace is inviting you to a scheduled Zoom meeting.\n\nJoin Zoom Meeting\nhttps://us02web.zoom.us/j/**********\n\nMeeting ID: 123 456 7890\nOne tap mobile\n+1234567890,,**********# US (San Jose)\n+1234567890,,**********# US (Tacoma)\n\nDial by your location\n +1 123 456 7890 US (San Jose)\n +1 123 456 7890 US (Tacoma)\n +1 123 456 7890 US (Houston)\n +1 123 456 7890 US (Germantown)\n +1 123 456 7890US (Chicago)\n +1 123 456 7890 US (New York)\nMeeting ID: 123 456 7890\nFind your local number: https://us02web.zoom.us/u/*******\n\n\n──────────\n\n-::~:~::~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~::~:~::-\nPlease do not edit this section of the description.\n\nView your event at https://calendar.google.com/calendar/event?action=VIEW&eid=********&tok=******&ctz=America%2FChicago&hl=en&es=1.\n-::~:~::~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~::~:~::-",
"ical_uid": "***********@google.com",
"id": "4wa541hgeph6vje9mzzf5wrru",
"location": "https://us02web.zoom.us/j/**********",
"message_id": "3etfeskt26j5oqdt5w1ordafz",
"object": "event",
"owner": "Ada Lovelace <[email protected]>",
"participants": [
{
"comment": null,
"email": "[email protected]",
"name": "[email protected]",
"status": "noreply"
},
{
"comment": null,
"email": "[email protected]",
"name": "[email protected]",
"status": "yes"
}
],
"read_only": true,
"recurrence": {
"rrule": [
"RRULE:FREQ=WEEKLY;BYDAY=WE"
],
"timezone": "America/Los_Angeles"
},
"status": "confirmed",
"title": "Weekly 1:1",
"when": {
"end_time": 1608150600,
"object": "timespan",
"start_time": 1608148800
}
}]
[{
"account_id": "5tgncdmczat02216u7d6uypyi",
"busy": true,
"calendar_id": "cdv2pa13ogzd7x1fgb6bk0uy0",
"description": "\n──────────\nAda Lovelace is inviting you to a scheduled Zoom meeting.\n\nJoin Zoom Meeting\nhttps://us02web.zoom.us/j/**********\n\nMeeting ID: 123 456 7890\nOne tap mobile\n+1234567890,,**********# US (San Jose)\n+1234567890,,**********# US (Tacoma)\n\nDial by your location\n +1 123 456 7890 US (San Jose)\n +1 123 456 7890 US (Tacoma)\n +1 123 456 7890 US (Houston)\n +1 123 456 7890 US (Germantown)\n +1 123 456 7890US (Chicago)\n +1 123 456 7890 US (New York)\nMeeting ID: 123 456 7890\nFind your local number: https://us02web.zoom.us/u/*******\n\n\n──────────\n\n-::~:~::~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~::~:~::-\nPlease do not edit this section of the description.\n\nView your event at https://calendar.google.com/calendar/event?action=VIEW&eid=********&tok=******&ctz=America%2FChicago&hl=en&es=1.\n-::~:~::~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~:~::~:~::-",
"ical_uid": "***********@google.com",
"id": "4wa541hgeph6vje9mzzf5wrru",
"location": "https://us02web.zoom.us/j/**********",
"message_id": "3etfeskt26j5oqdt5w1ordafz",
"object": "event",
"owner": "Ada Lovelace <[email protected]>",
"participants": [
{
"comment": null,
"email": "[email protected]",
"name": "[email protected]",
"status": "noreply"
},
{
"comment": null,
"email": "[email protected]",
"name": "[email protected]",
"status": "yes"
}
],
"read_only": true,
"recurrence": {
"rrule": [
"RRULE:FREQ=WEEKLY;BYDAY=WE"
],
"timezone": "America/Los_Angeles"
},
"status": "confirmed",
"title": "Weekly 1:1",
"when": {
"end_time": 1608150600,
"object": "timespan",
"start_time": 1608148800
}
}]

Conferencing limitations in v3

The following limitations apply to conferencing in Nylas v3:

  • Nylas can read, but cannot create, Zoom, WebEx, and GoToMeeting conference details.
  • v3 does not support autocreate for cross-platform conferencing. This means that if you create an event for Google Calendar, you cannot autocreate a Microsoft Teams conference for that event. If you need to create a cross-platform conference, you can manually add the details instead.

Conferencing limitations in v2

The following limitations apply to conferencing in Nylas v2.x:

  • Nylas can read, but cannot create conferencing details for Zoom, WebEx, and GoToMeeting conference details.
  • When fetching events, Nylas might not return the conferencing object. Nylas attempts to get the conferencing details when they're available.
  • You can edit conference details for Google only.

Further reading