Smart Invites are trackable calendar invite files that keep your application up to date with attendee status changes. Your application can be notified when an attendee accepts the event, declines it or deletes 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: api.cronofy.com
Authentication: 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": "2017-10-05T09:30:00Z",
    "end": "2017-10-05T10:00: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. You can find this on the Settings tab. If you don't have an Application registered with Cronofy yet, you can easily create one by clicking on the "Create New Application" button on the left hand side of the dashboard.

recipient

This contains the email address of the attendee. 

smart_invite_id

Your unique identifier for this smart invite. Normally this will relate to an appointment, interview, etc record in your application. You can use the same smart_invite_id for different attendees when you want multiple people to to attend the same event.

event

This contains all of the fields for the event. Almost identical to the event object you will use in our read and upsert event APIs.

callback_url

The url for Cronofy to POST  updates to whenever the attendee status changes. More on this below.


The response contains the contents of your original post along with icalendar attachment you would add to the email to the recipient.

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

Sending the Smart Invite

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 < ApplicationMailer
  def invite(smart_invite)
    event_ics = smart_invite.attachments.icalendar

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

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

    mail(
      to: smart_invite.recipient.email,
      subject: smart_invite.summary
    )
  end
end

You'll note that the invite is added twice. Once inline as text/calendar with 7bit encoding 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. 

Tracking Attendee Status

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

GET /v1/smart_invites?recipient_email=cronofy@example.com&smart_invite_id=your-unique-identifier-for-invite
HTTP/1.1
Host: api.cronofy.comAuthentication:
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://example.yourapp.com/..."
  }
}


This is a quick introduction to Smart Invites. If you have any further questions don't hesitate to get in touch. 

Did this answer your question?