Hide replies

​

Introduction

This endpoint gives you the ability to programmatically hide or unhide replies using criteria you define. Just like the functionality in the main X experience, replies will be hidden from the main conversation but still visible on a separate page. You can use the endpoint to create apps to help people hide replies they don’t find valuable.

The hide replies endpoint uses either OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE authentication. If successful, the endpoint hides a single Reply that was published in a Post conversation that was initiated by an authenticated user. Each conversation supports hiding up to 725 Posts.

​

Getting started with the hide replies endpoint

This quick start guide will help you make your first request to the hide replies endpoint using Postman.

If you would like to see some code snippets in different languages, please visit the hide replies API Reference page. 

​

Steps to build a PUT /tweets/:id/hidden request

​

Step one: Start with a tool or library

There are several different tools, code examples, and libraries that you can use to make a request to this endpoint, but we are going to use the Postman tool here to simplify the process.

To load X API v2 Postman collection into your environment, please click on the following button:

Once you have the X API v2 collection loaded in Postman, navigate to the hide replies endpoint.

​

Step two: Authenticate your request

To properly make a request to the X API, you need to verify that you have permission. To do so with this endpoint, you must authenticate your request using either OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE.

In this example, we are going to use OAuth 1.0a User Context.

You must add your keys and tokens – specifically your API Key, API Secret Key, OAuth 1.0a user Access Token, and OAuth 1.0a user Access Token Secret – to Postman. You can do this by selecting the environment named “X API v2” in the top-right corner of Postman and adding your keys and tokens to the “initial value” and “current value” fields (by clicking the eye icon next to the environment dropdown).

These variables will automatically be pulled into the request’s authorization tab if you’ve done this correctly.  

​

Step three: Find a Post ID to hide

The hide replies endpoint can hide or unhide replies on behalf of an authorized user. Because we are using the Access Tokens related to your user profile in this example, you will be able to hide replies from users who participate in a conversation started by you. Similarly, if you were using Access Tokens that belong to another user that authorized your app, you would be able to moderate replies to any conversations started by that account.

Ask a friend to reply to a Post (let them know you’re testing hide replies) or reply to any of your Posts from a test account. Click on that reply, then copy the numeric part of its URL. That will be the Post ID we will hide.

In this case, we will be looking at the following Post, which has the ID 1232720193182412800:

https://twitter.com/TwitterDev/status/1232720193182412800

​

Step four: Hide the Post

In Postman, open the Hide replies folder and select Hide a reply. In the Params tab, paste the Post ID next to the id field (you won’t need to replace :id in the URL). Click “Send” and you will see a successful response.

{"hidden":true}

​

Step five: Unhide the Post

Hidden Posts are moved to a separate tab in the X app. To unhide a Post in Postman, open the Hide replies folder and select Unhide a reply. In the Params tab, paste the same Post ID used in the previous step next into the id field. Click “Send” and you will see a successful response.

{"hidden":false}

The hidden field represents the hidden status of the Post. A hidden status of true means the Post is hidden. Similarly, false means the Post is not hidden.

​

Integrate

​

Manage replies by topic

Through the hide replies endpoint, you can build integrations to help people and brands keep their conversation on topic. This page shows how to manage a conversation using the hide replies and recent search endpoints.

Recent search has functionality to a conversation and its replies, and the Post payload returns Post annotations to help you understand the context and topic of each Post, regardless of language.

The app’s flow will have controls to display and manage a conversation:

1. It asks the user’s permission to read their Posts and manage their replies.

2. It pulls a recent conversation from a Post URL, and checks that the conversation is from the authenticating user.

3. It will call the recent search endpoint to display each Post in the conversation. The request will include a conversation ID search query and the annotation expansion to determine if the Post is sports-related or not, according to X’s interpretation of the Post.

4. It calls Hide replies to hide a reply when the user chooses to do so. It will also provide a way to undo this action in case, so that the user is always in control. 

5. For longer conversations, it will provide controls to paginate through search results.  

​

Optimize for the user (and for usage)

You can design a flow in a way that puts the user in control of any action they intend to make. Keeping this principle in mind also helps you build an integration that can optimize for Post consumption.

1. Because the authenticated user can only manage conversations they started, your flow should terminate early when that’s not the case.
   • Make an initial Post lookup request. Terminate the flow early if the Post URL is not valid or the conversation was not started by the authenticating user.
   • This way, your app doesn’t have to make a recent search request if the conversation cannot be moderated by the authenticated user.
2. Request user and Post fields in the same request to avoid making separate requests. This approach can also improve your app’s performance.
3. Avoid making requests when needed. This app caches a reply’s hidden status in the user’s browser. This is useful for larger conversations, where the user may want to pick up their moderation efforts at a later stage, and it helps your app optimize requests to hide or unhide replies.

​

Manage replies in realtime

With the hide replies endpoint, you can build a workflow to helps your users hide replies that have a very high-probability of being irrelevant.

Useful apps often combine technologies so that they can be valuable to their users. This page shows how to hide replies by using the Perspective API. This API is an artificial intelligence trained by Jigsaw, a unit within Google, to detect toxic comments. The application logic will work in the following way:

1. It asks the user’s permission to read their Posts and hide or unhide their replies.
2. It uses the Account Activity API to detect incoming replies.
3. It asks the Perspective API to give a “score” (a number between 0 and 1) that indicates how confident their algorithm is that a comment is similar to toxic comments it’s seen in the past. (Perspective does not store the text sent to the service).
4. It calls hide replies if the algorithm’s score is very high.

​

Strive for transparency

Because Perspective is not trained on actual Posts, certain language nuances may cause this app to hide a reply that a user wants to remain unhidden. Regardless of the technology or the approach you use when designing your app, always make the best possible effort to ensure that your users understand what your app has hidden and can make changes.

• The best option is to always trust the user and to give them full control over their decisions. This means your user experience should include controls to undo any action taken by your app on behalf of the user.
• When using an artificial intelligence, your app should use a very high confidence threshold to detect and hide Posts.
• Not everybody uses the same words, and your app should be designed to avoid any bias. Be mindful of reclaimed words and slang that may lead to false positives.
• If you are training an artificial intelligence, consider adopting a model that closely reflects language often used on X.

​

Comparing Twitter API’s hide replies endpoints

The v2 hide replies endpoint is replacing the Labs hide replies endpoint. If you have code, apps, or tools that use the Labs version of this endpoint, and are considering migrating to the newer Twitter API v2 endpoint, then this guide is for you.

In order to use the new Twitter API v2 (including the hide replies endpoint), you will need to opt in to the new developer portal, create a Project, and add an App to that Project. You can then use the credentials associated with that App to make requests to the hide replies endpoint. Adding the same App that’s enrolled for the Labs v2 hide replies endpoint will keep your users authenticated.

The following table compares the differences between Labs and the newer Twitter API v2 endpoint:  

Other migration resources

Twitter API migration hub

​

Apps using the hide replies endpoint

Here’s a collection of noteworthy apps built by developers who integrated the hide replies endpoint. By matching their technology with the X API, they created useful experiences to help all users enhance the public conversation.

Clarabridge

Clarabridge integrates hide replies so that companies can keep their X feed clean and interesting to read. Replies can be hidden manually, and agents can also use Clarabridge’s text analytics to automatically detect profanity and other language that is not in line with brand policy.

Go to website ▸

Clarabridge on X

Perspective API template app

Perspective is an artificial intelligence trained by Jigsaw (a unit within Alphabet) to detect toxic comments. This app detects a person’s incoming replies, and automatically hides a reply based on the “score” that indicates how confident Perspective is that a comment is similar to toxic comments it’s seen in the past. This is an open source template app developed by X. We encourage you to personalize it to build tools for your users.

Use app ▸

Jigsaw on X


Reshuffle

Reshuffle is a platform to connect business applications with flexible scripts. They built an integration script to detect and hide replies that include keywords you define. To try it out, make sure you have a valid app enabled for Hide replies, then follow the instructions in the repo.

Go to app ▸

Reshuffle on X


Hide unwanted replies

Dara Oladosu, the developer behind the popular app QuotedReplies, built an app that automatically hides replies that meet some of the criteria that he’s determined are more likely to exhibit abusive behavior, including replies that contain certain keywords he’s muted in the past.

Go to app ▸

Dara Oladosu on X


Pandaflow

Pandaflow is a no code platform to automate workflows. They integrate the endpoint so users can programmatically hide replies based on a custom flow they define.

Go to app ▸

Pandaflow on X

​

API Reference

​

PUT /2/tweets/:id/hidden

Hides or unhides a reply to a Tweet.

Build request with API Explorer ❯

​

Endpoint URL

https://api.x.com/2/tweets/:id/hidden

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

JSON body parameters

​

Example code with offical SDKs

• TypeScript - hide reply
• TypeScript - unhide reply
• Java - hide reply
• Java - unhide reply

(async () => {
  try {
    const hideReply = await twitterClient.tweets.hideReplyById(
      // The ID of the reply that you want to hide or unhide.
      "1228393702244134912",
      {
        hidden: true,
      }
    );
    console.dir(hideReply, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Success (reply hidden)
• Success (reply unhidden)

{
  "data": {
    "hidden": true
  }
}

​

Response fields