Contacts let your Glassware receive timeline items that it did not create. Users must explicitly share a timeline item with your contact by tapping on a card's **Share** menu item. ## How they work Once you create a sharing contact, sharing timeline cards follows this general flow: 1. Create a contact and define MIME types that your contact supports. 2. Insert the contact to your user's timeline. 3. The user receives a timeline item that has a **Share** menu item. Glassware must explicitly allow users to share their items with this menu item. 4. The user taps the timeline item, selects the **Share** menu item, and selects your contact. 5. The Mirror API creates a copy of the shared timeline card, gives your contact access to the copy, and inserts the copy into the user's timeline. Your Glassware cannot access the original timeline item. 6. If you [subscribed to share notifications](https://developers.google.com/glass/develop/mirror/contacts#subscribing_to_sharing_notifications), you receive a payload containing the timeline card's identifying information. You can then retrieve the timeline item with [Timeline.get](https://developers.google.com/glass/v1/reference/timeline/get). 7. You modify the shared timeline card and update the existing timeline card with [Timeline.update](https://developers.google.com/glass/v1/reference/timeline/update). ## When to use them By default, Glassware cannot access timeline items that it did not create, so contacts allow Glassware to Glassware data sharing with user consent. There are two main ways that your Glassware can use contacts: - **Allow users to share your timeline items with other contacts** : Add the [`SHARE` built-in menu item](https://developers.google.com/glass/v1/reference/timeline/insert#menuItems.action) to a timeline card. When users tap the share menu item, Glass displays a list of possible contacts to share with. - **Allow users to share timeline items with your Glassware** : Create a contact that represents your Glassware. When users want to share a timeline card, your contact appears as an option. You can also declare a list of [acceptable MIME types](https://developers.google.com/glass/reference/contacts#acceptTypes) so that your contact only appears for cards that you are interested in. To get notified of when users share a timeline card with your contact, you can subscribe to timeline notifications. ## Creating a contact To allow users to share timeline items with your Glassware, insert a contact by POSTing a [JSON representation of a contact](https://developers.google.com/glass/v1/reference/contacts) to the [insert REST endpoint](https://developers.google.com/glass/v1/reference/contacts/insert). All contacts must specify an `id`, which identifies the contact to the Glassware receiving the notifications. You must also specify a `displayName` and at least one `imageUrls`, which Glass uses to display the contact information to the user. > [!NOTE] > **Note:** For best results, use a PNG icon image that is 640 by 360 pixels with a transparent background for `imageUrls`. ### Raw HTTP POST /mirror/v1/contacts HTTP/1.1 Authorization: Bearer {auth token} Content-Type: application/json Content-Length: {length} { "id": "harold" "displayName": "Harold Penguin", "iconUrl": "https://developers.google.com/glass/images/harold.jpg" "priority": 7 } ## Subscribing to sharing notifications The Mirror API allows you to [subscribe to notifications](https://developers.google.com/glass/reference/subscriptions/insert) that are sent when the user takes specific actions on a [Timeline Item](https://developers.google.com/glass/reference/timeline) or when the user location has been updated. When you subscribe to a notification, you provide a callback URL that processes the notification. > [!NOTE] > **Note:** In production, your callback URL must support SSL. For development purposes, we provide an [subscription proxy server](https://developers.google.com/glass/subscription-proxy) that can forward notifications to your non-SSL development server. A notification from the Mirror API is sent as a `POST` request to the subscribed endpoint containing a `JSON` request body. ### Raw HTTP { "collection": "timeline", "itemId": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg", "operation": "INSERT", "userToken": "harold_penguin", "verifyToken": "random_hash_to_verify_referer", "userActions": [ { "type": "SHARE" } ] } The `itemId` attribute is the `ID` of the shared timeline item, which you can use with [Timeline.get](https://developers.google.com/glass/reference/timeline/get) to obtain the timeline item. The following example shows a typical timeline item with a photo attachment: { "id": "3hidvm0xez6r8_dacdb3103b8b604_h8rpllg", "attachments": [ { "contentType": "image/jpeg", "id": "" } ], "recipients": [ { "kind": "glass#contact", "source": "api:", "id": "", "displayName": "", "imageUrls": [ "" ] } ] } Your service must respond to the API with a `200 OK` HTTP status code if no error occurred. If your service responds with an error code, the Mirror API might try to resend the notification to your service. > [!NOTE] > **Note:** The connection will time out after 10 seconds. If a long process is required, respond right away and do the process in another thread. ## Receiving speech transcription Users can share transcribed speech with your contact through the main voice menu. There are currently two voice commands that your contact can use: - "take a note" - "post an update" For example, a user can tell us about Chipotle's upcoming birthday with the phrase: "Ok Glass... post an update to... Cat Stream... Chipotle's birthday is tomorrow!" ![](https://developers.google.com/static/glass/images/glass-screens/voice_menu_post_update_320.png) ![](https://developers.google.com/static/glass/images/glass-screens/voice_command_320.png) To use voice commands: 1. Specify the [`acceptCommands`](https://developers.google.com/glass/reference/contacts#acceptCommands) property with the appropriate [`type`](https://developers.google.com/glass/reference/contacts#acceptCommands.type): { ... "displayName": "Cat Stream", "id": "CAT_STREAM", "acceptCommands": [ {"type": "POST_AN_UPDATE"} ] } 2. Subscribe to timeline notifications to be notified that transcribed speech is available. Your Glassware receives a notification when this occurs: { "collection": "timeline", "operation": "UPDATE", "userToken": "", "verifyToken": "", "itemId": "", "userActions": [ {"type": "LAUNCH"} ] } 3. Use the `itemId` to fetch the timeline item: { "id": "", "text": "Chipotle's birthday is tomorrow", "recipients": [ {"id": "CAT_STREAM"} ] } > [!NOTE] > **Note:** When you receive the shared timeline item, update the existing timeline card with [Timeline.update](https://developers.google.com/glass/reference/timeline/update) instead of creating a new one if you are modifying the item. 4. If more than one Glassware registers a contact with the same voice command, Glass displays a second-level menu showing the [`displayName`](https://developers.google.com/glass/v1/reference/contacts#menuItems.values.displayName) of each contact. Users can then speak the contact of their choosing. If your contact's [`displayName`](https://developers.google.com/glass/v1/reference/contacts#menuItems.values.displayName) contains unpronounceable characters or is not phonetic, use the [`speakableName`](https://developers.google.com/glass/reference/contacts#speakableName) property to declare the expected pronunciation of your sharing contact. ## Captions for shared photos Users have the ability to share photos with your Glassware with an accompanying caption that they input with speech. The general user flow is: 1. The user taps a timeline item containing a photo, selects the **Share** menu item, and selects your contact. 2. The user taps again within a short period of time to add a caption to the photo. 3. The user speaks a caption. 4. The timeline item is shared with your Glassware as described previously in [How they work](https://developers.google.com/glass/develop/mirror/contacts#how_they_work). In addition, the timeline item's [`text`](https://developers.google.com/glass/reference/timeline#text) property is set with the user's transcribed caption.