# Using mobile push notifications for Amazon Chime SDK messaging to receive messages
Using mobile push notifications to receive messages

You can configure Amazon Chime SDK Messaging to send channel messages to mobile push notification channels. The Amazon Chime SDK requires an Amazon Pinpoint application configured for push notifications. Your Amazon Pinpoint application must meet these prerequisites: 
+ Your Amazon Pinpoint application must have at least an FCM or APNS channel configured and enabled.
+ Your Amazon Pinpoint application must reside in the same AWS account and region as your Amazon Chime SDK app instance.

**Note**  
By default, all the members of a push notification channel receive the push notifications, including message senders. However, you can set a filter rule that prevents messages from going to senders. For more information, see [Using filter rules to filter messages for Amazon Chime SDK messaging](filter-msgs.md), later in this section.

**Topics**
+ [

# Create an Amazon Pinpoint application for Amazon Chime SDK messaging
](create-pinpoint.md)
+ [

# Create a service role for Amazon Chime SDK messaging
](create-service-role.md)
+ [

# Register a mobile device endpoint as an App Instance user for Amazon Chime SDK messaging
](register-endpoint.md)
+ [

# Send a channel message with notifications enabled in Amazon Chime SDK messaging
](send-channel-msg-with-notifications.md)
+ [

# Receiving push notifications in Amazon Chime SDK messaging
](receive-notifications.md)
+ [

# Debugging push notification failures for Amazon Chime SDK messaging
](debug-notifications.md)
+ [

# Using filter rules to filter messages for Amazon Chime SDK messaging
](filter-msgs.md)

# Create an Amazon Pinpoint application for Amazon Chime SDK messaging
Create an Amazon Pinpoint application

To send push notifications, the Amazon Chime SDK requires an Amazon Pinpoint application configured to send pushes to your mobile app. The following steps explain how to use the AWS console to create a Pinpoint application.

**To create a Amazon Pinpoint application**

1. Sign in to the AWS Management Console and open the Amazon Pinpoint console at [https://console.aws.amazon.com/pinpoint/](https://console.aws.amazon.com/pinpoint/).

   If this is your first time using Amazon Pinpoint, you see a page that introduces you to the features of the service.

1. In the **Get started** section, enter a name for your project, and then choose **Create a project**.

1. On the **Configure features** page, next to **Push Notifications** choose **Configure**.

1. On the **Set up push notifications** page, toggle **Apple Push Notification service (APNs)**, **Firebase Cloud Messaging (FCM)**, or both, and complete the required fields.
**Important**  
The Amazon Chime SDK currently only supports sending push notifications to APNs and FCM.

1. When finished, choose **Save.**

1. Return to the Amazon Pinpoint console at [https://console.aws.amazon.com/pinpoint/](https://console.aws.amazon.com/pinpoint/) and note the **Project ID** value. You use that as the ARN for your Amazon Pinpoint application.

# Create a service role for Amazon Chime SDK messaging
Create a service role

AWS uses service roles to grant permissions to an AWS service so it can access AWS resources. The policies that you attach to a service role determine which resources the service can access and what it can do with those resources. The service role that you create for the Amazon Chime SDK gives the service permission to make `SendMessages` calls to your Amazon Pinpoint application.

**To create a service role**

1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).

1. In the navigation pane, choose **Policies**, and then choose **Create Policy**.

1. Choose the **JSON** tab and copy the policy below into the text box. Be sure to replace `project_id` with the the ID of the Amazon Pinpoint application created in the previous step, and the `aws_account_id` with your AWS Account ID.

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": {
           "Action": "mobiletargeting:SendMessages",
           "Resource": "arn:aws:mobiletargeting:us-east-1:123456789012:apps/project_id/messages",
           "Effect": "Allow"
       }
   }
   ```

------

1. Choose **Next: Tags**.

1. Choose **Next: Review**, and enter **AmazonChimePushNotificationPolicy** in the **Name** field, and choose **Create Policy**.

1. In the navigation pane, choose **Roles**, and then choose **Create role**.

1. On the **Create role** page, choose **AWS service**, open the **Choose a user case** list and choose **EC2**.

1. Choose **Next: Permissions**, and in the search box, enter **AmazonChimePushNotificationPolicy**, and select the check box next to the policy.

1. Choose **Next: Tags**.

1. Choose **Next: Review**, and enter **ServiceRoleForAmazonChimePushNotification** in the **Name** field. 
**Important**  
You must use the name listed above. The Amazon Chime SDK only accepts that specific name.

1. Choose **Create role**, and on the **Roles** page. enter **ServiceRoleForAmazonChimePushNotification** in the search box, and choose the matching role.

1. Choose the **Trust Relationships** tab, choose **Edit trust relationship** and replace the existing policy with the one below.

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Principal": {
                   "Service": "messaging.chime.amazonaws.com"
                },
                "Action": "sts:AssumeRole"
            }
       ]
   }
   ```

------

1. Choose **Update Trust Policy**.

**Important**  
Modifying the role by changing the name, the permission policy, or the trust policy can break the push notification functionality. 

# Register a mobile device endpoint as an App Instance user for Amazon Chime SDK messaging
Register a mobile device endpoint as an App Instance user

To receive push notifications, app instance users must first use the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html) API to register a mobile device. They must register from a mobile app that has access to the device token for the device's operating system.

To ensure the app instance User has access to the Amazon Pinpoint application listed in the ARN, the user must have permission to call `mobiletargeting:GetApp` on the Amazon Pinpoint ARN. Otherwise, the Amazon Chime SDK throws a 403 Forbidden error when calling [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html).

This example shows the policy needed to register an endpoint.

------
#### [ JSON ]

****  

```
{ 
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "PermissionToRegisterEndpoint",
            "Effect": "Allow",
            "Action": "chime:RegisterAppInstanceUserEndpoint",
            "Resource": "arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/user/app_instance_user_id"
        },
        {
            "Sid": "PermissionToGetAppOnPinpoint",
            "Effect": "Allow",
            "Action": "mobiletargeting:GetApp",
            "Resource": "arn:aws:mobiletargeting:us-east-1:123456789012:apps/project_id"
        }
    ]
}
```

------

**To register an endpoint**
+ Use the Amazon Pinpoint ARN and your device token to call the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html) API.

# Send a channel message with notifications enabled in Amazon Chime SDK messaging
Send a channel message with notifications enabled

The [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html) API has an optional `PushNotification` attribute that the Amazon Chime SDK uses to build the push notification to send to Amazon Pinpoint. Currently, the Amazon Chime SDK only supports the notification title and body fields. 

The Amazon Chime SDK also supports APNs VoIP pushes. To send a push notification as an APNs VoIP push, set the type in the `PushNotification` attribute to VOIP.

# Receiving push notifications in Amazon Chime SDK messaging
Receiving push notifications

Along with the channel message push notification title and body, the Amazon Chime SDK also includes the channel message ID and channel ARN in the data payload. You use that information to load the full channel message.

The following examples shows a typical push notification payload.

```
{
    "pinpoint.openApp=true",
    "pinpoint.notification.title=PushNotificationTitle",
    "pinpoint.notification.body=PushNotificationBody",
    "pinpoint.campaign.campaign_id=_DIRECT",
    "pinpoint.notification.silentPush=0",
    "pinpoint.jsonBody="{
        "chime.message_id":"ChannelMessageId",
        "chime.channel_arn":"ChannelARN"
    }
}
```

## Disabling or filtering push notification receipts


The Amazon Chime SDK provides multiple options to allow app instance users to control whether they wish to receive push notifications.

**Disabling all push notifications**  
 App instance users can disable push notifications entirely by calling [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_UpdateAppInstanceUserEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_UpdateAppInstanceUserEndpoint.html) and setting the `AllowMessages` attribute to `NONE`. 

**Disabling push notifications for a channel**  
App instance users can disable push notifications for a specific channel by calling [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html) to `NONE` in the **PushNotification Preferences** field. 

**Filtering push notifications for a channel**  
App Instance users can set a filter rule so they only receive specific push notifications using the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html) API. For more information, refer to [Using filter rules to filter messages for Amazon Chime SDK messaging](filter-msgs.md). 

# Debugging push notification failures for Amazon Chime SDK messaging
Debugging push notification failures

The Amazon Chime SDK integrates with Amazon EventBridge in order to notify you of push message delivery failures. To further debug failures, you can also look into the [CloudWatch metrics](https://docs.aws.amazon.com/pinpoint/latest/userguide/monitoring-metrics.html) that Amazon Pinpoint sends for failures.

The following table lists and describes the delivery error messages.


| Message | Description | 
| --- | --- | 
| The request processing has failed because of an unknown error, exception or failure. | We encountered an internal error. Please try again. | 
| The specified resource was not found. AppInstanceUserEndpoint will be deactivated. | The Amazon Pinpoint application does not exist. | 
| Too many requests sent to Amazon Pinpoint. | Amazon Pinpoint has throttled your outgoing messages. | 
| Unable to send messages. Please verify IAM Permissions Policy on ServiceRoleForAmazonChimePushNotification. | The role created for the Amazon Chime SDK does not have permission to call `mobiletargeting:SendMessages`. Please verify the IAM policy on the role. | 
| Unable to send messages. Please verify IAM Trust Relationships on ServiceRoleForAmazonChimePushNotification. | The Amazon Chime SDK does not have permission to access the role for push notificiations.  Please verify the IAM role's trust policy contains the service principal, `messaging.chime.amazonaws.com`. | 

# Using filter rules to filter messages for Amazon Chime SDK messaging
Using filter rules to filter messages

The Amazon Chime SDK supports setting filter rules on an app instance user’s channel membership to limit which message they will receive. Filter rules are set on the channel membership and run against the message attributes map. The message attribute map must be a map of string keys to string values. Filter rules support inclusion and exclusion with exact string matching.

**Important**  
The Amazon Chime SDK only supports escaped JSON strings as the filter rule.
All members of a notification channel receive the push notifications, including message senders. To prevent that from happening, see the first example rule below.

To set filter rules on a channel membership, use the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html) API. You can include message attributes in a channel message as part of the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html) API call.

**Topics**
+ [

## Filter rule types
](#filter-rule-types)
+ [

## Filter rule limits
](#filter-rule-limits)
+ [

## Example filter rules
](#example-preference-rule)

## Filter rule types


The Amazon Chime SDK supports the following types of filter rules: 
+ Inclusive exact string matching
+ Exclusive exact string matching
+ Multiple filter rules using AND or OR

## Filter rule limits


The Amazon Chime SDK imposes the following restrictions on filter rules:
+ We only support exact string matching.
+ A total filter rules size of 2KB.
+ A total message attribute size of 1KB.
+ A maximum of five (5) separate constraints inside an OR filter rule.
+ A maximum complexity of 20 for the entire filter rule. *Complexity* is calculated as the sum of the number of keys and values in the filter rule:

  For example, this filter rule has a complexity of 4.

  ```
  "FilterRule": "{\"type\":[{\"anything-but\": [\"Room\"]}],\"mention\":[\"Bob\"]}
  ```

  We calculate that value as follows:

  ```
  Keys = “type” and “mention” - Complexity 2
  Values = "Room" and "Bob" -   Complexity 2
  
                        Total complexity = 4
  ```

## Example filter rules


The following examples show several ways to use channel membership preferences and filter rules.

**Preventing messages from going to senders**  
This filter rule sends messages to all channel members except the message sender.

```
{
    "Preferences": {
        "PushNotifications": {
            "FilterRule": "{\"type\":[{\"anything-but\": [\"USER_ARN\"]}]}",
            "AllowNotifications": "FILTERED"
        }
    }
}
```

App instance users with the preferences shown above receive a channel message with the following attributes:

```
"MessageAttributes": {
    "senderId": {
        "StringValues": ["USER_ARN"]
    }
}
```

**Inclusive string matching**  
 This filter rule allows any message with the message attribute key “mention” and the value “Bob.” 

```
{
    "Preferences": {
        "PushNotifications": {
            "FilterRule": "{\"mention\":[\"Bob\"]}",
            "AllowNotifications": "FILTERED"
        }
    }
}
```

An app instance user with the preferences shown above receives a channel message with the following message attributes:

```
"MessageAttributes": {
    "mention": {
        "StringValues": ["Bob", "Alice"]
    }
}
```

However, the app instance user will not receive a channel message with the following attributes:

```
"MessageAttributes": {
    "mention": {
        "StringValues": ["Tom"]
    }
}
```

**Exclusive string matching**  
 This filter rule allows any message except those containing the attribute key “type” and the value “Room”. 

```
{
    "Preferences": {
        "PushNotifications": {
            "FilterRule": "{\"type\":[{\"anything-but\": [\"Room\"]}]}",
            "AllowNotifications": "FILTERED"
        }
    }
}
```

An app instance user with those preferences receives a channel message with the following message attributes:

```
"MessageAttributes": {
    "type": {
        "StringValues": ["Conversation"]
    }
}
```

However, the app instance user doesn't see a channel message with the following attributes:

```
"MessageAttributes": {
    "type": {
        "StringValues": ["Room"]
    }
}
```

**A multiple filter rule with AND logic**  
When you combine filter rules with AND logic, a message must meet all the filter criteria for the filter to apply.

```
{
    "Preferences": {
        "PushNotifications": {
            "FilterRule": "{\"type\":[{\"anything-but\": [\"Room\"]}],\"mention\":[\"Bob\"]}",
            "AllowNotifications": "FILTERED"
        }
    }
}
```

An app instance user with the preferences above receives a channel message with the following message attributes:

```
"MessageAttributes": {
    "mention": {
        "StringValues": ["Bob"]
    },
    "type": {
        "StringValues": ["Conversation"]
    }
}
```

**A multiple filter rule with OR logic**  
You use `$or` to combine filter rules with OR logic. When you use OR logic, a message must meet one of the criteria for the filter to apply. 

```
{
    "Preferences": {
        "PushNotifications": {
            "FilterRule": "{\"$or\":[{\"mention\":[\"Bob\"]},{\"type\":[{\"anything-but\": [\"Room\"]}]}]}",
            "AllowNotifications": "FILTERED"
        }
    }
}
```

An app instance user with the preferences above receives a channel message with the following message attributes:

```
"MessageAttributes": {
    "mention": {
        "StringValues": ["Bob"]
    }
}
```

An app instance user with the preferences above receives a channel message with the following message attributes:

```
"MessageAttributes": {
    "type": {
        "StringValues": ["Conversation"]
    }
}
```