> 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/messages/images.md).

# Images

Why settle for plain text when you can *show* what’s happening? Whether it’s a screenshot of an error log, a security camera feed, or a celebratory GIF, images add context and impact to your notifications.

* **Quantity:** You can attach **1 to 10 images** per message.
* **Source:** Images can be provided as a **direct URL** or **base64-encoded data**.
* **Captions:** Each image can have an optional caption for extra context (e.g., `"Front Door Camera Snapshot"`).

#### Use cases

Images make your notifications more useful (or just more fun). Here are some ways you can use them effectively:

**Good Use Cases**

✅ **Home Automation:** “Front door opened” with a security camera snapshot.\
✅ **Monitoring & Alerts:** A graph of CPU usage skyrocketing before disaster strikes.\
✅ **Fun & Memes:** “Deployment successful” with a GIF of fireworks.

**Bad Use Cases**

❌ **Spamming 10 images of your cat.** (Okay, maybe once.)\
❌ **Huge base64-encoded files.** (Our server will start hating you.)

#### Requirements

<table><thead><tr><th>Attribute</th><th width="124">Data Type</th><th>Validation Criteria</th></tr></thead><tbody><tr><td><code>images</code></td><td><code>array</code></td><td><code>max 10 items</code></td></tr><tr><td><code>images.*.caption</code></td><td><code>string</code></td><td><code>max 255 characters</code></td></tr><tr><td><code>images.*.url</code></td><td><code>url</code></td><td><code>a valid url the image can be downloaded from</code></td></tr><tr><td><code>images.*.body</code></td><td><code>string</code></td><td>a valid base64 encoded image</td></tr></tbody></table>

{% hint style="info" %}
Either the **body** or the **url** is required within an image.
{% endhint %}

#### Example Request

```bash
curl -X "POST" "https://api.justpush.io/messages" \
     -H 'Content-Type: application/json' \
     -d $'{
  "user": "<< USER KEY >>",
  "title": "A simple title",
  "message": "A simple test message",
  "images": [
    {
      "url": "https://picsum.photos/800/600"
      "caption": "Thanks Picsum"
    }
  ],
}'
```

#### Mobile App

Below you see an example of how this is displayed as a push message and within the app.

**Push Message**

<figure><img src="https://2086736154-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FacKz69OOmleoOndNBWa7%2Fuploads%2Fgit-blob-c1e4494c7465d43f85496a49f1f6b7402ad454e4%2Fpush-with-image.png?alt=media" alt=""><figcaption><p>Push Message with an image</p></figcaption></figure>

**JustPush.io App**

<figure><img src="https://2086736154-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FacKz69OOmleoOndNBWa7%2Fuploads%2Fgit-blob-d6d6371363a43c629ddaf110c4944a018755cf75%2Fmessage-with-image.png?alt=media" alt=""><figcaption><p>Message with an image</p></figcaption></figure>

{% hint style="info" %}
Once the image is clicked / touched, it will open in gallery mode.
{% endhint %}

***

#### Frequently Asked Questions

<details>

<summary><strong>Is there a file size limit?</strong></summary>

Yup, we don't accept images larger than **5.0MB.** Images larger won't be processed

</details>

<details>

<summary><strong>Can I mix URLs and base64 images?</strong></summary>

Absolutely! Some images can be URLs, while others can be base64-encoded in the same message.

```json
{
  "images": 
  [
    {
      "caption": "Random Image",
      "url": "https://picsum.photos/800/600"
    },
    {
      "caption": "Random Base64 Image",
      "body": "<BASE64 ENCODED IMAGE>"
    }
  ]
}
```

</details>

<details>

<summary><strong>What happens if an image fails to load?</strong></summary>

If a URL is broken or base64 data is corrupted, the image just won’t appear—no error messages, no drama.

</details>

<details>

<summary><strong>Can I send GIFs?</strong></summary>

Yes! Animated GIFs work, but they won’t be animated inside the notification.

</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/messages/images.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.