# Timeline

<br />

For a list of [methods](https://developers.google.com/glass/v1/reference/timeline#methods) for this resource, see the end of this page.

## Resource representations

Each item in the user's timeline is represented as a `TimelineItem` JSON structure, described below.

```
{
  "kind": "mirror#timelineItem",
  "id": string,
  "sourceItemId": string,
  "canonicalUrl": string,
  "bundleId": string,
  "isBundleCover": boolean,
  "selfLink": string,
  "created": datetime,
  "updated": datetime,
  "displayTime": datetime,
  "isPinned": boolean,
  "pinScore": integer,
  "isDeleted": boolean,
  "etag": etag,
  "creator": contacts Resource,
  "recipients": [
    contacts Resource
  ],
  "inReplyTo": string,
  "title": string,
  "text": string,
  "html": string,
  "speakableType": string,
  "speakableText": string,
  "attachments": [
    timeline.attachments Resource
  ],
  "location": locations Resource,
  "menuItems": [
    {
      "id": string,
      "action": string,
      "values": [
        {
          "state": string,
          "displayName": string,
          "iconUrl": string
        }
      ],
      "removeWhenSelected": boolean,
      "payload": string
    }
  ],
  "notification": {
    "level": string,
    "deliveryTime": datetime
  }
}
```

| Property name | Value | Description | Notes |
|---|---|---|---|
| `attachments[]` | `list` | A list of media attachments associated with this item. As a convenience, you can refer to attachments in your HTML payloads with the attachment or cid scheme. For example: - attachment: `<img src="attachment:attachment_index">` where attachment_index is the 0-based index of this array. - cid: `<img src="cid:attachment_id">` where attachment_id is the [ID](https://developers.google.com/glass/v1/reference/timeline#attachments.id) of the attachment. |   |
| `bundleId` | `string` | The bundle ID for this item. Services can specify a bundleId to group many items together. They appear under a single top-level item on the device. | writable |
| `canonicalUrl` | `string` | A canonical URL pointing to the canonical/high quality version of the data represented by the timeline item. | writable |
| `created` | `datetime` | The time at which this item was created, formatted according to RFC 3339. |   |
| `creator` | `nested object` | The user or group that created this item. | writable |
| `displayTime` | `datetime` | The time that should be displayed when this item is viewed in the timeline, formatted according to RFC 3339. This user's timeline is sorted chronologically on display time, so this will also determine where the item is displayed in the timeline. If not set by the service, the display time defaults to the `updated` time. | writable |
| `etag` | `etag` | ETag for this item. |   |
| `html` | `string` | HTML content for this item. If both `text` and `html` are provided for an item, the `html` will be rendered in the timeline. **Allowed HTML elements** - You can use these elements in your timeline cards. - Headers: `h1, h2, h3, h4, h5, h6` - Images: `img` - Lists: `li, ol, ul` - HTML5 semantics: `article, aside, details, figure, figcaption, footer, header, nav, section, summary, time` - Structural: `blockquote, br, div, hr, p, span` - Style: `b, big, center, em, i, u, s, small, strike, strong, style, sub, sup` - Tables: `table, tbody, td, tfoot, th, thead, tr` **Blocked HTML elements**: These elements and their contents are removed from HTML payloads. - Document headers: `head, title` - Embeds: `audio, embed, object, source, video` - Frames: `frame, frameset` - Scripting: `applet, script` **Other elements**: Any elements that aren't listed are removed, but their contents are preserved. | writable |
| `id` | `string` | The ID of the timeline item. This is unique within a user's timeline. |   |
| `inReplyTo` | `string` | If this item was generated as a reply to another item, this field will be set to the ID of the item being replied to. This can be used to attach a reply to the appropriate conversation or post. |   |
| `isBundleCover` | `boolean` | Whether this item is a bundle cover. If an item is marked as a bundle cover, it will be the entry point to the bundle of items that have the same `bundleId` as that item. It will be shown only on the main timeline --- **not within the opened bundle** . On the main timeline, items that are shown are: - Items that have `isBundleCover` set to `true` - Items that do not have a `bundleId` In a bundle sub-timeline, items that are shown are: <!-- --> - Items that have the `bundleId` in question **AND** `isBundleCover` set to `false` | writable |
| `isDeleted` | `boolean` | When true, indicates this item is deleted, and only the ID property is set. |   |
| `isPinned` | `boolean` | When true, indicates this item is pinned, which means it's grouped alongside "active" items like navigation and hangouts, on the opposite side of the home screen from historical (non-pinned) timeline items. You can allow the user to toggle the value of this property with the `TOGGLE_PINNED` built-in menu item. |   |
| `kind` | `string` | The type of resource. This is always `mirror#timelineItem`. |   |
| `location` | `nested object` | The geographic location associated with this item. | writable |
| `menuItems[]` | `list` | A list of menu items that will be presented to the user when this item is selected in the timeline. | writable |
| `menuItems[].action` | `string` | Controls the behavior when the user picks the menu option. Allowed values are: - `CUSTOM` - Custom action set by the service. When the user selects this `menuItem`, the API triggers a notification to your [`callbackUrl`](https://developers.google.com/glass/subscriptions) with the [`userActions.type`](https://developers.google.com/glass/reference/subscriptions#notification.userActions.type) set to `CUSTOM` and the [`userActions.payload`](https://developers.google.com/glass/reference/subscriptions#notification.userActions.payload) set to the `ID` of this menu item. This is the default value. - Built-in actions: - `REPLY` - Initiate a reply to the timeline item using the voice recording UI. The `creator` attribute must be set in the timeline item for this menu to be available. - `REPLY_ALL` - Same behavior as `REPLY`. The original timeline item's `recipients` will be added to the reply item. - `DELETE` - Delete the timeline item. - `SHARE` - Share the timeline item with the available contacts. - `READ_ALOUD` - Read the timeline item's `speakableText` aloud; if this field is not set, read the `text` field; if none of those fields are set, this menu item is ignored. - `GET_MEDIA_INPUT` - Allow users to provide media payloads to Glassware from a menu item (currently, only transcribed text from voice input is supported). Subscribe to notifications when users invoke this menu item to receive the timeline item ID. Retrieve the media from the timeline item in the [payload](https://developers.google.com/glass/reference/timeline/insert#menuItems.payload) property. - `VOICE_CALL` - Initiate a phone call using the timeline item's `creator.phoneNumber` attribute as recipient. - `NAVIGATE` - Navigate to the timeline item's `location`. - `TOGGLE_PINNED` - Toggle the `isPinned` state of the timeline item. - `OPEN_URI` - Open the `payload` of the menu item in the browser. - `PLAY_VIDEO` - Open the `payload` of the menu item in the Glass video player. - `SEND_MESSAGE` - Initiate sending a message to the timeline item's `creator`: - If the `creator.phoneNumber` is set and Glass is connected to an Android phone, the message is an SMS. - Otherwise, if the `creator.email` is set, the message is an email. | writable |
| `menuItems[].id` | `string` | The ID for this menu item. This is generated by the application and is treated as an opaque token. | writable |
| `menuItems[].payload` | `string` | A generic payload whose meaning changes depending on this MenuItem's action. - When the action is `OPEN_URI`, the payload is the URL of the website to view. - When the action is `PLAY_VIDEO`, the payload is the streaming URL of the video - When the action is `GET_MEDIA_INPUT`, the payload is the text transcription of a user's speech input | writable |
| `menuItems[].removeWhenSelected` | `boolean` | If set to true on a `CUSTOM` menu item, that item will be removed from the menu after it is selected. | writable |
| `menuItems[].values[]` | `list` | For `CUSTOM` items, a list of values controlling the appearance of the menu item in each of its states. A value for the `DEFAULT` state must be provided. If the `PENDING` or `CONFIRMED` states are missing, they will not be shown. | writable |
| `menuItems[].values[].displayName` | `string` | The name to display for the menu item. If you specify this property for a built-in menu item, the default contextual voice command for that menu item is not shown. | writable |
| `menuItems[].values[].iconUrl` | `string` | URL of an icon to display with the menu item. | writable |
| `menuItems[].values[].state` | `string` | The state that this value applies to. Allowed values are: - `DEFAULT` - Default value shown when displayed in the `menuItems` list. - `PENDING` - Value shown when the `menuItem` has been selected by the user but can still be cancelled. - `CONFIRMED` - Value shown when the menuItem has been selected by the user and can no longer be cancelled. | writable |
| `notification` | `nested object` | Controls how notifications for this item are presented on the device. If this is missing, no notification will be generated. | writable |
| `notification.deliveryTime` | `datetime` | The time at which the notification should be delivered. | writable |
| `notification.level` | `string` | Describes how important the notification is. Allowed values are: - `DEFAULT` - Notifications of default importance. A chime will be played to alert users. | writable |
| `pinScore` | `integer` | For pinned items, this determines the order in which the item is displayed in the timeline, with a higher score appearing closer to the clock. Note: setting this field is currently not supported. |   |
| `recipients[]` | `list` | A list of users or groups that this item has been shared with. | writable |
| `selfLink` | `string` | A URL that can be used to retrieve this item. |   |
| `sourceItemId` | `string` | Opaque string you can use to map a timeline item to data in your own service. | writable |
| `speakableText` | `string` | The speakable version of the content of this item. Along with the `READ_ALOUD` menu item, use this field to provide text that would be clearer when read aloud, or to provide extended information to what is displayed visually on Glass. Glassware should also specify the speakableType field, which will be spoken before this text in cases where the additional context is useful, for example when the user requests that the item be read aloud following a notification. | writable |
| `speakableType` | `string` | A speakable description of the type of this item. This will be announced to the user prior to reading the content of the item in cases where the additional context is useful, for example when the user requests that the item be read aloud following a notification. This should be a short, simple noun phrase such as "Email", "Text message", or "Daily Planet News Update". Glassware are encouraged to populate this field for every timeline item, even if the item does not contain speakableText or text so that the user can learn the type of the item without looking at the screen. | writable |
| `text` | `string` | Text content of this item. | writable |
| `title` | `string` | The title of this item. | writable |
| `updated` | `datetime` | The time at which this item was last modified, formatted according to RFC 3339. |   |

## Methods

[delete](https://developers.google.com/glass/v1/reference/timeline/delete)
:   Deletes a timeline item.

[get](https://developers.google.com/glass/v1/reference/timeline/get)
:   Gets a single timeline item by ID.

[insert](https://developers.google.com/glass/v1/reference/timeline/insert)
:   Inserts a new item into the timeline.

[list](https://developers.google.com/glass/v1/reference/timeline/list)
:   Retrieves a list of timeline items for the authenticated user.

[patch](https://developers.google.com/glass/v1/reference/timeline/patch)
:   Updates a timeline item in place. This method supports [patch semantics](https://developers.google.com/glass/performance#patch).

[update](https://developers.google.com/glass/v1/reference/timeline/update)
:   Updates a timeline item in place.