On this page

JavaScript API & SDK Docs 12.0.0

Chat SDK

If you want to create a chat app, you can use our Chat SDK, which relies on the JavaScript SDK, is written in TypeScript, and offers a set of chat-specific methods to manage users, channels, messages, typing indicators, quotes, mentions, threads, and many more.

This guide walks you through a simple "Hello, World" application that demonstrates the core concepts of PubNub:

Setting up a connection
Sending messages
Receiving messages in real-time

Overview

This guide helps you get up and running with PubNub in your JavaScript application. The JavaScript software development kit (SDK) provides a simple interface for integrating PubNub real-time messaging. Since JavaScript is commonly used across different platforms, we provide platform-specific guidance for:

Web: For developers building browser-based applications
Node.js: For server-side applications
React: For browser-based React applications using hooks and components
React Native: For mobile app development

The core PubNub concepts and API usage remain the same across all platforms, but implementation details like lifecycle management and UI updates differ. Select the appropriate tab in each section to see platform-specific guidance.

You can use either JavaScript or TypeScript with any of these platforms. The only difference is in how you import PubNub:

For JavaScript files (.js extension): const PubNub = require('pubnub');
For TypeScript files (.ts extension): import PubNub from 'pubnub';

JavaScript SDK supports a wide variety of environments including browsers, Node.js, React Native, React, Angular, Vue, and other JavaScript frameworks.

Prerequisites

Before we dive in, make sure you have:

A basic understanding of JavaScript
For browser applications: A modern web browser
For Node.js: Node.js installed (version 22 or later)
For React: Node.js installed (version 22 or later) and a React project (e.g. created with Vite)
For React Native: React Native development environment set up
A PubNub account (we'll help you set this up!)
(Optional) If you want to use TypeScript: TypeScript installed (version 4.0 or later)

JavaScript environment setup

For detailed guidance on Node.js versions, package managers (npm, yarn, pnpm, bun), TypeScript configuration, and modern build tools like Vite, refer to the JavaScript Environment Setup guide.

Setup

Get your PubNub keys

First, get your PubNub keys:

Sign in or create an account on the PubNub Admin Portal
Create an app (or use an existing one)
Find your publish and subscribe keys in the app dashboard

When you create an app, PubNub automatically generates a keyset. You can use the same keyset for development and production, but we recommend separate keysets for each environment to improve security and management.

Install the SDK

SDK version

Always use the latest SDK version to have access to the newest features and avoid security vulnerabilities, bugs, and performance issues.

Web
Node.js
React Native
Source code
React

To integrate PubNub into your web project, add the JavaScript SDK to your HTML page using the CDN:

1<script src="https://cdn.pubnub.com/sdk/javascript/pubnub.12.0.0.js"></script>

You can also use the minified version for production:

1<script src="https://cdn.pubnub.com/sdk/javascript/pubnub.12.0.0.min.js"></script>

To integrate PubNub into your Node.js project, install the SDK using npm:

1npm install pubnub

Then import it in your project:

1const PubNub = require('pubnub');

For React Native projects, install the PubNub SDK:

1npm install pubnub

Then import it in your project:

1import PubNub from 'pubnub';

Clone the GitHub repository:

1git clone https://github.com/pubnub/javascript

Install the PubNub SDK using npm (or yarn/pnpm) in your React project:

1npm install pubnub

Then import it in your component or app entry point:

1import PubNub from 'pubnub';

If you don't have a React project yet, create one with Vite:

1npm create vite@latest my-pubnub-app -- --template react
2cd my-pubnub-app
3npm install
4npm install pubnub

Steps

Initialize PubNub

Web
Node.js
React Native
React

Create an instance of the PubNub class with your keys and a unique user ID:

1const pubnub = new PubNub({
2    publishKey: "demo",
3    subscribeKey: "demo",
4    userId: "web-user-" + Math.floor(Math.random() * 1000)
5});

Make sure to replace the demo keys with your app's publish and subscribe keys from the Admin Portal.

For more information, refer to the Configuration section of the SDK documentation.

Set up event listeners

Listeners help the application react to events and messages. You can implement custom app logic to respond to each type of message or event.

For complete details on subscribing and handling events, refer to the Publish and Subscribe API Reference.

Web
Node.js
React Native
React

1// Add listener to handle messages, presence events, and connection status
2pubnub.addListener({
  message: function(event) {
      // Handle message event
      console.log("New message:", event.message);
      // Display message in the UI
      displayMessage(event.message);
  },
  presence: function(event) {
      // Handle presence event
      console.log("Presence event:", event);
      console.log("Action:", event.action); // join, leave, timeout
      console.log("Channel:", event.channel);
      console.log("Occupancy:", event.occupancy);
  },
  status: function(event) {
      // Handle status event
      console.log("Status event:", event);
      if (event.category === "PNConnectedCategory") {
          console.log("Connected to PubNub channels!");
      } else if (event.category === "PNNetworkIssuesCategory") {
          console.log("Connection lost. Attempting to reconnect...");
      }
  }
25});
26

27// Function to display messages in the UI
28function displayMessage(message) {
  const messagesDiv = document.getElementById('messages');
  const messageElement = document.createElement('div');
  messageElement.className = 'message';
  
  // Format message based on content
  let content = '';
  if (typeof message === 'object' && message.text) {
      content = `${message.sender || 'User'}: ${message.text}`;
  } else {
      content = JSON.stringify(message);
  }
  
  messageElement.textContent = content;
  messagesDiv.appendChild(messageElement);
  messagesDiv.scrollTop = messagesDiv.scrollHeight; // Auto-scroll to bottom
44}
show all 44 lines

Create a subscription

To receive messages on a channel, you need to subscribe to it. PubNub offers an entity-based subscription approach which provides more control and flexibility:

Web
Node.js
React Native
React

1// Create a channel entity
2const channel = pubnub.channel('hello_world');
3

4// Create a subscription for this channel
5const subscription = channel.subscription();
6

7// Subscribe
8subscription.subscribe();

For more information, refer to the Subscribe section of the SDK documentation.

Publish messages

Once you've set up your subscription, you can start publishing messages to channels.

When you publish a message to a channel, PubNub delivers that message to everyone who is subscribed to that channel.

A message can be any type of JavaScript Object Notation (JSON)-serializable data (such as objects, arrays, integers, strings) that is smaller than 32 KiB.

Web
Node.js
React Native
React

1// Function to publish a message
2async function publishMessage(text) {
3    if (!text.trim()) return;
4    
5    try {
6        const result = await pubnub.publish({
7            message: {
8                text: text,
9                sender: pubnub.getUUID(),
10                time: new Date().toISOString()
11            },
12            channel: 'hello_world'
13        });
14        console.log("Message published with timetoken:", result.timetoken);
15    } catch (error) {
16        console.error("Publish failed:", error);
17    }
18}
19

20// Example: Call this function when a button is clicked
21document.getElementById('send-button').addEventListener('click', function() {
22    const input = document.getElementById('message-input');
23    publishMessage(input.value);
24    input.value = '';
25});
show all 25 lines

Run the app

Once you've implemented all the previous steps (initialization, listeners, subscription, and publishing), you're ready to run your application:

Web
Node.js
React Native
React

Save your HTML file with all the JavaScript code.
Open the file in a web browser.
Type a message in the input box and click Send.
You should see your message appear in the messages area.
To see real-time communication, open the same file in another browser tab.

Save your JavaScript file (e.g., index.js).
Run the file using Node.js:
```
node index.js
```
Type messages in the console and press Enter to send.
To see real-time communication, open another terminal window and run another instance of your app.

Start your React Native app:

npm run android
# or
npm run ios
# or
npm run web

The app should launch on the selected platform.
Type a message in the input field and tap Send.
You should see your message appear in the messages list.
To see real-time communication, run the app on another device or simulator.

Start your Vite-based React app:
```
npm run dev
```
Open http://localhost:5173 in your browser.
Type a message in the input field and click Send.
You should see your message appear in the messages list.
To see real-time communication, open the same URL in another browser tab.

Complete example

Web
Node.js
React Native
React

1<!DOCTYPE html>
2<html>
3<head>
  <meta charset="utf-8" />
  <title>PubNub Chat Example</title>
  <script src="https://cdn.pubnub.com/sdk/javascript/pubnub.12.0.0.js"></script>
  <style>
      #chat-container {
          max-width: 600px;
          margin: 0 auto;
          padding: 20px;
          font-family: Arial, sans-serif;
      }
      #messages {
          height: 300px;
          overflow-y: auto;
          border: 1px solid #ccc;
          padding: 10px;
          margin-bottom: 10px;
          background-color: #f9f9f9;
      }
      .message {
          margin-bottom: 8px;
          padding: 8px;
          border-radius: 4px;
          background-color: #e9e9e9;
      }
      .input-container {
          display: flex;
      }
      #message-input {
          flex-grow: 1;
          padding: 8px;
          margin-right: 10px;
      }
  </style>
37</head>
38<body>
  <div id="chat-container">
      <h1>PubNub Chat</h1>
      <div id="messages"></div>
      <div class="input-container">
          <input type="text" id="message-input" placeholder="Type a message..." />
          <button id="send-button">Send</button>
      </div>
  </div>
47

  <script>
      // Initialize PubNub
      const pubnub = new PubNub({
          publishKey: "demo",
          subscribeKey: "demo",
          userId: "web-user-" + Math.floor(Math.random() * 1000)
      });
55

      // Display messages in the UI
      function displayMessage(message) {
          const messagesDiv = document.getElementById('messages');
          const messageElement = document.createElement('div');
          messageElement.className = 'message';
          
          // Format message based on content
          let content = '';
          if (typeof message === 'object' && message.text) {
              content = `${message.sender || 'User'}: ${message.text}`;
          } else {
              content = JSON.stringify(message);
          }
          
          messageElement.textContent = content;
          messagesDiv.appendChild(messageElement);
          messagesDiv.scrollTop = messagesDiv.scrollHeight; // Auto-scroll to bottom
      }
74

      // Add listener to handle messages
      pubnub.addListener({
          message: function(event) {
              displayMessage(event.message);
          },
          status: function(event) {
              if (event.category === "PNConnectedCategory") {
                  console.log("Connected to PubNub!");
                  // Display a connection message
                  const messagesDiv = document.getElementById('messages');
                  const statusElement = document.createElement('div');
                  statusElement.textContent = "Connected to chat!";
                  statusElement.style.textAlign = "center";
                  statusElement.style.color = "green";
                  messagesDiv.appendChild(statusElement);
              }
          }
      });
93

      // Subscribe to a channel
      const channel = pubnub.channel('hello_world');
      const subscription = channel.subscription();
      subscription.subscribe();
98

      // Publish message function
      async function publishMessage(text) {
          if (!text.trim()) return;
          
          try {
              const result = await pubnub.publish({
                  message: {
                      text: text,
                      sender: pubnub.getUUID(),
                      time: new Date().toISOString()
                  },
                  channel: 'hello_world'
              });
              console.log("Message published with timetoken:", result.timetoken);
          } catch (error) {
              console.error("Publish failed:", error);
          }
      }
117

      // Add event listeners for the UI
      document.getElementById('send-button').addEventListener('click', function() {
          const input = document.getElementById('message-input');
          publishMessage(input.value);
          input.value = '';
      });
124

      document.getElementById('message-input').addEventListener('keypress', function(e) {
          if (e.key === 'Enter') {
              const input = document.getElementById('message-input');
              publishMessage(input.value);
              input.value = '';
          }
      });
  </script>
133</body>
134</html>
show all 134 lines

;
3import PubNub from 'pubnub';
4
5const pubnub = new PubNub({
6 publishKey: 'YOUR_PUBLISH_KEY',
7 subscribeKey: 'YOUR_SUBSCRIBE_KEY',
8 userId: 'react-user-' + Math.floor(Math.random() * 1000),
9});
10
11export default function App() {
12 const [messages, setMessages] = useState([]);
13 const [inputText, setInputText] = useState('');
14 const [isConnected, setIsConnected] = useState(false);
15 const [onlineCount, setOnlineCount] = useState(0);
16 const messagesEndRef = useRef(null);
17
18 useEffect(() => {
19 pubnub.addListener({
20 message: (event) => {
21 setMessages((prev) => [...prev, event.message]);
22 },
23 presence: (event) => {
24 // occupancy is present on join/leave/timeout/interval but not on state-change
25 if (event.action !== 'state-change') setOnlineCount(event.occupancy);
26 },
27 status: (event) => {
28 if (event.category === 'PNConnectedCategory') {
29 setIsConnected(true);
30 } else if (event.category === 'PNNetworkIssuesCategory') {
31 setIsConnected(false);
32 }
33 },
34 });
35
36 const channel = pubnub.channel('hello_world');
37 const subscription = channel.subscription({ receivePresenceEvents: true });
38 subscription.subscribe();
39
40 return () => {
41 subscription.unsubscribe();
42 pubnub.removeAllListeners();
43 };
44 }, []);
45
46 useEffect(() => {
47 messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
48 }, [messages]);
49
50 const publishMessage = async () => {
51 if (!inputText.trim() || !isConnected) return;
52
53 try {
54 await pubnub.publish({
55 message: {
56 text: inputText,
57 sender: pubnub.userId,
58 time: new Date().toISOString(),
59 },
60 channel: 'hello_world',
61 });
62 setInputText('');
63 } catch (error) {
64 console.error('Publish failed:', error);
65 }
66 };
67
68 return (
69 <div style={styles.container}>
70 <div style={styles.header}>
71 <h2 style={styles.title}>PubNub Chat</h2>
72 <span style={{ ...styles.badge, background: isConnected ? '#4CAF50' : '#F44336' }}>
73 {isConnected ? `${onlineCount} online` : 'Connecting...'}
74 </span>
75 </div>
76
77 <div style={styles.messageList}>
78 {messages.map((msg, i) => (
79 <div key={i} style={styles.message}>
80 <strong>{msg.sender || 'User'}: </strong>
81 {msg.text || JSON.stringify(msg)}
82 </div>
83 ))}
84 <div ref={messagesEndRef} />
85 </div>
86
87 <div style={styles.inputRow}>
88 <input
89 style={styles.input}
90 type="text"
91 value={inputText}
92 onChange={(e) => setInputText(e.target.value)}
93 onKeyDown={(e) => e.key === 'Enter' && publishMessage()}
94 placeholder="Type a message..."
95 />
96 <button
97 style={{
98 ...styles.sendButton,
99 opacity: !inputText.trim() || !isConnected ? 0.5 : 1,
100 }}
101 onClick={publishMessage}
102 disabled={!inputText.trim() || !isConnected}
103 >
104 Send
105 </button>
106 </div>
107 </div>
108 );
109}
110
111const styles = {
112 container: { display: 'flex', flexDirection: 'column', height: '100vh', maxWidth: 600, margin: '0 auto', fontFamily: 'Arial, sans-serif' },
113 header: { display: 'flex', alignItems: 'center', justifyContent: 'space-between', padding: '12px 16px', borderBottom: '1px solid #e0e0e0' },
114 title: { margin: 0, fontSize: 18 },
115 badge: { color: '#fff', padding: '4px 10px', borderRadius: 12, fontSize: 13 },
116 messageList: { flex: 1, overflowY: 'auto', padding: 16 },
117 message: { marginBottom: 8, padding: '8px 12px', background: '#f0f0f0', borderRadius: 8 },
118 inputRow: { display: 'flex', padding: 12, borderTop: '1px solid #e0e0e0', gap: 8 },
119 input: { flex: 1, padding: '8px 12px', borderRadius: 20, border: '1px solid #ddd', fontSize: 14 },
120 sendButton: { padding: '8px 20px', borderRadius: 20, background: '#4b0082', color: '#fff', border: 'none', cursor: 'pointer', fontWeight: 'bold' },
121};
show all 121 lines

Chat SDK

Overview​

Prerequisites​

JavaScript environment setup

Setup​

Get your PubNub keys​

Install the SDK​

SDK version

Steps​

Initialize PubNub​

Set up event listeners​

Create a subscription​

Publish messages​

Run the app​

Complete example​

Next steps​