Page updated Jan 16, 2024

Subscribe and unsubscribe


Subscribe to a topic

In order to start receiving messages from your provider, you need to subscribe to a topic as follows;

2 next: (data) => console.log('Message received', data),
3 error: (error) => console.error(error),
4 complete: () => console.log('Done')

If multiple providers are defined in your app you can include the specific provider you would like to subscribe to:

1PubSub.subscribe('myTopic', { provider: 'AWSIoTProvider' }).subscribe({
2 //...
5PubSub.subscribe('myTopic', { provider: 'MqttOverWSProvider' }).subscribe({
6 //...

Note: If you do not include a specific provider it will subscribe to all of the configured PubSub providers in your app.

Following events will be triggered with subscribe()

nextTriggered every time a message is successfully received for the topic
errorTriggered when subscription attempt fails
completeTriggered when you unsubscribe from the topic

Subscribe to multiple topics

To subscribe for multiple topics, just pass a String array including the topic names:

1PubSub.subscribe(['myTopic1', 'myTopic1']).subscribe({
2 //...


To stop receiving messages from a topic, you can use unsubscribe() method:

1const sub1 = PubSub.subscribe('myTopicA').subscribe({
2 next: (data) => console.log('Message received', data),
3 error: (error) => console.error(error),
4 complete: () => console.log('Done')
8// You will no longer get messages for 'myTopicA'

Subscription connection status updates

Now that your application is setup and using pubsub subscriptions, you may want to know when the subscription is finally established, or reflect to your users when the subscription isn't healthy. You can monitor the connection state for changes via Hub.

1import { CONNECTION_STATE_CHANGE, ConnectionState } from '@aws-amplify/pubsub';
2import { Hub } from 'aws-amplify';
4Hub.listen('pubsub', (data: any) => {
5 const { payload } = data;
6 if (payload.event === CONNECTION_STATE_CHANGE) {
7 const connectionState = as ConnectionState;
8 console.log(connectionState);
9 }

Connection states

  • Connected - Connected and working with no issues.
  • ConnectedPendingDisconnect - The connection has no active subscriptions and is disconnecting.
  • ConnectedPendingKeepAlive - The connection is open, but has missed expected keep alive messages.
  • ConnectedPendingNetwork - The connection is open, but the network connection has been disrupted. When the network recovers, the connection will continue serving traffic.
  • Connecting - Attempting to connect.
  • ConnectionDisrupted - The connection is disrupted and the network is available.
  • ConnectionDisruptedPendingNetwork - The connection is disrupted and the network connection is unavailable.
  • Disconnected - Connection has no active subscriptions and is disconnecting.

Connection issues and automated reconnection

Your application can lose connectivity for any number of reasons such as network outages or when the device is put to sleep. Your subscriptions will automatically reconnect when it becomes possible to do so.

While offline, your application will miss messages and will not automatically catch up when reconnection happens. Depending on your usecase, you may want take action to catch up when your app comes back online.

1const fetchRecentData = () => {
2 // Retrieve recent data from some sort of data storage service
5let priorConnectionState: ConnectionState;
7Hub.listen("pubsub", (data: any) => {
8 const { payload } = data;
9 if (
10 payload.event === CONNECTION_STATE_CHANGE
11 ) {
13 if (priorConnectionState === ConnectionState.Connecting && === ConnectionState.Connected) {
14 fetchRecentData();
15 }
16 priorConnectionState =;
17 }
21 next: data => // Process incoming messages