## Partner Triggered Notifications
### Add Message and Notify
#### Background
After a user adds a pass you may want to send them a message related to the
pass and ensure they are notified about it. Using the [Add Message API](https://developers.google.com/wallet/generic/rest/v1/genericclass/addmessage)
request with a `message_type` equal to
**`TEXT_AND_NOTIFY`** the following occurs:
1. A "[Message](https://developers.google.com/wallet/reference/rest/v1/Message.md.txt)" item is added to the "back of pass" (aka [Details
Template](https://developers.google.com/wallet/generic/resources/template#details-template)) and a push notification is sent to users with the pass saved.
2. Once the user taps the notification it opens Google Wallet to the front of the pass (a.k.a. Card view) and the user will see a callout at the top of the screen with a "View Message" button.
3. Clicking the callout will take users to the back of the pass, where new unread messages are highlighted.
#### Some considerations when sending messages with notifications to users
- Users must have notifications enabled for their passes to receive the push notifications related to messages.
- Messages may contain URIs to your website or app. Hyperlinks must be a website or app related to the pass. It is a violation of the [Acceptable Use Policy](https://payments.developers.google.com/terms/aup) to send users to links not related to the pass.
- You may send a maximum of 3 messages that trigger a push notification in a 24 hour period. Google may throttle your push notification delivery quota if it deems you are spamming your users.
- The push notification users see on their lock screen is controlled by Google Wallet.
- You can use the [UPDATE](https://developers.google.com/wallet/generic/rest/v1/genericclass/update) or [PATCH](https://developers.google.com/wallet/generic/rest/v1/genericclass/patch) methods to edit or remove message data using the regular class or object endpoint.
#### Integration Steps
When you want to notify users about a new issuer message added using the
AddMessage API, you will need to update the [AddMessageRequest](https://developers.google.com/wallet/reference/rest/v1/AddMessageRequest.md.txt)
so that the [Message](https://developers.google.com/wallet/reference/rest/v1/Message.md.txt)
which contains your new text has the [MessageType](https://developers.google.com/wallet/reference/rest/v1/Message.md.txt#MessageType)
**TEXT_AND_NOTIFY** instead of **TEXT**.
#### Example JSON Request to add message and notify in a Passes Class
```
...
"id": ISSUER_ID.CLASS_ID",
"message":
{
"header":"My Class message header",
"body": "My Class message body with a Hyperlink<\a>",
"id": "message_id",
"message_type": "TEXT_AND_NOTIFY"
},
...
```
#### Example JSON Request to add message and notify in a Passes Object
```
...
"id": OBJECT_ID",
"classId": "ISSUER_ID.CLASS_ID",
"message":
{
"header":"My Object message header",
"body": "My Object message body with a Hyperlink<\a>",
"id": "message_id",
"message_type": "TEXT_AND_NOTIFY"
},
...
```
#### Example [Response](https://developers.google.com/wallet/generic/rest/v1/genericclass/addmessage#response-body) to add message and notify for a Pass Class
```
// The updated resource
…
{
"kind": "walletobjects#walletObjectMessage",
"header": "My Object message header",
"body": "My Object message body with a Hyperlink<\a>",
"id": "message_id",
"messageType": "textAndNotify"
},
…
```
#### Exception handling
Any attempts to notify more than 3 times will yield a
**QuotaExceededException** response. Any further updates to the
pass can be set using "**TEXT** " instead of
"**TEXT_AND_NOTIFY** " as discussed in the [Integration
Steps](https://developers.google.com/wallet/generic/use-cases/trigger-push-notifications#add-message-and-notify-integration-steps).
### Nearby Notifications
This feature will show users who have enabled notifications and granted precise, always on location access to the Google Wallet app a push notification reminding them that they have saved a pass relevant to their current location.
#### Integration Steps
#### How to use
To use this feature, you need to add locations to your classes and objects. You can add up to 10
locations per class and 10 per object. Use `MerchantLocations` in your class or object
definition. You can add these locations when you use the `insert`, `patch`,
or `update` methods.
After you add locations to a class or object, Google will send notifications to users when they
are nearby. Google decides how close a user needs to be and how long they need to stay in the area
before the notification is sent. Google also controls the text of the notification.
An example of a LoyaltyClass with the MerchantLocations set:
```
{
"kind": "walletobjects#loyaltyClass",
"programLogo": {
"kind": "walletobjects#image",
"sourceUri": {
"uri":
...
}
},
"localizedProgramName": {
"kind": "walletobjects#localizedString",
"defaultValue": {
"kind": "walletobjects#translatedString",
"language": "en",
"value": "Program Name",
}
},
"id": Id1234,
"version": "1",
"allowMultipleUsersPerObject": true,
"reviewStatus": "underReview",
"enableSmartTap": false,
"localizedIssuerName": {
"kind": "walletobjects#localizedString",
"defaultValue": {
"kind": "walletobjects#translatedString",
"language": "en",
"value": "Issuer Name"
}
},
"multipleDevicesAndHoldersAllowedStatus": "multipleHolders",
"merchantLocations": [
{
"latitude": 37.79020867928078,
"longitude": -122.39004
},
{
"latitude": 37.42587,
"longitude": -122.08620
},
]
}
```
#### Expected Behavior
Users should get a sticky notifications about their passes when they are at one of the specified MerchantLocations.
If they click the notification, it will open their pass in Google Wallet.
Users can dismiss the notification with the swipe gesture. When a user leaves the location, the notification will disappear.