Templating ^ALPHA

Description #

With the introduction of Conferencing, the details of an event aren’t fully known when the initial API call is made. Cronofy generates the details of the conference and adds them to the event in the location and/or URL fields as appropriate.

Templating introduces the option to take control over the appearance of these details by marking sections of your content to be rendered when the details are available.

Templates are only evaluated in the description and location.description fields.

Available Template Variables #

• {{ cronofy.conferencing.join_url }}

The URL to join the conference, for example https://example.com/join/meeting-abc

• {{ cronofy.conferencing.invite_block }}

A multi-line block containing the full invite details of the conference. If dial-in details are available, they will appear in this block.

This varies by provider. Content generated by the provider is used where possible.

A loose example is:

You've been invited to a conference via ExampleConf!

You can join here: http://example.com/conferencing/meeting-abc

Dial in numbers are available for the following countries:
- US: +1-202-555-0169
- UK: +44 1632 960647
- DE: +49 30 419916934

Meeting passcode: 123456

This value is not accepted in the location.description field.

Example Request #

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": "We'll be discussing the next set of milestones.\n{{ cronofy.conferencing.invite_block }}",
  "location": {
    "description": "Online: {{ cronofy.conferencing.join_url }}"
  },
  "start": "2024-07-28T15:30:00Z",
  "end": "2024-07-28T17:00:00Z",
  "conferencing": {
    "profile_id": "default"
  },
  "locale": "en"
}

Example Response #

HTTP/1.1 202 Accepted

Request parameters #

description optional  #

The usual description field as described in the Create/Update Event.

This field can contain any of the mentioned templates.

location.description optional  #

The usual location.description field as described in the Create/Update Event.

This field can only make use of the {{ cronofy.conferencing.join_url }} template.

locale required  #

The locale represents the 2 character code for the language of the content. This is used to allow Cronofy to fill in a suitable message if conferencing generation fails.

Currently supported locales are:

• en English

If conferencing fails to generate, the event will be written to the calendars to ensure the time is held. Any templates will be expanded to a placeholder value. For example, the example location would be:

Online: (Link to follow)

Once the conferencing generate succeeds, this will be updated to the actual value. You can be notified of any events in this state by using conferencing subscriptions.

conferencing required  #

The content of this is the same as specifying conferencing on an event.

However, when using templating this must be provided when setting the description, even if updating an existing event. This is to allow the API to consistently apply the update.

Please note that removing conferencing from an event with a templated description will not remove any templated values from the event description. This could lead to old conferencing details persisting in the description. It is essential to update the description when removing conferencing to ensure templates are removed.

Frequently Asked Questions #

What happens if a user edits the event in their calendar?

Any user edit to a location or description containing a template will stop templates from rendering in that field. This is to guarantee we can preserve the users edits to the event.

If you are certain you want to overwrite any changes, you can use Push Notifications to watch for the user making edits to the event and trigger a call to the Update Event endpoint with your required description, including the templates again.

What happens to an event if it has been written to the users calendar and then I update the Conferencing provider?

The event will be updated in the users calendar with the templates rendered for the updated conferencing provider. However, it is worth noting that the original conference will not be cancelled with the conferencing provider.