Skip to main content
GET
/
user
/
avatar
User Avatar
curl --request GET \
  --url https://api.example.com/user/avatar
{
  "400": {},
  "500": {}
}
Retrieve the profile picture URL for a WhatsApp user or group.

​
Authentication

​
Authorization
string
required
Basic authentication credentials (username:password in base64)

​
Headers

​
X-Device-Id
string
Device identifier for multi-device support. Required when multiple devices are registered. If only one device is registered, it will be used as the default.

​
Query Parameters

​
phone
string
required
Phone number with WhatsApp suffix formatExample: [email protected]
​
is_preview
boolean
Whether to fetch a preview (lower resolution) of the avatarExample: true
​
is_community
boolean
Whether to fetch a community avatarExample: false

​
Response

​
code
string
Response code indicating success or failureExample: SUCCESS
​
message
string
Human-readable response messageExample: Success
​
results
object
Avatar information
​
url
string
Direct URL to the profile pictureExample: https://pps.whatsapp.net/v/t61.24694-24/181358562_385581386633509_6230178822944778044_n.jpg?ccb=11-4&oh=df36c5b990497b8a5758a0f1ad8118a8&oe=620AA726
​
id
string
Unique identifier for the avatar imageExample: 1635239861
​
type
string
Media type of the avatarExample: image

​
Example Request

curl -X GET 'http://localhost:3000/user/[email protected]&is_preview=true' \
  -u 'username:password' \
  -H 'X-Device-Id: my-device-id'

​
Response Example

{
  "code": "SUCCESS",
  "message": "Success",
  "results": {
    "url": "https://pps.whatsapp.net/v/t61.24694-24/181358562_385581386633509_6230178822944778044_n.jpg?ccb=11-4&oh=df36c5b990497b8a5758a0f1ad8118a8&oe=620AA726",
    "id": "1635239861",
    "type": "image"
  }
}

​
Error Responses

​
400
object
Bad Request
{
  "code": "400",
  "message": "Invalid file format",
  "results": null
}
​
500
object
Internal Server Error
{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Failed to update avatar",
  "results": null
}

​
Usage Notes

  • Use is_preview=true to get a smaller, lower resolution version of the avatar
  • The avatar URL is temporary and may expire
  • For groups, use the group JID with @g.us suffix
  • The id field can be used to detect avatar changes
  • Maximum file size for avatar upload is typically 5MB
  • Images are automatically resized and cropped by WhatsApp

Build docs developers (and LLMs) love

Get started for freeTalk to us