# WhatsApp profile picture or channel icon API

> Get any WhatsApp profile picture or channel icon from one image URL: avatarsapi.com/whatsapp/<handle>. No WhatsApp API key, no scraping code.

Put a WhatsApp Handle in the URL and the response is the profile picture or channel icon as image bytes, ready for an `<img src>`. avatarapi fetches it from WhatsApp, checks it is a real image, and caches it at the edge.

```html
<img src="https://avatarsapi.com/whatsapp/channel%3A0029Va9K6Il0LKZDRVNIOQ0d" alt="">
```

## What goes in the URL

`https://avatarsapi.com/whatsapp/<handle>`

A phone number in international format with no `+` (default), or `channel:` plus a channel id.

Percent-encode the Handle if it contains a `/`, a space, or other reserved characters.

## Options

- `?size=16..1000` sets the square size in pixels (default 400): `https://avatarsapi.com/whatsapp/channel%3A0029Va9K6Il0LKZDRVNIOQ0d?size=64`
- `?json` returns the resolved image URL instead of the bytes:

```json
{ "version": 1, "data": { "url": "https://…", "source": "whatsapp", "kind": "username" } }
```

Starter Projects can also set `?ttl=1h..28d` for the cache lifetime (default 7 days).

## When there is no picture

If the account does not exist or has no profile picture or channel icon, the response is a 404 with a JSON body whose `code` is `ENOTFOUND`. That makes `onerror` a reliable fallback:

```html
<img
  src="https://avatarsapi.com/whatsapp/channel%3A0029Va9K6Il0LKZDRVNIOQ0d"
  onerror="this.onerror=null; this.src='/default-avatar.svg'"
  alt="">
```

`EUPSTREAM` (502) means WhatsApp itself failed or changed; it is usually transient. All codes are in the [error table](https://avatarsapi.com/docs#errors).

## Related

- [Wise profile picture API](/platforms/wise)
- [X (Twitter) profile picture API](/platforms/x)
- [Xbox gamerpic API](/platforms/xboxgamertag)
- [YouTube channel avatar API](/platforms/youtube)
- [All 67 platforms](/platforms/)