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

# Button Groups

## Button Groups

***

Sometimes, a single button just doesn’t cut it. **Button groups** allow you to categorize multiple actions under a single section, making notifications more organized and user-friendly.

* **Up to 4 groups per message.**
* **Each group has a name** (e.g., `"Response Options"`).
* **Each group has a CTA** (max **25 characters**) to describe its purpose.
* **Action Required Option:** Decide if a group must be used before dismissing the notification.
* **Each group contains up to 10 buttons.**
* **Each button has its own CTA (25 char max) and unique URL.**

#### **Use Cases**

Some actions naturally belong together. Button groups make it easy for users to pick the right one without clutter.

**Good Use Cases**

✅ **Incident Response:** `"Server Down! Choose an action"`

* `"🔧 Restart"` | `"📅 Schedule Fix"` | `"❌ Ignore"`

✅ **Order Management:** `"Order #12345 - What next?"`

* `"🚚 Ship Now"` | `"🔄 Change Address"` | `"🛑 Cancel Order"`

✅ **Survey or Feedback:** `"How was your experience?"`

* `"😀 Great"` | `"😐 Okay"` | `"😞 Bad"`

**Bad Use Cases**

❌ **Cramming all possible actions into one group.** (Too much choice = confusion.)\
❌ **Using long CTAs.** (`"Click this button if you want to approve the request immediately"`)\
❌ **Mixing unrelated actions.** (`"Call Support"` and `"Delete Account"` in the same group? Yikes.)

#### Requirements

<table><thead><tr><th width="266">Attribute</th><th width="124">Data Type</th><th>Validation Criteria</th></tr></thead><tbody><tr><td><code>buttons_groups</code></td><td><code>array</code></td><td><code>max 4 items</code></td></tr><tr><td><code>buttons_groups.*.name</code></td><td><code>string</code></td><td><code>max 150 characters</code></td></tr><tr><td><code>buttons_groups.*.cta</code></td><td><code>string</code></td><td><code>max 25 characters</code></td></tr><tr><td><code>buttons_groups.*.action_required</code></td><td><code>boolean</code></td><td><code>sets a pending action</code></td></tr><tr><td><code>buttons_groups.*.buttons</code></td><td><code>array</code></td><td><code>max 10 items</code></td></tr><tr><td><code>buttons_groups.*.buttons.cta</code></td><td><code>string</code></td><td><code>max 25 characters</code></td></tr><tr><td><code>buttons_groups.*.buttons.url</code></td><td><code>string</code></td><td><code>a valid url</code></td></tr></tbody></table>

#### Example Request

```bash
curl -X "POST" "https://api.justpush.io/messages" \
     -H 'Content-Type: application/json' \
     -d $'{
  "user": "<< USER KEY>>",
  "message": "A simple test message",
  "title": "A simple title",
  "button_groups": [
    {
      "buttons": [
        {
          "cta": "Button1",
          "url": "https://www.action1.com",
          "requires_action": false
        },
        {
          "cta": "Button2",
          "url": "https://www.action2.com",
          "requires_action": true
        }
      ],
      "name": "Group 1",
      "cta": "Group 1 Cta",
      "action_required": true
    }
  ]
}'

```

#### 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/6Uk2b4956s803OggNnpx" alt=""><figcaption><p>Message with a button group</p></figcaption></figure>

<figure><img src="/files/Ya7erOxuqiolDlzMIGEb" alt=""><figcaption><p>The button group opened</p></figcaption></figure>

***

#### Frequently Asked Questions

<details>

<summary>Can I mix standalone buttons with button groups?</summary>

Yes! You can use both in the same message. Go wild!

</details>

<details>

<summary>What happens if <code>action_required</code> is true?</summary>

Users must interact with at least one button from the group before the notification can be dismissed.

</details>

<details>

<summary>Do buttons inside a group share the same URL?</summary>

Nope! Each button can have its own unique URL.

</details>

<details>

<summary>Can I have more than 4 groups?</summary>

No, the max is **4 groups per message with up to 10 buttons each**—keep things tidy!

</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/button-groups.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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/button-groups.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.