Moderate Conversations API for Instagram

Updated: Jul 2, 2026

This guide explains how to use the Moderate Conversations API to:

Block a user

Unblock a user

Move a conversation to spam in the Meta Business Suite Inbox

Before you start

This guide assumes you have read the Messenger Platform Overview and implemented the needed components for sending and receiving messages and notifications.

You will need:

The ID for the Facebook Page linked to your Instagram Professional account

The Instagram-scoped ID for the customer you want to apply the action to

A Page access token requested from a person who can perform the MESSAGE task on the Facebook Page linked to your Instagram Professional account

instagram_manage_messages, instagram_basic, and business_management permissions. Advanced Access is required to use this API for conversations involving your business and people who do not have a role on your messaging app, your Facebook page, or your business

A conversation must exist between the user and Instagram business before any of the actions provided by this API can be used

Limitations

Provide up to 10 IDs per request

Specify up to 2 actions per request. unblock_user cannot be included in the same request as block_user

You cannot block an Instagram user that is linked, through accounts center, to your Instagram business account

Request parameters

`user_ids`

Property	Description
`id` string	Instagram-scoped ID for the person you want to apply the action to

Actions

Action	Description
`block_user`	Blocks user and Instagram business interactions on Instagram. Prevents a user from messaging the Instagram business and prevents the business from messaging the user. The user will not be able to find the business’s profile, posts, or stories on Instagram.
`unblock_user`	Unblocks user and Instagram business interactions on Instagram. Allows the user and business to message each other again. The user will be able to view and interact with the business’s content on Instagram.
`move_to_spam`	Marks the conversation as spam and moves the conversation to the spam folder in Meta Business Suite inbox.

Block a user

To block messaging with a user, send a POST request to the /<PAGE_ID>/moderate_conversations endpoint with the Instagram-scoped ID for the user and the block_user action.

Sample request

curl -X POST -H "Content-Type: application/json" -d '{
  "user_ids":[
    {
        "id": "<IGSID>"
    }
  ],
  "actions": [
    "block_user"
  ]
}' "https://graph.facebook.com/v22.0/<PAGE_ID>/moderate_conversations?access_token=<PAGE_ACCESS_TOKEN>"

On success, your app receives the following JSON response with the success field set to true. On failure, the API sets the success field to false.

"success": "true"

Unblock a user

To unblock a user, send a POST request to the /<PAGE_ID>/moderate_conversations endpoint with the Instagram-scoped ID for the user and the unblock_user action.

Sample request

curl -X POST -H "Content-Type: application/json" -d '{
  "user_ids":[
    {
        "id":"<IGSID>"
    }
  ],
  "actions": [
    "unblock_user"
  ]
}' "https://graph.facebook.com/v22.0/<PAGE_ID>/moderate_conversations?access_token=<PAGE_ACCESS_TOKEN>"

On success, your app receives the following JSON response with the success field set to true. On failure, the API sets the success field to false.

"success": "true"

Move conversation to spam

To mark a conversation as spam and move it to the spam folder in the Meta Business Suite inbox, send a POST request to /<PAGE_ID>/moderate_conversations with the Instagram-scoped ID for the user and the move_to_spam action.

Sample request

curl -X POST -H "Content-Type: application/json" -d '{
  "user_ids":[
    {
        "id":"<IGSID>"
    }
  ],
  "actions": [
    "move_to_spam"
  ]
}' "https://graph.facebook.com/v22.0/<PAGE_ID>/moderate_conversations?access_token=<PAGE_ACCESS_TOKEN>"

On success, your app receives the following JSON response with the success field set to true. On failure, the API sets the success field to false.

"success": "true"

Perform multiple actions for multiple users

If you would like to perform multiple actions at once for a set of users, send a POST request to /<PAGE_ID>/moderate_conversations with the Instagram-scoped IDs for the users and a list of the actions to apply to the users.

Sample request

Block two users and move the conversations to spam.

curl -X POST -H "Content-Type: application/json" -d '{
  "user_ids":[
    {
        "id":"<IGSID>"
    },
    {
        "id":"<IGSID>"
    }
  ],
  "actions": [
    "block_user",
    "move_to_spam"
  ]
}' "https://graph.facebook.com/v22.0/<PAGE_ID>/moderate_conversations?access_token=<PAGE_ACCESS_TOKEN>"

On success, your app receives the following JSON response with the success field set to true. On failure, the API sets the success field to false.

"success": "true"

Error codes

If you encounter any of the following errors while trying to complete the request for multiple users, you can retry the request with one user at a time.

Error Code	Message
`100`	Invalid parameter The provided user ids or actions may be invalid The user ID is not a valid PSID or IGSID Invalid actions
`1`	Failed to block Instagram user Failed to unblock Instagram user Instagram Direct thread not found between business and consumer Unexpected error: Failed to move Instagram thread to spam folder