# Message schema

The complete set of fields your code can return as a [message object](/introduction/justpush-studio/writing-code/the-message-object.md). Only `title` is required.

## Top-level fields

| Field                      | Type    | Limits / values                         | Description                                                             |
| -------------------------- | ------- | --------------------------------------- | ----------------------------------------------------------------------- |
| `title`                    | string  | **Required.** Max 255 chars             | The notification headline.                                              |
| `message`                  | string  | Plain text                              | The body text.                                                          |
| `topic`                    | string  | —                                       | Topic to publish under; auto-created if it doesn't exist.               |
| `topic_token`              | string  | —                                       | Secure topic identifier; takes priority over `topic` when both are set. |
| `priority`                 | integer | See [Priority](#priority)               | How prominent the alert is.                                             |
| `sound`                    | string  | See [Sounds](#sounds)                   | Built-in notification sound.                                            |
| `expiry_ttl`               | integer | seconds, max 2147483647                 | Auto-expire the message after this long.                                |
| `requires_acknowledgement` | boolean | —                                       | Require the recipient to confirm receipt.                               |
| `acknowledgement`          | object  | See [Acknowledgement](#acknowledgement) | Retry/callback behavior for acknowledgements.                           |
| `images`                   | array   | max 10                                  | Image attachments. See [Images](#images).                               |
| `buttons`                  | array   | max 10                                  | Action buttons. See [Buttons](#buttons).                                |
| `button_groups`            | array   | max 4                                   | Grouped sets of buttons. See [Button groups](#button-groups).           |

## Priority

Priority controls how prominently the notification is presented. In Studio it's a five-step scale:

| Level   | Use for                                 |
| ------- | --------------------------------------- |
| Lowest  | Background/info, no urgency.            |
| Low     | Minor updates.                          |
| Normal  | Default.                                |
| High    | Important — worth surfacing promptly.   |
| Highest | Critical — demands immediate attention. |

## Sounds

Set `sound` to one of:

```
NONE, DEFAULT, BIKE, CASHREGISTER, CLASSICAL, COSMIC, FALLING, GAMELAN,
INCOMING, INTERMISSION, MAGIC, MECHANICAL, PIANOBAR, SIREN, SPACEALARM,
TUGBOAT, ALIEN, CLIMB, PERSISTENT, ECHO, UPDOWN, VIBRATE
```

Use `NONE` for a silent notification.

## Images

Each entry in `images` (max 10):

| Field     | Type         | Notes                                                  |
| --------- | ------------ | ------------------------------------------------------ |
| `url`     | string (URL) | Source image. *(or supply `body`)*                     |
| `body`    | string       | Base64-encoded image data, as an alternative to `url`. |
| `caption` | string       | Max 255 chars.                                         |

Max file size 5 MB. Supported formats: PNG, JPG, GIF (converted to WebP).

```javascript
images: [
    { url: "https://picsum.photos/800/600", caption: "Preview" }
]
```

## Buttons

Each entry in `buttons` (max 10):

| Field             | Type         | Notes                                   |
| ----------------- | ------------ | --------------------------------------- |
| `cta`             | string       | Button label, max 25 chars.             |
| `url`             | string (URL) | Where the button leads.                 |
| `action_required` | boolean      | Whether tapping is required to dismiss. |

```javascript
buttons: [
    { cta: "Open", url: "https://example.com", action_required: false }
]
```

## Button groups

Each entry in `button_groups` (max 4):

| Field             | Type    | Notes                                  |
| ----------------- | ------- | -------------------------------------- |
| `name`            | string  | Group name, max 150 chars.             |
| `cta`             | string  | Group label, max 25 chars.             |
| `action_required` | boolean | —                                      |
| `buttons`         | array   | Up to 10 buttons, each `{ cta, url }`. |

## Acknowledgement

When `requires_acknowledgement` is true, you can refine the behavior with an `acknowledgement` object:

| Field               | Type          | Notes                               |
| ------------------- | ------------- | ----------------------------------- |
| `requires_retry`    | boolean       | Re-notify until acknowledged.       |
| `max_retries`       | integer       | Max 255.                            |
| `interval`          | integer       | 10–65535 seconds between retries.   |
| `callback_required` | boolean       | Fire a callback on acknowledgement. |
| `callback.url`      | string (URL)  | Callback destination.               |
| `callback.params`   | object (JSON) | Extra data sent with the callback.  |

```javascript
return {
    title: "Server alert",
    message: "Disk almost full",
    requires_acknowledgement: true,
    acknowledgement: {
        requires_retry: true,
        max_retries: 10,
        interval: 60
    }
}
```

***

This mirrors the JustPush message format. For the canonical API-level reference and per-field guides, see the [JustPush documentation](https://docs.justpush.io).


---

# 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/justpush-studio/reference/message-schema.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.