WhatsApp Business Account - Assigned Users Management API
Copy for LLM View as Markdown Version v23.0 API for managing user assignments and permissions for WhatsApp Business Accounts. This endpoint allows businesses to manage user access to their WhatsApp Business Accounts, including listing assigned users, adding users with specific permissions, and removing user access.Base URL
| https://graph.facebook.com |Endpoints
| GET | ///assigned_users | | POST | ///assigned_users | | DELETE | ///assigned_users |GET ///assigned_users
Retrieve a list of users assigned to the WhatsApp Business Account with their permissions and user details. This endpoint supports pagination and filtering capabilities. Use Cases: Audit user access to WhatsApp Business Account Retrieve user permission assignments for compliance List all users with access for management purposes Monitor user access patterns and assignments Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: User assignment data can be cached for short periods, but permission changes may occur frequently. Implement appropriate cache invalidation strategies.Request Syntax
GET///assigned_users Try it Select language cURLJavaScriptPythonUser-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters
Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WhatsApp-Business-Account-IDstring·required Your WhatsApp Business Account ID. This ID is provided when you create the account and can be found in your Business Manager or through account management APIs. Query Parameters
businessstring·required Business ID that owns or has access to the WhatsApp Business Account. This parameter is required to specify the business context for user assignments. fieldsstring Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id, name). Available fields: id, name, business, user_type limitinteger [min: 1, max: 100] Maximum number of assigned users to return per page. Default is 25, maximum is 100. afterstring Cursor for pagination. Use this to get the next page of results. beforestring Cursor for pagination. Use this to get the previous page of results. Responses
Retrieve a list of users assigned to the WhatsApp Business Account with their permissions and user details. This endpoint supports pagination and filtering capabilities. Use Cases: Audit user access to WhatsApp Business Account Retrieve user permission assignments for compliance List all users with access for management purposes Monitor user access patterns and assignments Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. Caching: User assignment data can be cached for short periods, but permission changes may occur frequently. Implement appropriate cache invalidation strategies. 200 Successfully retrieved assigned users list Content Type: application/json Schema: AssignedUsersResponse Show child attributes
AssignedUsersResponse
dataarray of AssignedUser·required Array of assigned users Show child attributes
data[]AssignedUser User assigned to WhatsApp Business Account with permissions Show child attributes
idstring·required Unique identifier for the assigned user
namestring·required Display name of the assigned user
businessBusinessNode Business entity associated with the user Show child attributes
idstring Unique identifier for the business
namestring Name of the business
user_typeAssignedUserType Type of user assignment
pagingCursorPaging Cursor-based pagination information Show child attributes
cursorsobject Show child attributes
beforestring Cursor pointing to the start of the page of data
afterstring Cursor pointing to the end of the page of data
nextstring Graph API endpoint for the next page of results
previousstring Graph API endpoint for the previous page of results
summaryAssignedUsersSummary Summary information about assigned users Show child attributes
total_countinteger Total number of assigned users 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 404 Not Found - WhatsApp Business Account ID does not exist or is not accessible Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes Select language cURLJavaScriptPython
POST ///assigned_users
Add a user to the WhatsApp Business Account with specified permission tasks. This operation grants the user access to perform specific actions on the account based on the provided permission tasks. Use Cases: Grant user access to WhatsApp Business Account management Assign specific permission tasks for granular access control Add new team members to WhatsApp Business Account operations Configure user permissions for different business roles Permission Tasks: Different permission tasks grant access to different WhatsApp Business Account features: MANAGE: General account management permissions DEVELOP: Development and API access permissions MANAGE_TEMPLATES: Message template management MANAGE_PHONE: Phone number management MESSAGING: Send and receive messages FULL_CONTROL: Complete access to all account features Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff.Request Syntax
POST///assigned_users Try it Select language cURLJavaScriptPythonUser-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters
Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WhatsApp-Business-Account-IDstring·required Your WhatsApp Business Account ID. This ID is provided when you create the account and can be found in your Business Manager or through account management APIs. Request BodyRequired
Content Type: application/x-www-form-urlencoded Schema: object Show child attributes
userstring·required User ID of the person to add to the WhatsApp Business Account. This must be a valid Facebook user ID.
tasksarray of WhatsAppBusinessAccountPermissionTask·required Array of permission tasks to grant to the user. These tasks determine what actions the user can perform on the WhatsApp Business Account. Show child attributes
tasks[]WhatsAppBusinessAccountPermissionTask Granular permission tasks for WhatsApp Business Account access Responses
Add a user to the WhatsApp Business Account with specified permission tasks. This operation grants the user access to perform specific actions on the account based on the provided permission tasks. Use Cases: Grant user access to WhatsApp Business Account management Assign specific permission tasks for granular access control Add new team members to WhatsApp Business Account operations Configure user permissions for different business roles Permission Tasks: Different permission tasks grant access to different WhatsApp Business Account features: MANAGE: General account management permissions DEVELOP: Development and API access permissions MANAGE_TEMPLATES: Message template management MANAGE_PHONE: Phone number management MESSAGING: Send and receive messages FULL_CONTROL: Complete access to all account features Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. 200 Successfully added user to WhatsApp Business Account Content Type: application/json Schema: SuccessResponse Show child attributes
SuccessResponse
successboolean·required Indicates whether the operation was successful 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 404 Not Found - WhatsApp Business Account ID or User ID does not exist Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes Select language cURLJavaScriptPython
DELETE ///assigned_users
Remove a user’s access from the WhatsApp Business Account. This operation revokes all permissions and access rights for the specified user on the account. Use Cases: Revoke user access when they leave the organization Remove temporary access grants Clean up user permissions for security compliance Manage user lifecycle and access control Important Notes: This operation removes ALL permissions for the user on this WhatsApp Business Account The user will lose access to all account features and data This action cannot be undone - the user must be re-added if access is needed again Webhooks may be triggered to notify of user access changes Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff.Request Syntax
DELETE///assigned_users Try it Select language cURLJavaScriptPythonUser-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Path Parameters
Versionstring·required Graph API version to use for this request. Determines the API behavior and available features. WhatsApp-Business-Account-IDstring·required Your WhatsApp Business Account ID. This ID is provided when you create the account and can be found in your Business Manager or through account management APIs. Request BodyRequired
Content Type: application/x-www-form-urlencoded Schema: object Show child attributes
userstring·required User ID of the person to remove from the WhatsApp Business Account. This must be a valid Facebook user ID that is currently assigned to the account. Responses
Remove a user’s access from the WhatsApp Business Account. This operation revokes all permissions and access rights for the specified user on the account. Use Cases: Revoke user access when they leave the organization Remove temporary access grants Clean up user permissions for security compliance Manage user lifecycle and access control Important Notes: This operation removes ALL permissions for the user on this WhatsApp Business Account The user will lose access to all account features and data This action cannot be undone - the user must be re-added if access is needed again Webhooks may be triggered to notify of user access changes Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff. 200 Successfully removed user from WhatsApp Business Account Content Type: application/json Schema: SuccessResponse Show child attributes
SuccessResponse
successboolean·required Indicates whether the operation was successful 400 Bad Request - Invalid parameters or malformed request Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 401 Unauthorized - Invalid or missing access token Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 403 Forbidden - Insufficient permissions or access denied Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 404 Not Found - WhatsApp Business Account ID or User ID does not exist or is not assigned Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 422 Unprocessable Entity - Request parameters are valid but cannot be processed Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 429 Too Many Requests - Rate limit exceeded Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes 500 Internal Server Error - Unexpected server error Content Type: application/json Schema: GraphAPIError Show child attributes
GraphAPIError
errorobject·required Show child attributes
messagestring·required Human-readable error message
typestring·required Error category type
codeinteger·required Numeric error code
error_subcodeinteger More specific error subcode when available
fbtrace_idstring Unique identifier for debugging and support requests with Meta
is_transientboolean Indicates whether this error is temporary and the request should be retried
error_user_titlestring User-friendly error title for display purposes
error_user_msgstring User-friendly error message for display purposes Select language cURLJavaScriptPython

