Перейти к основному содержимому

Руководство по API блокировки пользователей | Документация для разработчиков

Руководство по API блокировки пользователей

Обновлено: 23 февраля 2026 г
API блокировки пользователей позволяет вашей компании блокировать доступ недобросовестных пользователей к вашим услугам.

Как это работает

При блокировке пользователя WhatsApp происходит следующее:
    Пользователь не может связаться с вашей компанией или увидеть, что вы находитесь в сети.Ваша компания не может отправлять сообщения пользователю. В противном случае вы столкнетесь с ошибкой.
    Ошибки в API возникают для каждого номера отдельно, поскольку блокировка может быть успешной для одних номеров и неудачной для других.
    API для блокировки пользователей работает синхронно.

    Ограничения

      Вы можете заблокировать только тех пользователей, которые отправляли сообщения вашей компании в течение последних 24 часов.Вы не можете использовать этот API для блокировки другого аккаунта WhatsApp Business.В черный список включено не более 64 000 пользователей.

      Функции

      API содержит три конечные точки:
      // Блокировка номеров пользователей WhatsApp POST /< PHONE_NUMBER_ID >/ block_users
      // Разблокировка номеров пользователей WhatsApp DELETE / <PHONE_NUMBER_ID> / block_users
      // Получить список заблокированных номеров пользователей WhatsApp GET / <PHONE_NUMBER_ID> / block_users

      Блокировать пользователи

      Используйте этот конечный пункт для блокировки списка номеров пользователей WhatsApp.

      Конечная точка

      ПОЧТА /<НОМЕР_ТЕЛЕФОНА_ИДЕНТИФИКАТОР>/block_users

      Текст запроса

      {
      "messaging_product": "WhatsApp",
      "block_users": [
          {
      "пользователь": "<PHONE_NUMBER> или<WA_ID> "
          }
        ]
      }
      Параметры запроса
      
Параметр

Описание

      messaging_product
      Нить
      Необходимый
      Для отправки запроса используется служба обмена сообщениями. Должна быть "WhatsApp".
      block_users
      Множество
      Необходимый
      Список пользователей для блокировки.
      Каждый элемент содержит пользователь поле.
      пользователь
      нить
      Номер телефона или идентификатор WhatsApp, который вы хотите заблокировать.
      Объект ответа
      УСПЕХ (200)

      {
      "messaging_product": "WhatsApp",
      "block_users": {
      "added_users": [
            {
      "вход": "<PHONE_NUMBER> или<WA_ID> ",
      "ва_ид": "<WA_ID> "
            }
          ]
        }
      }
      Параметры отклика
      
Параметр

Описание

      block_users
      Объект
      Содержит два списка:
        добавленные_пользователи — Список успешно заблокированных пользователей.failed_users — Список пользователей, которые не были заблокированы.
        добавленные_пользователи
        Объект
        Список успешно заблокированных пользователей.
        Содержит значения обоих параметров:
          вход
          Нить — Номер телефона пользователя WhatsApp
          wa_id
          Нить — Уникальный идентификатор пользователя WhatsApp
          failed_users
          Объект
          Список пользователей, которые не были заблокированы.
          Содержит значения:
            вход
            Нить — Номер телефона пользователя WhatsApp
            wa_id
            Нить — Уникальный идентификатор пользователя WhatsApp (может отсутствовать, если номер недействителен)
            ошибки
            Множество — Подробная информация об ошибке для пользователя
            Смешанные успехи/неудачи (400)

            {
            "messaging_product": "WhatsApp",
            "block_users": {
            "added_users": [
                  {
            "вход": "<PHONE_NUMBER> или<WA_ID> ",
            "ва_ид": "<WA_ID> "
                  },
                  {
            "вход": "<PHONE_NUMBER> или<WA_ID> ",
            "ва_ид": "<WA_ID> "
                  },
                  ...
                ],
            "failed_users": [
                  {
            "вход": "<PHONE_NUMBER> или<WA_ID> ",
            "ва_ид": "<WA_ID> ", // Может отсутствовать, если число недействительно
            "ошибки": [
                      {
            "сообщение": "<MESSAGE> ",
            "код": <CODE>,</code>
            "error_data": {
            "подробности": "<DETAILS> "
                        }
                      }
                    ]
                  }
                ]
              },
            "ошибка": {
            "сообщение": "(#139100) Не удалось заблокировать/разблокировать пользователей",
            "тип": "OAuthException",
            "код": 139100,
            "error_data": {
            "подробности": "Не удалось заблокировать некоторых пользователей, см. block_users rСписок ответов для получения подробной информации
                },
            "fbtrace_id": "<FBTRACE_ID> "
              }
            }
            Разблокировать пользователей
            Используйте этот адрес электронной почты, чтобы разблокировать список номеров пользователей WhatsApp.
            Конечная точка
            УДАЛИТЬ /<НОМЕР_ТЕЛЕФОНА_ИДЕНТИФИКАТОР>/block_users
            Текст запроса
            {
            "messaging_product": "WhatsApp",
            "block_users": [
                 {
            "пользователь": "<PHONE_NUMBER> или<WA_ID> "
                 }
               ]
            }
            Параметры запроса
            
Параметр

Описание

            messaging_product
            Нить
            Необходимый
            Для отправки запроса используется служба обмена сообщениями. Должна быть "WhatsApp".
            block_users
            Множество
            Необходимый
            Список пользователей, которых нужно разблокировать.
            Каждый элемент содержит пользователь поле.
            пользователь
            нить
            Номер телефона или идентификатор WhatsApp, который вы хотите разблокировать.
            Объект ответа
            УСПЕХ (200)

            {
            "messaging_product": "WhatsApp",
            "block_users": {
            "удалённые_пользователи": [
                  {
            "вход": "<PHONE_NUMBER> или<WA_ID> ",
            "ва_ид": "<WA_ID> "
                  }
                ]
              }
            }
            Параметры отклика
            
Параметр

Описание

            block_users
            Объект
            Содержит два списка:
              удаленные_пользователи — Список успешно разблокированных пользователей.failed_users — Список пользователей, которые не были разблокированы.
              удаленные_пользователи
              Объект
              Список успешно разблокированных пользователей.
              Содержит значения обоих параметров:
                вход
                Нить — Номер телефона пользователя WhatsApp
                wa_id
                Нить — Уникальный идентификатор пользователя WhatsApp
                failed_users
                Объект
                Список пользователей, которые не были разблокированы.
                Содержит значения:
                  вход
                  Нить — Номер телефона пользователя WhatsApp
                  wa_id
                  Нить — Уникальный идентификатор пользователя WhatsApp (может отсутствовать, если номер недействителен)
                  ошибки
                  Множество — Подробная информация об ошибке для пользователя
                  Смешанные успехи/неудачи (400)

                  {
                  "messaging_product": "WhatsApp",
                  "block_users": {
                  "удалённые_пользователи": [
                        {
                  "вход": "<PHONE_NUMBER> или<WA_ID> ",
                  "ва_ид": "<WA_ID> "
                        },
                        {
                  "вход": "<PHONE_NUMBER> или<WA_ID> ",
                  "ва_ид": "<WA_ID> "
                        },
                        ...
                      ],
                  "failed_users": [
                        {
                  "вход": "<PHONE_NUMBER> или<WA_ID> ",
                  "ва_ид": "<WA_ID> ", // Может отсутствовать, если число недействительно
                  "ошибки": [
                            {
                  "сообщение": "<MESSAGE> ",
                  "код": <CODE>,</code>
                  "error_data": {
                  "подробности": "<DETAILS> "
                              }
                            }
                          ]
                        }
                      ]
                    },
                  "ошибка": {
                  "сообщение": "(#139100) Не удалось заблокировать/разблокировать пользователей",
                  "тип": "OAuthException",
                  "код": 139100,
                  "error_data": {
                  "подробности": «Не удалось разблокировать некоторых пользователей, см. block_users» Список ответов для получения подробной информации"
                      },
                  "fbtrace_id": "<FBTRACE_ID> "
                    }
                  }
                  Получить список заблокированных номеров
                  Используйте этот адрес электронной почты, чтобы получить список заблокированных номеров для вашего бизнес-номера WhatsApp.
                  Конечная точка
                  ПОЛУЧАТЬ /<НОМЕР_ТЕЛЕФОНА_ИДЕНТИФИКАТОР>/block_users
                  Параметры запроса
                  ?лимит=10&после=<AFTER_CURSOR>&до=<ДО_КУРСОР>
                  Параметры запроса
                  
Параметр

Описание

                  лимит
                  Необязательный
                  Максимальное количество заблокированных пользователей, которое можно получить в запросе.
                  после
                  Необязательный
                  до
                  Необязательный
                  Объект ответа
                  УСПЕХ

                  {
                  "данные": [
                      {
                  "messaging_product": "WhatsApp",
                  "ва_ид": "<WA_ID> "
                      }
                    ],
                  "пейджинг": {
                  "курсоры": {
                  "после": "eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD",
                  "до": "eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD"
                      }
                    }
                  }
                  Параметры отклика
                  
Параметр

Описание

                  данные
                  Множество
                  Список заблокированных пользователей.
                  Каждый элемент содержит messaging_product и wa_id поля.
                  messaging_product
                  Нить
                  Необходимый
                  Для отправки запроса используется служба обмена сообщениями. Должна быть "WhatsApp".
                  wa_id
                  Нить
                  Уникальный идентификатор пользователя WhatsApp
                  пейджинг
                  Объект
                  коды ошибок
                  

                  

                  ОШИБКА
                  {
                  "messaging_product":
                  
"WhatsApp",
                  "ошибка":
                  
{
                  "сообщение":
                  

                  "(#139102)
Черный список
одновременное обновление",
                  "тип": "OAuthException",
                  "код": 139102,
                  "error_data": {
                  "подробности": «Во время получения данных список заблокированных пользователей был обновлен — повторите попытку»смещение 0"
                      },
                  "fbtrace_id": "<FBTRACE_ID> "
                    }
                  }
                  
Код 
                  

Описание 




                  

                  139100
                  

                  Не удалось заблокировать/разблокировать некоторых пользователей
                  


                  

                  Массовая блокировка не смогла заблокировать некоторых или всех пользователей.
                  



                  

                  139101
                  

                  Достигнут лимит черного списка
                  


                  

                  В черный список добавлено 64 000 пользователей.
                  



                  

                  139102
                  

                  Одновременное обновление списка заблокированных устройств
                  


                  

                  Проблема возникает, когда список заблокированных пользователей обновляется во время выполнения запроса на пагинацию, и значение version_id не совпадает.
                  



                  

                  139103
                  

                  Внутренняя ошибка
                  


                  

                  Внутренняя ошибка. Пожалуйста, попробуйте еще раз.
                  



                  

                  130429
                  

                  Превышен лимит запросов
                  


                  

                  Происходит при одном из следующих событий:
                  

                    В самом запросе слишком много цифр.Или же, слишком много запросов поступает за короткий промежуток времени.
                    



                    

                    131021
                    

                    Самоблокировка
                    


                    

                    Не удалось заблокировать собственный номер телефона.
                    



                    

                    131047
                    

                    Требуется возобновление взаимодействия
                    


                    

                    Это происходит, если компания не получала сообщений с этого номера в течение последних 24 часов.
                    

                    Эта ошибка также будет возвращена, если номер принадлежит недействительному пользователю WhatsApp.
                    
    
                            
                    
    
                    

            
                    
        
                    
    
                    

    
                    

    
    
                    
        
                    
             Вернуться наверх