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

# Buttons

Why just *read* a notification when you can *act* on it? Buttons let you turn a simple alert into an interactive experience—open a URL, trigger an API call, or acknowledge an urgent message with one tap.

* **Up to 10 buttons per message.**
* **CTA (Call to Action)**: A short, clear label (max 25 characters).
* **URL**: The destination link for the button.
* **Action Required**: If `true`, the message won’t be marked as read until the button is clicked.

#### Use Case

Buttons make your notifications actionable. Instead of just reading an alert, users can respond instantly—whether it’s fixing an issue, tracking an order, or approving a request. Here are some ways to use them effectively:

**Good Use Cases**

✅ **Incident Response:** `"🔧 Fix Now"` links to your monitoring system.\
✅ **Order Alerts:** `"📦 Track Order"` opens a shipping page.\
✅ **Security Notifications:** `"🚪 View Camera"` shows a live feed.\
✅ **Approval Requests:** `"✅ Approve" | ❌ Reject"` for workflow automation.

**Bad Use Cases**

❌ **Super long CTAs.** (`"Click this button to resolve the issue immediately"`)\
❌ **Broken or missing URLs.** (`"Open Dashboard"` should *actually* open the dashboard.)\
❌ **Using `action_required` for everything.** (Your users will not be happy.)

#### Requirements

<table><thead><tr><th>Attribute</th><th width="124">Data Type</th><th>Validation Criteria</th></tr></thead><tbody><tr><td><code>buttons</code></td><td><code>array</code></td><td><code>max 10 items</code></td></tr><tr><td><code>buttons.*.cta</code></td><td><code>string</code></td><td><code>max 255 characters</code></td></tr><tr><td><code>buttons.*.url</code></td><td><code>url</code></td><td><code>a valid url</code></td></tr><tr><td><code>buttons.*.action_required</code></td><td><code>boolean</code></td><td></td></tr></tbody></table>

#### Example Request

```bash
curl -X "POST" "https://api.justpush.io/messages" \
     -H 'Content-Type: application/json' \
     -H 'Cookie: __cf_bm=eqEiJxfuqxBpd7.rYTRfNRTh0B7MEkwceNTDR3XExoM-1742157025-1.0.1.1-XAdo4uOcyTtElg.lGx9USRnw4c8Lh6qDJ.ju.G8.gvB.bz7vTfmyPgYSqc7EGfbhVWLGlnLVDsF41l7GbCe1xqrQ7J0_iIOVZqRQVoA_WDk' \
     -d $'{
  "user": "<< USER KEY >>",     
  "message": "A simple test message",
  "title": "A simple title",
  "buttons": [
    {
      "cta": "Button1",
      "url": "https://www.action1.com",
      "action_required": false
    }
  ]
}'

```

#### 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="/files/yAthI294PaGlzV0XaUot" alt=""><figcaption><p>Push Message with Title and Message</p></figcaption></figure>

**JustPush.io App**

<figure><img src="/files/CgWO3irFUQNwbEHtY9e8" alt=""><figcaption><p>Message with a single button</p></figcaption></figure>

***

#### Frequently Asked Questions

<details>

<summary>What happens if I don’t set a URL?</summary>

Simple, the button will not do anything.

</details>

<details>

<summary>Can I mix buttons with and without <code>action_required</code>?</summary>

Yep! Some can be optional, while others require acknowledgement.

</details>

<details>

<summary>What if my CTA is longer than 25 characters?</summary>

It will get cut off, so keep it short and snappy.

</details>

<details>

<summary>Can buttons trigger actions inside apps?</summary>

At the moment we can't but we are planning to add this.

</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/buttons.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.