Smart Invites

Smart Invites are trackable calendar invite files that keep your application up to date with attendee status changes without needing a connection to their calendar. Your application can be notified when an attendee accepts the event or declines it from their calendar.

Healthcare appointments or interviews can then be rescheduled. A rental property viewing or restaurant booking can be auto cancelled and the slot made available to others.

Importantly the workflow decisions are yours but Cronofy gives you the real-time notification you need to trigger the appropriate process at the appropriate time.

If you’re already sending invite files from your application then this is a really simple operation to swap out your existing ICS generation with Cronofy Smart Invites.

Creating your first Smart Invite #

A single API call is all that’s needed to generate the invite you can allow the user to download or send via email.

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

{
  "recipient": {
    "email": "cronofy@example.com"
  },
  "smart_invite_id": "your-unique-identifier-for-invite",
  "event": {
    "summary": "Board meeting",
    "description": "Discuss plans for the next quarter.",
    "start": "2024-07-28T09:30:00Z",
    "end": "2024-07-28T10:30:00Z",
    "tzid": "Europe/London",
    "location": {
      "description": "Board room"
    }
  },
  "callback_url": "https://yourapp.com/smart_invite/notifications"
}

The key attributes from the above sample request are as follows,

API_KEY  #

This is the client_secret for your Application in the Cronofy Developer Dashboard.

recipient  #

This contains the email address of the attendee.

smart_invite_id  #

Your unique identifier for the Smart Invite.

event  #

This contains all the fields for the event.

callback_url  #

The url for Cronofy to ‘POST’ updates to whenever the attendee status changes.

Further details on these parameters can be found here.

{
  "event": {...},
  "attachments": { "icalendar": "BEGIN:VCALENDAR\nVERSION:2.0..." }
}

Sending the Smart Invite #

Cronofy does not send the email.

Different languages and frameworks vary but the process requires creating two attachments on the email message. A Rails Mailer example is given here:

class SmartInviteMailer < ActionMailer::Base
  def invite(smart_invite) event_ics = smart_invite.attachments.icalendar

    method = 'REQUEST' # method=CANCEL in the case of cancellations

    attachments.inline["invite.ics"] = {
      content_type: "text/calendar; charset=UTF-8; method=#{method}",
      encoding: '7bit',
      content: event_ics,
    }

    attachments["invite.ics"] = {
      content_type: "application/ics; charset=UTF-8; method=#{method}",
      encoding: 'base64',
      content: Base64.encode64(event_ics),
    }

    mail(
      to: smart_invite.recipient.email,
      subject: "Smart Invite Example",
      body: "Here is your invite."
    )
  end
end

You’ll note that the invite is added twice. Once inline as text/calendar with 7bitencoding and once as application/ics with base64 encoding.

Doing this is standards guidance for best practice and ensures the widest compatibility with calendar servers and clients.

Examples for different languages in Sending Smart Invites

Tracking Attendee Status #

You can request the current status of a Smart Invite by querying the /v1/smart_invites API endpoint.

GET /v1/smart_invites?recipient_email=cronofy@example.com&smart_invite_id=your-unique-identifier-for-invite HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}

You’ll receive back the entire information about that invitation including the following attributes.

{
  "recipient": {
    "email": "cronofy@example.com",
    "status": "pending"
  },
  "replies": [
    {
      "email": "person1@example.com",
      "status": "accepted"
    },
    {
      "email": "person2@example.com",
      "status": "declined"
    }
  ],
}

recipient  #

This is the same as the submission with the addition of a status attribute indicating whether the recipient has accepted or not.

replies  #

Is a list of all replies to the invite. This will usually be the same as the recipient but it’s presented as a separate attribute because it is possible for other people to reply to the calendar invite. This can be when email aliases are used or when the recipient is a team mailbox that is shared by multiple people.

You can then see at any time, who’s accepted, who’s declined and make sure your application and thus your user is fully informed.

Status Update Callbacks #

The last concept to cover is the callback. Whenever a reply is received, Cronofy will generate a push notification to the callback_url you specified when creating the event. The body will be similar to this:

{
  "notification": {
    "type": "smart_invite"
  },
  "smart_invite": {
    "recipient": {
      "email": "cronofy@example.com",
      "status": "accepted"
    },
    "smart_invite_id": "your-unique-identifier-for-invite",
    "callback_url": "https://yourapp.example.com/..."
  }
}

This is a quick introduction to Smart Invites. If you have any further questions please send us an email at support@cronofy.com or go to this page for a more detailed look at creating and updating smart invites.