# The message object

The object your code returns describes the push notification JustPush will deliver. Only `title` is required; everything else is optional.

```javascript
return {
    title: "Payment received",          // required
    message: "€49.00 from Jane Doe",    // body text
    topic: "Payments",                  // groups the message under a topic
    priority: 2,                        // how prominent the alert is
    sound: "CASHREGISTER",              // notification sound
    images: [
        { url: "https://example.com/receipt.png", caption: "Receipt" }
    ],
    buttons: [
        { cta: "View receipt", url: "https://example.com/r/123" }
    ]
}
```

## Common fields

| Field                      | Type    | Notes                                                           |
| -------------------------- | ------- | --------------------------------------------------------------- |
| `title`                    | string  | **Required.** Max 255 characters.                               |
| `message`                  | string  | The body text (plain text).                                     |
| `topic`                    | string  | Groups the message under a topic; created automatically if new. |
| `priority`                 | integer | Controls prominence. See [Priority](#priority) below.           |
| `sound`                    | string  | One of the built-in sounds. See [Sounds](#sounds).              |
| `requires_acknowledgement` | boolean | Require the recipient to confirm receipt.                       |
| `expiry_ttl`               | integer | Seconds before the message auto-expires.                        |
| `images`                   | array   | Up to 10 images, each `{ url, caption }`.                       |
| `buttons`                  | array   | Up to 10 action buttons, each `{ cta, url }`.                   |
| `button_groups`            | array   | Up to 4 grouped sets of buttons.                                |

The complete field-by-field reference, including limits and nested object shapes, lives in the [Message schema](/introduction/justpush-studio/reference/message-schema.md).

## Priority

Priority changes how the notification is presented, from quiet to attention-grabbing. In Studio you can think of it on a five-step scale — **Lowest, Low, Normal, High, Highest** — which maps to the JustPush priority values. Use **High/Highest** sparingly, for things that genuinely need immediate attention.

## Sounds

Pick a built-in sound by name, e.g. `"DEFAULT"`, `"SIREN"`, `"CASHREGISTER"`, `"MAGIC"`. Use `"NONE"` for a silent notification. The full list is in the [Message schema](/introduction/justpush-studio/reference/message-schema.md#sounds).

## Buttons

Buttons add tappable actions to a notification — typically a link to the relevant page:

```javascript
buttons: [
    { cta: "Open dashboard", url: "https://app.example.com" },
    { cta: "View logs", url: "https://app.example.com/logs" }
]
```

`cta` is the label (max 25 characters). For more on grouped buttons and acknowledgement-required buttons, see the [Message schema](/introduction/justpush-studio/reference/message-schema.md).


---

# 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/writing-code/the-message-object.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.