Scheduler Workflows BETA

Scheduler Workflows allow you to integrate the Scheduler into your business workflows and applications.

Using Workflows, you can:

  • Control the recipient’s experience by redirecting them back to your application after they’ve interacted with a Scheduler link
  • Capture metadata and store it on the Request, so that you can correlate Scheduling Requests with items in your own systems
  • Configure push notifications to be sent back to your application at various stages in the scheduling flow

Capturing metadata #

Scheduler links accept query string arguments for metadata parameters. The values provided are stored against the Request when a time slot is selected, and are then passed back to your application in later callback notifications or redirects.

The following allow list of parameters is currently accepted. Each is treated as an opaque string, with a length limit of 128 characters.

  • correlation_id - This is intended to be set to a meaningful value in your system. For example a Candidate ID in an Applicant Tracking System.
  • utm_source
  • utm_medium
  • utm_campaign
  • utm_term
  • utm_content

For example, given a Scheduling Request with the URL https://app.cronofy.com/rts/FIDaAWS5, you may pass metadata by sending your recipient the following link:

https://app.cronofy.com/rts/FIDaAWS5?correlation_id=CASE-66

This also works with Public Links:

https://app.cronofy.com/pls/Q5-ZDPM8?utm_source=outreach_campaign&utm_medium=email

Receiving callback notifications #

To receive callbacks, you must set up a Cronofy Internal Developer Application within the Organizational Unit you’re creating Scheduling Requests for.

Once you’ve done this, you should configure a Universal Push Notification URL for that application. Workflows can then be configured to send callbacks to that URL.

Creating the Application #

  • Navigate to Developer, then Create New App. If you don’t see the Developer navigation item, enable Show the Developer Dashboard under your Cronofy profile page.

  • If you have multiple Organizational Units, the Application should be created within the same Organizational Unit as your Scheduling Requests are created and your Scheduler Workflows will be configured.

  • Ensure the Internal Only Application setting is checked

Configuring your Push Notification URL #

Under your application in the navigation menu, choose Notifications. On this page you can configure your Application’s Universal Push Notification URL where all Scheduler Workflow callback notifications will be sent.

Configuring a Workflow #

Scheduler Workflows can be created within your Organizational Unit on the Cronofy dashboard.

They have some essential properties:

Enabling a Workflow #

Workflows can be enabled or disabled. When a Workflow is disabled, none of its configured actions will take effect.

Matching Scheduling Rules #

Workflows are active for any Scheduling Requests made for the selected Organizational Unit Scheduling Rules. This includes both ad-hoc Requests, as well as bookings made via Public Links for those Scheduling Rules.

Steps and Actions #

A Workflow has Actions which take effect at various Steps during the Scheduling process.

The possible Steps are as follows:

  • When an initial time slot is selected via the link
  • When a Request is rescheduled by the recipient via the link
  • When a Request is declined by the recipient via the link
  • When the recipient visits a link, but there were no slots available
  • When the recipient requests more times
  • When a scheduled event starts
  • When a scheduled event ends

There are two types of Action which can be applied to these Steps

  • Redirecting the recipient
  • Callback notifications

Redirects #

Redirects are available for all of the Steps which are a direct interaction with the Scheduling Request link. That is, all of the above Steps except when the scheduled event starts or ends.

When a Redirect action is present on a Workflow, we’ll send the recipient to the desired URL at the appropriate point in time. For example, if you configure a Workflow to redirect the user when they’ve selected their initial time slot, we’ll do that immediately after they’ve confirmed their choice.

The destination URL will have query string parameters added:

  • scheduling_request_id, matching the same ID that would appear for the request in a Callback Notification Payload
  • If the Scheduling Request has Metadata from the above list present, we’ll add those parameters as query string values on to the URL you provide.

For example, when specifying a Redirect URL of:

https://example.com/handle_time_chosen

A redirect after the time is selected might look like:

https://example.com/handle_time_chosen?scheduling_request_id=srq_52b65401a5d87bb4f0bee44e&correlation_id=your-value

Callback notifications #

Callback notifications are available for all Step types. When configuring a Callback Action, you’ll have to choose an Application to deliver the notification to. We’ll send a notification to the configured Universal Push Notification URL for that Application.

Your Application should respond quickly with a 2XX successful status. If it does not, we will retry the notification periodically until it succeeds or fails 10 times consecutively.

Callback example #

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

{
  "notification": {
    "type": "scheduling_request_time_chosen"
  },
  "user": {
    "tzid": "Europe/Paris"
  },
  "scheduling_request": {
    "scheduling_request_id": "srq_d6f3f8165239d662963fc09b",
    "slot_selection": "complete",
    "primary_select_url": "https://app.cronofy.com/rts/suDzyKHW",
    "dashboard_url": "https://app.cronofy.com/scheduler/requests/d6f3f8165239d662963fc09b",
    "summary": "Driving lessons - Marty & Doc",
    "duration": { "minutes": 30 },
    "buffer": {
      "before": { "minutes": 20 },
      "after": { "minutes": 15 }
    },
    "recipient_operations": {
      "view_url": "https://app.cronofy.com/rts/suDzyKHW",
      "decline_url": "https://app.cronofy.com/rts/suDzyKHW?decline=true",
      "reschedule_url": "https://app.cronofy.com/rts/suDzyKHW?reschedule=true"
    },
    "recipients": [
      {
        "email": "marty@evenitron.com",
        "display_name": "Marty McFly",
        "slot_selector": true,
        "select_url": "https://app.cronofy.com/rts/suDzyKHW"
      }
    ],
    "collaborators": [
      { "sub": "acc_7fad963a87459cefb4010b71" }
    ],
    "collaborator_groups": [
      {
        "name": "Driving Examiners",
        "members": [
          { "sub": "acc_75623a84e774744c496051d7" },
          { "sub": "acc_51bb3cc0c34e5364ff06bb6e" },
          { "sub": "acc_c1278d31ed6c4a9dd262afa2" }
        ],
        "required": 1
      }
    ],
    "event": {
      "host": {
        "email": "ihost@evenitron.com",
        "display_name": "Ian Host",
        "sub": "acc_962bfe62001ed91c7e906242",
        "status": "accepted"
      },
      "attendees": [
        {
          "email": "marty@evenitron.com",
          "display_name": "Dr Emmet Brown",
          "status": "accepted"
        },
        {
          "email": "bob@evenitron.com",
          "display_name": "Bob Visser",
          "sub": "acc_7fad963a87459cefb4010b71",
          "status": "needs_action"
        },
        {
          "email": "alice@hiring.evenitron.com",
          "display_name": "Alice McHiring",
          "sub": "acc_75623a84e774744c496051d7",
          "status": "tentative"
        }
      ],
      "start": {
        "time": "2024-12-23T14:00:00Z",
        "tzid": "Europe/London"
      },
      "end": {
        "time": "2024-12-23T14:30:00Z",
        "tzid": "Europe/London"
      },
      "summary": "Driving lessons - Marty & Doc",
      "metadata": {
        "scheduler": {
          "correlation_id": "foobar",
          "utm_medium": "email",
          "utm_source": "automated_email_workflow",
          "utm_campaign": "candidate_interview_offer_email",
          "captured_data.phone_number": "0118999881999119725 3",
          "captured_data.notes": "No dietary requirements."
        }
      }
    }
  }
}

Notification types:

  • scheduling_request_time_chosen - When an initial time slot is selected via the link
  • scheduling_request_rescheduled - When a Request is rescheduled by the recipient via the link
  • scheduling_request_declined - When a Request is declined by the recipient via the link
  • scheduling_request_no_times_available - When the recipient visits a link, but there were no slots available
  • scheduling_request_more_times_requested - When the recipient requests more times
  • event_participant_status_changed - When an attendee or host of a scheduled event updates their participation status
  • event_start - When a scheduled event starts
  • event_end - When a scheduled event ends

The schema of scheduling_request can be found in Scheduling Request query documentation.

Note:

recipient_operations will only contain URLs for actions that are available for the Scheduling Request in its current state.

Optional schema parameters #

Some schema parameters will only only be present on certain event types.

Notifications of interactions where the invitee is interacting directly with the booking link may include a user parameter. These types are:

  • scheduling_request_time_chosen
  • scheduling_request_rescheduled
  • scheduling_request_declined
  • scheduling_request_no_times_available
  • scheduling_request_more_times_requested
Callback example
POST {CALLBACK_URL_PATH} HTTP/1.1
Host: {CALLBACK_URL_HOST}
Content-Type: application/json; charset=utf-8
Cronofy-HMAC-SHA256: {Base64(HmacSHA256(body_bytes, CLIENT_SECRET))}

{
  "notification": {
    "type": "scheduling_request_time_chosen"
  },
  "user": { // Optional user parameter
    "tzid": "Europe/Paris"
  },
  "scheduling_request": {
    ...omitted for length
  }
}

Some notification types can include extra contextual information under a notification_context parameter. These types are:

  • event_participant_status_changed
Callback example
POST {CALLBACK_URL_PATH} HTTP/1.1
Host: {CALLBACK_URL_HOST}
Content-Type: application/json; charset=utf-8
Cronofy-HMAC-SHA256: {Base64(HmacSHA256(body_bytes, CLIENT_SECRET))}

{
  "notification": {
    "type": "event_participant_status_changed"
  },
  "notification_context": { // Optional notification_context parameter
      "changed_participants": [
          {
              "email": "bob@evenitron.com"
          }
      ]
  },
  "scheduling_request": {
    "scheduling_request_id": "srq_52b65401a5d87bb4f0bee44e",
    "recipients": [
      {
        "email": "marty@evenitron.com",
        "display_name": "Marty McFly",
        "slot_selector": true,
        "select_url": "https://app.cronofy.com/rts/VFbnUVCv"
      }
    ],
    "event": {
      "summary": "Driving test - Marty & Doc",
      "attendees": [
        {
          "email": "marty@evenitron.com",
          "display_name": "Dr Emmet Brown",
          "status": "accepted"
        },
        {
          "email": "bob@evenitron.com",
          "display_name": "Bob Visser",
          "sub": "acc_7fad963a87459cefb4010b71",
          "status": "declined"
        },
      ],
    }
  },
}

Event-based notifications #

You can configure a callback tied to the start or end time of the scheduled event. This fires when the event in your calendar actually takes place, and is kept in sync with any external changes that might occur.

For example, if the recipient originally chooses 11AM, but then the event is moved in the organizer’s calendar afterwards to 2PM, we’ll send a notification at the new time of 2PM.

We’ll send such notifications within a delivery window of one minute either side of the scheduled time.

Response Parameters #

notification required  #

An Object containing the type of the notification.

notification.type required  #

A String representing the type of notification sent.

user optional  #

An Object containing information about the user that booked the request.

user.tzid optional  #

A String representing the timezone of the invitee that booked the request. This is provided on a best effort basis, and may have been auto detected based on the invitee’s browser configuration if they did not explicitly choose a timezone.

scheduling_request required  #

An Object containing the details of a scheduling request. For more detail on the Scheduling Request schema, please see our Scheduling Request API documentation

notification_context optional  #

An Object which may be present to provide more context on the notifiable interaction.

notification_context.changed_participants optional  #

Present only for event_participant_status_changed events.

An Array containing participant Objects. The participant object contains an email property. This list identifies the participants which have had a change in status. Their up-to-date status can be fetched from the scheduling_request.event.

This may include the event.host as well as invitees present within event.attendees. If an invitee is added or removed from the event, then this is also seen as a change in status and they will be listed here.