Disqus Getting Started: Quick Integration Guide (2026)

Getting started overview

Integrating Disqus into a website or application primarily involves embedding a client-side JavaScript widget to display comment sections. For more advanced interactions, such as managing comments, users, or custom data, the Disqus API offers programmatic access. This guide focuses on the initial steps required to get Disqus up and running, from account creation and key generation to making a first functional integration. Developers can manage their Disqus applications and retrieve necessary credentials through the Disqus admin integration page.

The typical integration flow involves:

1. Account Creation: Setting up a Disqus account and registering a new site or application.
2. Credential Retrieval: Obtaining the unique Public Key and Secret Key for your application.
3. Initial Integration: Implementing the basic JavaScript embed code to display a comment section.
4. API Interaction (Optional): Using the API for custom moderation tools, data exports, or advanced user management.

While the JavaScript embed handles much of the complexity for displaying comments, understanding API authentication and basic request structures is beneficial for customizing the experience or integrating with backend systems. The Disqus API supports OAuth 2.0 for secure authorization, allowing applications to act on behalf of users or access specific site data with appropriate permissions. For a comprehensive overview of the available API endpoints and authentication methods, consult the Disqus API documentation.

Create an account and get keys

To begin using Disqus, you need to create an account and register your site or application. This process generates the necessary credentials—specifically, the Public Key and Secret Key—that identify your application and authorize its interactions with the Disqus platform.

Step 1: Sign up for a Disqus account

Navigate to the Disqus homepage and sign up for a new account. You can choose a free Basic plan to start, which supports standard comment embedding functionality. Paid plans like Plus and Pro offer additional features such as advanced analytics and moderation tools, as detailed on the Disqus pricing page.

Step 2: Register a new site

After signing up, you will be prompted to register your first site. Follow these steps:

1. From the Disqus admin panel, select 'Add Disqus To Your Site'.
2. Enter your website name and choose a unique Disqus URL (shortname). This shortname will be used to identify your site in the embed code and API calls.
3. Select a category for your website.
4. Click 'Create Site'.

Step 3: Obtain API keys

Once your site is registered, you can access your API keys:

1. In your Disqus admin panel, navigate to Admin > Settings > Applications.
2. If you haven't already, create a new application.
3. Click on the application you created to view its details.
4. On this page, you will find your Public Key (also known as API Key) and Secret Key (also known as API Secret). These keys are crucial for authenticating API requests. The Public Key is typically used for client-side embeds, while the Secret Key is used for server-side API calls that require higher privileges.
5. Note down both keys, ensuring the Secret Key is kept confidential and never exposed in client-side code.

Your first request

The quickest way to get Disqus working is by embedding the JavaScript widget. This process does not typically involve making direct API calls for displaying comments, but rather configuring a script to load the comment system for your site. For an API-driven interaction, we will demonstrate fetching basic site information using your Public Key.

Embedding the JavaScript widget (client-side)

This is the primary method for integrating Disqus into a website. It provides a full comment section without requiring custom API calls for display.

1. Add the Universal Embed Code

Place the following code snippet where you want the comment thread to appear. Replace YOUR_DISQUS_SHORTNAME with the shortname you created for your site:

<div id="disqus_thread"></div>
<script>
    /**
     *  RECOMMENDED CONFIGURATION VARIABLES: EDIT AND UNCOMMENT THE SECTION BELOW TO INSERT DYNAMIC VALUES FROM YOUR PLATFORM OR CMS.
     *  LEARN WHY DEFINING THESE VARIABLES IS IMPORTANT: https://disqus.com/admin/universalcode/#configuration-variables
     */
    /*
    var disqus_config = function () {
        this.page.url = PAGE_URL;  // Replace PAGE_URL with your page's canonical URL variable
        this.page.identifier = PAGE_IDENTIFIER; // Replace PAGE_IDENTIFIER with your page's unique identifier variable
    };
    */
    (function() { // DON'T EDIT BELOW THIS LINE
        var d = document, s = d.createElement('script');
        s.src = 'https://YOUR_DISQUS_SHORTNAME.disqus.com/embed.js';
        s.setAttribute('data-timestamp', +new Date());
        (d.head || d.body).appendChild(s);
    })();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>

For more details on configuration variables, refer to the Disqus universal embed code documentation.

2. Configure Page Variables (Optional but Recommended)

To ensure proper threading and identification of comments across different pages, uncomment and configure the disqus_config variables. For example:

var disqus_config = function () {
    this.page.url = 'http://example.com/your-article-url'; // Canonical URL of the page
    this.page.identifier = 'unique_page_id-123'; // Unique identifier for the page
    this.page.title = 'Title of Your Article'; // Title of the page
    this.page.category_id = '123456'; // Optional: Category ID if you're using categories
    this.page.api_key = 'YOUR_PUBLIC_KEY'; // Your Public Key
};

These variables help Disqus correctly associate comments with specific content, even if the URL changes.

Making an authenticated API request (server-side example)

This example demonstrates how to fetch details about your registered forum (site) using the Disqus API. This requires your Secret Key, which should be handled securely on a server-side environment.

Endpoint: https://disqus.com/api/3.0/forums/details.json

Parameters:

• api_secret: Your Secret Key
• forum: Your Disqus shortname

Example using curl:

curl -X GET \
  'https://disqus.com/api/3.0/forums/details.json?api_secret=YOUR_SECRET_KEY&forum=YOUR_DISQUS_SHORTNAME'

Replace YOUR_SECRET_KEY and YOUR_DISQUS_SHORTNAME with your actual credentials. A successful response will return a JSON object containing details about your forum, such as its name, ID, and other configuration settings.

For server-side applications, it's recommended to use a robust HTTP client library in your chosen programming language (e.g., Axios for Node.js, Requests for Python, Guzzle for PHP) to manage API calls and error handling. For instance, a basic Node.js example using node-fetch might look like this:

const fetch = require('node-fetch');

const API_SECRET = 'YOUR_SECRET_KEY';
const FORUM_SHORTNAME = 'YOUR_DISQUS_SHORTNAME';

async function getForumDetails() {
  try {
    const response = await fetch(
      `https://disqus.com/api/3.0/forums/details.json?api_secret=${API_SECRET}&forum=${FORUM_SHORTNAME}`
    );
    const data = await response.json();
    if (response.ok) {
      console.log('Forum details:', data.response);
    } else {
      console.error('Error fetching forum details:', data.response);
    }
  } catch (error) {
    console.error('Network or parsing error:', error);
  }
}

getForumDetails();

This provides a foundational understanding of how to interact with the Disqus API directly, which is useful for advanced features beyond the basic embed.

Quick Reference: Getting Started Steps

Common next steps

Once you have the basic Disqus embed working or have successfully made your first API call, consider these common next steps for further integration and customization:

• Configure Embed Variables: Customize the embed code using configuration variables to dynamically set page URLs, identifiers, and titles. This ensures comments are correctly associated with specific content and improves SEO.
• Moderation: Familiarize yourself with the Disqus moderation tools available in the admin panel. Enable pre-moderation, set up trusted users, and configure spam filters to maintain a healthy comment section. Disqus includes features for comment moderation to help manage user-generated content.
• SSO (Single Sign-On): For a more seamless user experience, implement Disqus Single Sign-On (SSO). This allows users already authenticated on your platform to be automatically logged into Disqus comments without creating a separate Disqus account. SSO requires API integration and proper configuration of authentication mechanisms as described in the Disqus SSO documentation.
• Webhooks: Set up webhooks to receive real-time notifications about events such as new comments, comment approvals, or deletions. Webhooks can be used to synchronize comment data with your own database or trigger custom actions in your application. Consult the Disqus webhooks guide for setup instructions.
• Custom Styling: Override default Disqus styles with your own CSS to match the look and feel of your website. While direct styling of the iframe content is limited, you can influence the surrounding container and some elements through the Disqus admin settings or custom CSS on your page.
• Analytics: Explore the analytics features provided by Disqus to understand user engagement with your comment sections. This can provide insights into popular topics and active users.
• Explore Advanced API Endpoints: Beyond fetching forum details, the Disqus API offers endpoints for managing users, posts (comments), threads, and more. For example, you can use the API to programmatically create posts, list comments, or retrieve user profiles.

Troubleshooting the first call

When you encounter issues with your initial Disqus integration or API calls, consider the following common troubleshooting steps:

• Incorrect Shortname: Ensure that the YOUR_DISQUS_SHORTNAME in your embed code (s.src = 'https://YOUR_DISQUS_SHORTNAME.disqus.com/embed.js';) and API calls (forum=YOUR_DISQUS_SHORTNAME) exactly matches the shortname you set in your Disqus admin panel. A mismatch will prevent comments from loading or API requests from resolving correctly.
• Missing JavaScript: Verify that JavaScript is enabled in your browser and that no ad blockers or browser extensions are preventing the Disqus embed script from loading. Check your browser's developer console for any JavaScript errors.
• Incorrect API Keys: Double-check that you are using the correct Public Key for client-side configurations (if applicable via disqus_config) and the correct Secret Key for server-side API requests. A common mistake is using the Public Key where the Secret Key is required, or vice-versa. Ensure your Secret Key is protected and not exposed on the client-side.
• CORS Issues: If you are making client-side API requests directly (which is generally not recommended for sensitive actions due to Secret Key exposure), you might encounter Cross-Origin Resource Sharing (CORS) errors. The Disqus API is designed for server-side interaction when the Secret Key is involved. For client-side dynamic loading or actions, use the provided JavaScript SDK or proxy requests through your own backend. For more information on CORS, refer to the Mozilla Developer Network CORS documentation.
• Network Connectivity: Ensure that your server or client has stable internet connectivity to reach the Disqus API endpoints (disqus.com). Temporary network issues can lead to failed requests.
• Rate Limiting: While less common during initial setup, be aware that APIs often have rate limits. If you are making numerous rapid calls during testing, you might temporarily hit a rate limit, resulting in HTTP 429 Too Many Requests errors. Check the Disqus API documentation for specific rate limit policies.
• Page Configuration Variables: If comments are not appearing on specific pages or are incorrectly threaded, ensure that disqus_config.page.url and disqus_config.page.identifier are correctly set and unique for each page. These variables are critical for Disqus to track comments accurately.
• Firewall or Security Software: In some corporate or highly secured environments, firewalls or security software might block access to external scripts or API endpoints. Confirm that *.disqus.com domains are whitelisted if necessary.