Read Conversation ^ALPHA

Description #

Retrieve the current state of a scheduling conversation.

URL Format #

{data_center_url}/v1/scheduling_conversations/{scheduling_conversation_id}

Example Request #

GET /v1/scheduling_conversations/{scheduling_conversation_id} HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "scheduling_conversation_id": "scv_5b45cfabef723e0913f3323f",
  "participants": [
    {
      "participant_id": "@grace",
      "sub": "acc_5ba21743f408617d1269ea1e",
      "email": "grace@company.com",
      "common_name": "Grace Devlin",
      "slots": {
        "selection_method": "auto"
      },
      "status": "waiting",
      "possible_actions": {},
    },
    {
      "participant_id": "@karl",
      "common_name": "Karl Cramer",
      "slot_choice": {
        "method": "manual"
      },
      "status": "needs_action",
      "possible_actions": {
        "slots_list": {
          "url": "https://api.cronofy.com/v1/sche..."
        },
        "slots_select": {
          "url": "https://api.cronofy.com/v1/sche..."
        }
      }
    }
  ],
  "tzid": "America/Chicago",
  "required_duration": {
    "minutes": 60
  },
  "available_periods": [
    {
      "start": "2024-12-23T09:00:00Z",
      "end": "2024-12-23T18:00:00Z"
    }
  ],
  "status": "in_progress"
}

Request parameters #

scheduling_conversation_id required  #

The Cronofy assigned ID for the SchedulingConversation.

Response parameters #

scheduling_conversation_id  #

The Cronofy assigned ID for the SchedulingConversation.

participants  #

An array of the groups of participants who will participate in this scheduling conversation.

Identification of participants is through one of three properties in the following order of importance: participant_id, sub then email. At least one of these must be supplied.

Currently, the maximum number of participants is two.

participants.participant_id  #

The String that uniquely identifies the participant in the calling application.

Usually this will be your own internal ID for the participant, eg @grace, encoded as a String.

participants.sub  #

The internal Cronofy ID for the account, as an ASCII-only String.

This can be retrieved by calling the UserInfo endpoint with a valid access_token

participants.email  #

An email address for the participant. This will be used to identify a scheduling conversation service the participant has enabled to progress the conversation, and/or progress the conversation via email.

participants.common_name  #

Friendly name for the participant

participants.slots.selection_method  #

auto or manual.

This indicates whether the participant should be prompted to chose a slot or (manual) or use their availability to automatically find a time (auto).

participants.slots.selected  #

An array of the slots selected by the participant

participants.status  #

Current status of a participant. Options include:

• waiting - waiting on other participants in the conversation.
• needs_action - participant needs to perform one of the possible actions.
• complete - the participant has completed the conversation.

participants.possible_actions  #

Object comprising the possible actions available to the participant based in the current state of the Scheduling Conversation.

Current possible actions are:

• slots_list
• slots_select

This list will be extended

participants.possible_actions.slots_list.url  #

The participant specific url for listing slots.

participants.possible_actions.slots_select.url  #

The participant specific url for selecting slots.

tzid  #

Specifies the master timezone for the conversation. A String representing a known time zone identifier from the IANA Time Zone Database.

This will be used as the default timezone for any events created in participant’s calendars.

required_duration  #

A Duration describing the minimum period that the participant groups must be satisfied for a period to be deemed as available.

Must be greater than zero minutes in length.

available_periods  #

An array of 1 to 50 available periods, across up to 35 days of the period of synchronized events, within which suitable matches may be found.

available_periods.start  #

Thestart of an available period as a Time.

It must represent a future point in time.

available_periods.end  #

Theend of an available period as a Time.

Must be at least 1 minute after the corresponding start and within 35 days of the earliest start.

status  #

Current status of the scheduling conversation. Options are:

• in_progress
• complete