There doesn't seem to be an documentation around this, so no wonder it has been challenging.
In order to retrieve the BuddyPress avatar URL, use the function like so:
// Assuming $user_id is the id for the desired user
echo bp_core_fetch_avatar (
array( 'item_id' => $user_id, // id of user for desired avatar
'type' => 'full',
'html' => FALSE // FALSE = return url, TRUE (default) = return img html
)
);
Here is the documentation (formatted a bit by me) from the source php file:
Documentation
bp_core_fetch_avatar( $args );
Return: string Formatted HTML <img>
element, or raw avatar URL based on $html arg.
Description:
Get an avatar for a BuddyPress object.
Supports avatars for users, groups, and blogs by default, but can be
extended to support custom components as well.
This function gives precedence to locally-uploaded avatars. When a local
avatar is not found, Gravatar is queried.
Usage
<?php bp_core_fetch_avatar( $args ); ?>
Default Usage:
<?php $args = array(
'item_id' => false,
'object' => 'user',
'type' => 'thumb',
'avatar_dir' => false,
'width' => false,
'height' => false,
'class' => 'avatar',
'css_id' => false,
'title' => false,
'alt' => '',
'email' => false,
'no_grav' => false,
'html' => true,
'extra_attr' => '',
'scheme' => null,
'rating' => {setting for 'avatar rating' option},
'force_default' => false
);
bp_core_fetch_avatar( $args ); ?>
Parameters:
All arguments are technically optional; some will, if not provided, be auto-detected by bp_core_fetch_avatar(). This auto-detection is described more below, when discussing specific arguments.
item_id
(int|bool) The numeric ID of the item for which you're requesting an avatar (eg, a user ID). If no 'item_id' is present, the function attempts to infer an ID from the 'object' + the current context: if 'object' is 'user' and the current page is a user page, 'item_id' will default to the displayed user ID; if 'group' and on a group page, to the current group ID; if 'blog', to the current blog's ID. If no 'item_id' can be determined in this way, the function returns false. Default: false.
$object
(string) The kind of object for which you're getting an avatar. BuddyPress natively supports three options: 'user', 'group', 'blog'; a plugin may register more. Default: 'user'.
$type
(string) When a new avatar is uploaded to BP, 'thumb' and 'full' versions are saved. This parameter specifies whether you'd like the 'full' or smaller 'thumb' avatar. Default: 'thumb'.
$avatar_dir
(string|bool) (auto-detected) The name of the subdirectory where the requested avatar should be found. If no value is passed, 'avatar_dir' is inferred from 'object': 'user' becomes 'avatars', 'group' becomes 'group-avatars', 'blog' becomes 'blog-avatars'.
Remember that this string denotes a subdirectory of BP's main avatar directory (usually based on {@link wp_upload_dir()}); it's a string like 'group-avatars' rather than the full directory path. Generally, it'll only be necessary to override the default value if storing avatars in a non-default location. Default: false.
$width
(int|bool) (auto-detected) Requested avatar width. The unit is px. This value is used to build the 'width' attribute for the <img>
element. If no value is passed, BP uses the global avatar width for this avatar type. Default: false.
$height
(int|bool) (auto-detected) Requested avatar height. The unit is px. This value is used to build the 'height' attribute for the <img>
element. If no value is passed, BP uses the global avatar height for this avatar type. Default: false.
$class
(string) The CSS class for the <img>
element. Note that BP uses the 'avatar' class fairly extensively in its default styling, so if you plan to pass a custom value, consider appending it to 'avatar' (eg 'avatar foo') rather than replacing it altogether. Default: 'avatar'.
$css_id
(string|bool) The CSS id for the <img>
element. Default: false.
$title
(string) The title attribute for the <img>
element. Default: false.
$alt
(string) The alt attribute for the <img>
element. In BP, this value is generally passed by the wrapper functions, where the data necessary for concatenating the string is at hand; see
{@link bp_get_activity_avatar()} for an example. Default: ''.
$email
(string|bool) An email to use in Gravatar queries. Unless otherwise configured, BP uses Gravatar as a fallback for avatars that are not provided locally. Gravatar's API requires using a hash of the user's email address; this argument provides it. If not provided, the function will infer it: for users, by getting the user's email from the database, for groups/blogs, by concatenating "{$item_id}-{$object}@{bp_get_root_domain()}". The user query adds overhead, so it's recommended that wrapper functions provide a value for 'email' when querying user IDs. Default: false.
$no_grav
(bool) Whether to disable the default Gravatar fallback. By default, BP will fall back on Gravatar when it cannot find a local avatar. In some cases, this may be undesirable, in which case 'no_grav' should be set to true. To disable Gravatar fallbacks globally, see the 'bp_core_fetch_avatar_no_grav' filter. Default: false.
$html
(bool) Whether to return an <img>
HTML element, vs a raw URL to an avatar. If false, <img>
-specific arguments (like 'css_id') will be ignored. Default: true.
$extra_attr
(string) HTML attributes to insert in the IMG element. Not sanitized. Default: ''.
$scheme
(string) URL scheme to use. See set_url_scheme() for accepted values. Default null.
$rating
(string) What rating to display Gravatars for. Accepts 'G', 'PG', 'R', 'X'. Default is the value of the 'avatar_rating' option.
$force_default
(bool) Used when creating the Gravatar URL. Whether to force the default
image regardless if the Gravatar exists. Default: false.
Notes:
To disable Gravatar query fallbacks locally, add this filter:
add_filter( 'bp_core_fetch_avatar_no_grav', '__return_true' );