Subscriptions

  • The Mirror API enables subscribing to notifications for user actions on timeline items or location updates.

  • Subscriptions can be customized for specific operations like updates, insertions, and deletions within the timeline, locations, or settings.

  • Notifications deliver data about the triggering event, including the collection, item ID, operation type, and user actions.

  • A callbackUrl is essential for receiving notifications, ensuring they are sent to a designated HTTPS endpoint.

  • Developers can manage subscriptions by deleting, inserting, listing, and updating them through dedicated API methods.

The Mirror API allows you to subscribe to notifications that are sent when the user takes specific actions on a timeline item or when the user location has been updated.

For a list of methods for this resource, see the end of this page.

Resource representations

A subscription to events on a collection.

{
  "kind": "mirror#subscription",
  "id": string,
  "updated": datetime,
  "collection": string,
  "operation": [
    string
  ],
  "callbackUrl": string,
  "verifyToken": string,
  "userToken": string,
  "notification": {
    "collection": string,
    "itemId": string,
    "operation": string,
    "userActions": [
      {
        "type": string,
        "payload": string
      }
    ],
    "verifyToken": string,
    "userToken": string
  }
}
Property name Value Description Notes
callbackUrl string The URL where notifications should be delivered (must start with https://). writable
collection string The collection to subscribe to. Allowed values are:
  • timeline - Changes in the timeline including insertion, deletion, and updates.
  • locations - Location updates.
  • settings - Settings updates.
 writable
id string The ID of the subscription.
kind string The type of resource. This is always mirror#subscription.
notification nested object Container object for notifications. This is not populated in the Subscription resource.
notification.collection string The collection that generated the notification.
notification.itemId string The ID of the item that generated the notification.
notification.operation string The type of operation that generated the notification.

Acceptable values are:
  • "DELETE"
  • "INSERT"
  • "MENU_ACTION"
  • "UPDATE"
notification.userActions[] list A list of actions taken by the user that triggered the notification.
notification.userActions[].payload string An optional payload for the action.

For actions of type CUSTOM, this is the ID of the custom menu item that was selected.
notification.userActions[].type string The type of action. The value of this can be:
  • SHARE - the user shared an item.
  • REPLY - the user replied to an item.
  • REPLY_ALL - the user replied to all recipients of an item.
  • CUSTOM - the user selected a custom menu item on the timeline item.
  • DELETE - the user deleted the item.
  • PIN - the user pinned the item.
  • UNPIN - the user unpinned the item.
  • LAUNCH - the user initiated a voice command.
In the future, additional types may be added. UserActions with unrecognized types should be ignored.
notification.userToken string The user token provided by the service when it subscribed for notifications.
notification.verifyToken string The secret verify token provided by the service when it subscribed for notifications.
operation[] list A list of operations that should be subscribed to. An empty list indicates that all operations on the collection should be subscribed to. Allowed values are:
  • UPDATE - The item has been updated.
  • INSERT - A new item has been inserted.
  • DELETE - The item has been deleted.
 writable
updated datetime The time at which this subscription was last modified, formatted according to RFC 3339.
userToken string An opaque token sent to the subscriber in notifications so that it can determine the ID of the user. writable
verifyToken string A secret token sent to the subscriber in notifications so that it can verify that the notification was generated by Google. writable

Methods

delete
Deletes a subscription.
insert
Creates a new subscription.
list
Retrieves a list of subscriptions for the authenticated user and service.
update
Updates an existing subscription in place.