> For the complete documentation index, see [llms.txt](https://docs.justpush.io/introduction/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.justpush.io/introduction/objects/topics/avatar.md).

# Avatar

Your topic’s avatar is the first thing people see when they subscribe—so make it count. By default, JustPush.io gives each topic a simple colored circle with the topic title’s initials (think Slack-style). It works… but you can do better.

Want to use your company logo? A mascot? A cat in a spacesuit? Go for it. Custom avatars make your topics more recognizable, more trustworthy, and just a little more fun.

* **Default:** Auto-generated with initials and random background color.
* **Custom:** Upload any image (PNG, JPG, or GIF) to make it yours.
* **Display:** Shown on subscription pages, device notifications, and the JustPush.io app.

{% hint style="info" %}
To keep your bandwidth as low as possible we will convert the image to a WebP format. Even your GIFs — we will use the first frame.
{% endhint %}

#### Use Cases

A good avatar adds instant recognition and a touch of personality. Here’s how people are using them:

**Good Use Cases**

✅ **Branding:** Use your company logo so users know the message is official.

✅ **Differentiate Topics:** Set distinct icons for `"🚨 Alerts"` vs. `"📦 Orders"` vs. `"💬 Feedback"`.

✅ **Internal Teams:** A fun mascot for your DevOps alerts, or your team’s group photo (if you’re brave).

✅ **Marketing:** Add flair to topics like `"🎉 Launch Updates"` or `"🔥 Hot Deals"` to make them stand out.

**Bad Use Cases**

❌ **Using the same avatar for every topic.** Confusing.

❌ **Uploading a 10MB image.** Nobody wants to load a billboard-sized JPEG.

❌ **NSFW or meme overload.** Unless you're running *that* kind of operation.

❌ **Blank avatars.** At least give us some initials, friend.

#### Requirements

| Attribute             | Data Type | Validation Criteria |
| --------------------- | --------- | ------------------- |
| `avatar`              | `array`   |                     |
| `avatar.external_url` | `string`  | A valid URL         |
| `avatar.body`         | `string`  | A valid base64 URL  |

### Example Request

```bash
curl -X "POST" "https://api.justpush.io/topics" \
     -H 'Content-Type: text/plain; charset=utf-8' \
     -d $'{
  "user": "<< USER KEY>>",
  "avatar": {
     "external_url": "https://picsum.photos/200/300"
   },
}'

```

***

### Frequently Asked Questions

<details>

<summary><strong>What image formats are supported for avatars?</strong></summary>

You can upload PNG, JPG, or GIF files. JustPush.io will handle the conversion behind the scenes—GIFs are converted to static WebP using the first frame.

</details>

<details>

<summary><strong>Can I use an animated GIF for my avatar?</strong></summary>

You can upload one, but animations won't be preserved. We convert GIFs to WebP and use only the first still image as the avatar.

</details>

<details>

<summary><strong>What happens if I don’t upload a custom avatar?</strong></summary>

A default avatar will be generated using the topic’s initials and a random background color—clean and simple, but less personal.

</details>

<details>

<summary><strong>Can I update the avatar later?</strong></summary>

Absolutely! You can change the avatar at any time to keep your topic fresh, branded, or seasonal. 🎃🎅

</details>

***

## Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.justpush.io/introduction/objects/topics/avatar.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.