iOS & APN
Let us know how we can improve our documentation:
Push Notifications for iOS
Using the APNs, your users apps can receive push notifications directly on their client app for new messages when offline. Stream supports both Certificate-based provider connection trust (.p12 certificate), as well as Token-based provider connection trust (JWT).
Setup APN Push Using Token Authentication
Token based authentication is the preferred way to setup push notifications. This method is easy to setup and provides strong security.
Step 1. Retrieve Your Team ID
Sign in to your Apple Developer Account and then navigate to Membership. Copy your Team ID
and store it somewhere safe.

Step 2. Retrieve your Bundle ID
- From App Store Connect, navigate to My Apps
- Select the app you are using Stream Chat with
-
Make sure the
App Store
tab is selected and navigate to App Information on the left bar

-
In the
Bundle ID
dropdown, make sure the proper bundle id is selected. Copy theBundle ID
.

Step 3. Generate a Token
- From your Apple Developer Account overview, navigate to Certificates, Identifiers & Providers

-
Make sure
iOS, tvOS, watchOS
is selected on the navigation pane on the left, and go to Keys > All

-
Click on the
+
button to Add a new key
-
In the
Name
field input a name for your key. In theKey Services
section, selectApple Push Notifications service (APNs)
and then click on Continue

- Review the information from the previous step and click on Confirm
-
Copy your
Key ID
and store it somewhere safe - Save the key on your hard drive

Step 4. Upload the Key Credentials to Stream Chat
Upload the TeamID
, KeyID
, Key
and BundleID
from the previous steps.
await client.updateAppSettings({
apn_config: {
auth_key: fs.readFileSync(
'./auth-key.p8',
'utf-8',
),
auth_type: 'token',
key_id: 'key_id',
bundle_id: 'com.apple.test',
team_id: 'team_id',
notification_template: `{"aps" :{"alert":{"title":"{{ sender.name }}","subtitle":"New direct message from {{ sender.name }}","body":"{{ message.text }}"},"badge":"{{ unread_count }}","category":"NEW_MESSAGE"}}`
},
});
npm install -g getstream-cli
OR yarn global add getstream-cli
. More information on initializing the CLI can be found here.
If your wish to use the APNs development endpoint instead of the production one, you must specify this when uploading the Key Credentials via the development
parameter as shown below:
await client.updateAppSettings({
apn_config: {
auth_key: fs.readFileSync(
'./auth-key.p8',
'utf-8',
),
key_id: 'key_id',
auth_type: 'token',
development: true,
bundle_id: 'com.apple.test',
team_id: 'team_id',
notification_template: `{"aps" :{"alert":{"title":"{{ sender.name }}","subtitle":"New direct message from {{ sender.name }}","body":"{{ message.text }}"},"badge":{{ unread_count }},"category":"NEW_MESSAGE"}}`
},
});
Setup APN Push Using Certificate Authentication
If token based authentication is not an option, you can setup APN with Certificate Authentication. You will need to generate a valid .p12
certificate for your application and upload it to Stream Chat.
Step 1. Create a Certificate Signing Request (CSR)
- On your Mac, open Keychain Access
- Go to Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority

- Fill out the information in the Certificate Information window as specified below and click Continue.
In the User Email Address field, enter the email address to identify with this certificate. In the Common Name field, enter your name. In the Request group, click the "Save to disk" option.

Finally, save the file on your hard drive in secure area.
Step 2. Create a Push Notification SSL Certificate
- Sign in to your Apple Developer Account and then navigate to Certificates, Identifiers & Providers

-
Make sure
iOS, tvOS, watchOS
is selected on the navigation pane on the left, and go to Certificates > All

-
Click on the
+
button to Add a new certificate

-
In the
Development
section, selectApple Push Notification service SSL (Sandbox)
and then click on Continue

- Select your app in the dropdown list and then click on Continue
-
You will see instructions on how to generate a
.certSigningRequest
file. This was already covered in the previous section. Click on Continue -
Click on Choose File and then navigate to where you have saved the
.certSigningRequest
file from the previous section, then click on Continue - Click on Download to save your certificate to your hard drive

Step 3. Export the Certificate in .p12 Format
-
On your mac, navigate to where you have saved the
.cer
file from the previous section and double click on the file. This will add it to your macOS Keychain. - Go to Keychain Access
- At the top left, select Keychains > Login
- Then, at the bottom left, select Category > Certificates

-
Select the certificate you've created in the previous step. It should look like
Apple Development IOS Push Services: YOUR_APP_NAME
and expand it to see the private key(it should be named after the Name you provided when creating theCertificate Signing Request
– the case of this example: John Smith)

-
Right-click the private key and click on Export. In the
File format
section selectPersonal Information Exchange (.p12)
and save the file on your hard drive

Step 4. Upload the Certificate to Stream Chat
await client.updateAppSettings({
apn_config: {
p12_cert: fs.readFileSync(
'./certificate.p12',
),
auth_type: 'certificate',
notification_template: `{"aps":{"alert":{"title":"{{ sender.name }}","subtitle":"New direct message from {{ sender.name }}","body":"{{ message.text }}"},"badge":{{ unread_count }},"category":"NEW_MESSAGE"}}`
},
});