Subscriptions

  • The Mirror API allows subscribing to notifications when users take actions on timeline items or when their location is updated.

  • A subscription resource represents a subscription to events on a collection and includes properties such as collection, callbackUrl, and operation.

  • Notifications contain details about the event, including the collection, item ID, operation type, and user actions.

  • The subscription resource and notifications include tokens (userToken and verifyToken) for identifying the user and verifying the notification source.

  • Methods available for subscriptions include deleting, creating, listing, and updating subscriptions.

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.