Using Disqus web integration
For many of the most popular platforms (e.g., WordPress), most of these steps are unnecessary as we have integrations that do all of this for you. See our list of available integrations to find out if yours is listed.
The comments embed is the core Disqus experience where most users will spend their time. By putting a snippet of code on your website, we’ll load all the necessary components for commenting experience on a specific post, article, or topic.
- Universal code is the basic drag-and-drop embed code to show the commenting embed.
- Configuration variables let you add a unique identifier, specify a link-to URL, and a title (among others) to be stored with your thread. These aren't required but are highly recommended.
- Multilingual websites allow you to override the language the embed UI displays from what you've set globally in your site settings. Using the
- AJAX sites detail how to reload the Disqus thread for AJAX/single-page applications without navigating to a new page.
- Secure (HTTPS) sites are handled out of the box with the current embedded code. See this guide if you still need to update the embed code or need help with mixed content errors.
- Single Sign-On (SSO) provides a seamless log-in experience to your users by allowing them to sign in to your site and fully use Disqus without again authenticating with Disqus.
You can display a comment count link anywhere on your site. This involves adding a small script and appending #disqus_thread to the end of href links. You can customize comment count link text at your Disqus admin's Settings > Community page. You can also translate the comment count above the postbox.
To add the comment count, follow these steps:
- Paste the following code at the bottom of your index or home page before the closing
<script id="dsq-count-scr" src="//EXAMPLE.disqus.com/count.js" async></script>.
- Change the short name variable from
EXAMPLEto whatever the short name is of the forum you're using. Your short name can also be found on your forum's Admin > Settings > General page.
- On the index or home page, append
#disqus_threadto the end of each article URL which appears inside the href tag for the article comments link. This will tell Disqus which links to look up to return the correct comment count.
Example: <a href="http://example.com/article2.html#disqus_thread">Second article</a>. See Counts for non-link elements below if you're not using
By default, Disqus looks up the count using the comment count link's
href attribute. However, you can also look up the count using a Disqus identifier. To do this, add a special attribute
data-disqus-identifier to your links.
Note: This requires setting a Disqus identifier on the comment threads themselves. Typically this is done using the
If you cannot use Disqus identifiers with your Disqus install, that's okay. Disqus will look up threads by their associated URLs using the
href attribute in comment count links on your site by simply not adding this attribute. However, we highly recommend using the Disqus identifier since URLs can change.
For the following link, Disqus will fetch the comment count by the identifier: article_1_identifier
Example: <a href="http://example.com/article1.html#disqus_thread" data-disqus-identifier="article_1_identifier">First article</a>
Counts for non-link elements
To add comment counts to <span> and <div> elements, add the class disqus-comment-count and the attribute data-disqus-identifier or data-disqus-url. Example:
<span class="disqus-comment-count" data-disqus-identifier="article_1_identifier">First article</span>
<span class="disqus-comment-count" data-disqus-url="http://example.com/article1.html">First article</span>
By default, Disqus will reload the most recent comment count with every new page load that includes
count.js is loaded, you call the following function if you'd like to poll and update the comment count dynamically:
One everyday use case of this function is to update page elements unavailable via the initial load of
Customizing comment count link text
You can customize comment count link text at your Disqus Admin > Settings > Community page.
Example scenario: Some websites show comment counts in a small circle or square and thus remove everything but the integer from their comment count links.
Note: The comment count text customization above only applies to links on your homepage or any other page that you load count.js—it is impossible to edit the comment count that displays above the comment embed.
- If you're using Disqus outside of a publicly accessible environment, see our guide on Best practices for staging, development, and preview sites at this link or below.
- If using configuration variables with the embed, set them before loading the page. None of the data you give these variables will apply after the thread is created, so they must be present before the page is loaded for the first time.
- Setting a trusted domain in your Disqus admin settings will ensure no other websites can use your Disqus short name. Ensure you include all possible domains you might load the Disqus embed on, or else you'll block yourself.
- We recommend Resetting and Archiving Large Threads when a discussion on your site grows larger than 5,000 comments. Large threads present some user experience issues and can be avoided by configuring your automatic close setting. See more on this below.
Using the Disqus API
The Disqus API provides a way to see many different points of data relating to comments on any site. It is designed as a supplemental data source and will provide a challenging method for replacing the comments embed. Once you've created a Disqus account, you can create an API application by following the guide here.
By default, the API will have a rate limit of 1000 calls per hour. Unlimited API access is currently available as an add-on for users with a Pro-level subscription. If you want to subscribe to Pro, you can do so in your subscription settings at Admin > Settings > Subscription and Billing.
Here's a list of relevant guides for how to utilize our API:
- Available Public API Data: Standard objects and common data that come with them
- API data relationships: How all the API objects relate to each other throughout Disqus
- Authentication in Disqus: How to authenticate a user for API requests using OAuth and/or single sign-on
- Permissions and scopes: Requesting permissions from users you authenticate
- API console: Use the Disqus API console to test endpoints, parameters, and application settings
- Tutorial: Send custom email notifications for new comments: Whenever a new comment is posted, you may use the API to send a custom email notification to the article author
- Disqus API Recipes: A cookbook of common recipes to help expedite your development process when using the DISQUS API
Best practices for staging, development, and preview sites
The content you store on Disqus should be properly sandboxed if your site uses a staging, testing, development, or preview site emulating live content. These are some tips on ensuring that invalid data doesn't leak onto your live site.
Use a neutral Disqus account when registering forums
This is a standard Disqus account controlled by your company or organization, which can be easily transferred as different members take on administrative duties within your Disqus forum.
Also, certain account aspects, such as API applications, can't be transferred and must be recreated.
Register multiple short names
Each short name is sandboxed from the other, and you can use that to keep test data away from the live site. For example, if you had the short name gotham installed on http://example.com/ and have a staging site at http://staging.example.com/, register and use the short name staging-Gotham for that server.
Note: There is no limit to the number of short names an account can register.
Personalizing your site
We offer several ways publishers can customize Disqus to reflect the voice of their site and community:
- Upload a default commenter avatar: Add a default site avatar for commenters who don’t have one yet. This is an excellent way to make readers feel like a part of the community.
- Create a custom moderator badge: Moderators on your site have a special badge next to their comments verifying who they are. By default, this reads "Mod," but you can easily customize this.
- Set the default sort order: If a commenter hasn't chosen a preferred sort order, the default you set is used instead. The default option of "Best" is recommended for most sites.
- Update the color scheme and typeface: Disqus automatically checks your site's font and background color and adapts to either a light or dark color scheme, along with a serif or sans-serif font. If these are detected incorrectly, you can override them.
- Customize link color: Disqus inherits your site's link colors and will use this color for all links, the Load More Comments button, and the upvote/downvote buttons when clicked. For this to work, you'll need to ensure the relevant CSS rules are inheritable by Disqus. If Disqus isn't inheriting your site's link color, this may require changing link colors in your publishing platform's (e.g., Tumblr or Squarespace) settings or editing your site's CSS stylesheets directly. To figure out which link color Disqus is inheriting:
- Locate <div id="disqus_thread">
- Insert an <a> tag into disqus_thread. This requires editing HTML in the web inspector.
- Inspect the anchor tag > expand the Computed Style dropdown > observe the 'color' parameter. This is the color that is being inherited.
The following customizations require a Pro or above subscription to enable:
- Disable Disqus branding: If you have a Pro subscription plan, you can remove the Disqus logo from your footer. You can update this by going to the General Settings page in your Disqus Admin. Unchecking the Disqus Branding option will remove the Disqus logo from the right side of the footer.
- Disable social share icons: This will allow you to disable the Facebook and Twitter social sharing buttons at both the comment and thread level. When on the Pro plan, you may disable social sharing here. Please note that even with social sharing icons disabled, a share option will still appear at the comment level but will only contain a direct link to the comment, with the previous Facebook and Twitter comment share options removed.
- Use custom fonts: For sites with a Business subscription, various fonts will be available. The desired font may be selected from the Typeface section of the General Settings page. Business Publishers may also request that new fonts be added to the Disqus system. To be assessed for addition, the font must meet the following requirements:
- Customize discussion prompts: This will allow you to customize the text in your postbox. This text will read "Start the discussion" for a thread with zero comments and "Join the discussion" for an active thread. With this feature, you can use any text with a 45-character limit. This change will apply to all threads on your site.
- Customize default thread length: This feature allows you to customize how many comments are shown in the embed when Disqus first loads on the page. This can be used to have Disqus load a smaller window when it first appears on the page. By default, 50 comments will load initially on the desktop, and 20 comments will load initially on mobile. This feature can be used to show any number of comments below 50 on the initial embed load. Please note that even with this customization enabled, clicking "Load More Comments" will load 50 comments on desktop and 20 comments on mobile.
- Customize width, margin, and padding: Disqus is set to fill 100% of the width of its parent HTML element and has no margin or padding set on its
<div>. Disqus often looks best when its parent container gives it some margin or padding. Additionally, the width of the
disqus_threadID can be adjusted using CSS.
Importing and exporting comments
Disqus supports several XML formats natively for comments. You must adapt your comments to our Custom XML import schema if they are not in these formats.
- Make sure the files you're importing are valid XML. You can use the W3C xml validating tool to check.
- Compressed files (e.g., .zip, .gzip) can't be read by default, so make sure you've decompressed these before uploading them.
- Unless you've changed some comment data, the importer will filter out duplicate comments.
- Email addresses are unique identifiers in Disqus, so ensure each user has their email address before importing. Otherwise, all comments will appear from the same user.
- Imported comments can't be permanently deleted. Consider following our guidelines for development sites to make sure the data you're importing is correct.
Importing comments into Disqus
Watch this video to understand how to import comments into Disqus across platforms.
Exporting from Disqus
Disqus provides export of all comments on your site in a g-zipped file. This is in your Moderation panel at Disqus Admin > Setup > Export. The export will be sent into a queue and then emailed to the address associated with your account once it's ready.
Note that this file can't be re-imported into Disqus as-is.
Please note: Exports may only be available for some sites. If you've requested an export file more than twice and still have not received a download link from us, an export for your site is likely unavailable.
These are other ways you can import/export/sync comments that we do not support.