# Send buttons

> Send reply or link buttons on WhatsApp, and action buttons on Instagram and Messenger, with POST /v1/messages.

`POST /v1/messages` with `type: "interactive"` sends reply or link buttons on WhatsApp. On Instagram and Messenger the equivalent is `type: "buttons"`. The fields shared by every send are in [Common fields](/en/send/text/#common-fields).

## Before you start

- An API key with the `send` permission (see [Authentication](/en/api/authentication/)).
- An **Active** connection for the channel.
- An interactive message is a free-form message: it only goes out within 24 hours of the contact's last message (see [Windows](/en/api/limits/#windows)). Outside it, use a template.

## Reply buttons (WhatsApp)

`interactive.type: "button"` shows 1 to 3 buttons. When the contact taps one, the button `id` comes back to you.

**cURL**

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
      "connection_id": "conn_...",
      "to": "5511999999999",
      "type": "interactive",
      "interactive": {
        "type": "button",
        "header": {
          "type": "text",
          "text": "Your order"
        },
        "body": {
          "text": "Your order #123 arrived. Did everything go well?"
        },
        "footer": {
          "text": "Reply with one tap"
        },
        "action": {
          "buttons": [
            {
              "type": "reply",
              "reply": {
                "id": "sim",
                "title": "Yes"
              }
            },
            {
              "type": "reply",
              "reply": {
                "id": "nao",
                "title": "No"
              }
            }
          ]
        }
      }
    }'
```

**TypeScript**

```ts
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });

const sent = await messajo.messages.send({
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": {
      "type": "text",
      "text": "Your order"
    },
    "body": {
      "text": "Your order #123 arrived. Did everything go well?"
    },
    "footer": {
      "text": "Reply with one tap"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "sim",
            "title": "Yes"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "nao",
            "title": "No"
          }
        }
      ]
    }
  }
});
```

**n8n**

n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": {
      "type": "text",
      "text": "Your order"
    },
    "body": {
      "text": "Your order #123 arrived. Did everything go well?"
    },
    "footer": {
      "text": "Reply with one tap"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "sim",
            "title": "Yes"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "nao",
            "title": "No"
          }
        }
      ]
    }
  }
}
```

| Field | Rule |
|---|---|
| `interactive.body.text` | Required, 1 to 1024 characters. |
| `interactive.header` | Optional. `{ "type": "text", "text": "…" }` with up to 60 characters. The type can also be `image`, `video` or `document`. |
| `interactive.footer.text` | Optional, up to 60 characters. |
| `interactive.action.buttons` | 1 to 3 items `{ "type": "reply", "reply": { "id", "title" } }`. |
| `reply.id` | 1 to 256 characters. This is what you get back. |
| `reply.title` | 1 to 20 characters. This is the button label. |

## Link button (cta_url)

`interactive.type: "cta_url"` shows a single button that opens a URL. `header` and `footer` are optional, as with reply buttons.

**cURL**

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
      "connection_id": "conn_...",
      "to": "5511999999999",
      "type": "interactive",
      "interactive": {
        "type": "cta_url",
        "body": {
          "text": "Track the delivery with the link."
        },
        "action": {
          "name": "cta_url",
          "parameters": {
            "display_text": "Track order",
            "url": "https://exemplo.com/pedido/123"
          }
        }
      }
    }'
```

**TypeScript**

```ts
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });

const sent = await messajo.messages.send({
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "body": {
      "text": "Track the delivery with the link."
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "Track order",
        "url": "https://exemplo.com/pedido/123"
      }
    }
  }
});
```

**n8n**

n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "body": {
      "text": "Track the delivery with the link."
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "Track order",
        "url": "https://exemplo.com/pedido/123"
      }
    }
  }
}
```

`display_text` is 1 to 20 characters and `url` is the page it opens.

## Receiving the tap

The tap arrives as a [`message.received`](/en/webhooks/events/) event, with `data.message.content` of type `reply`:

```json
{
  "type": "message.received",
  "data": {
    "message": {
      "direction": "inbound",
      "content": {
        "type": "reply",
        "kind": "button",
        "id": "sim",
        "title": "Yes",
        "description": null,
        "payload": null
      }
    }
  }
}
```

`id` and `title` are those of the tapped button. Tie your logic to the `id`, not the text, which you may change.

## Instagram and Messenger

On these channels use `type: "buttons"`: a text of 1 to 640 characters and 1 to 3 buttons. Each button is `postback` (`title` 1 to 20 and `payload` 1 to 1000 characters, returned when the contact taps) or `web_url` (`title` 1 to 20 and an https `url`). `quick_replies` is also accepted.

**cURL**

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
      "connection_id": "conn_...",
      "to": "17841400000000000",
      "type": "buttons",
      "buttons": {
        "text": "How can we help?",
        "buttons": [
          {
            "type": "postback",
            "title": "Talk to sales",
            "payload": "vendas"
          },
          {
            "type": "web_url",
            "title": "Visit site",
            "url": "https://exemplo.com"
          }
        ]
      }
    }'
```

**TypeScript**

```ts
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });

const sent = await messajo.messages.send({
  "connection_id": "conn_...",
  "to": "17841400000000000",
  "type": "buttons",
  "buttons": {
    "text": "How can we help?",
    "buttons": [
      {
        "type": "postback",
        "title": "Talk to sales",
        "payload": "vendas"
      },
      {
        "type": "web_url",
        "title": "Visit site",
        "url": "https://exemplo.com"
      }
    ]
  }
});
```

**n8n**

n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
  "connection_id": "conn_...",
  "to": "17841400000000000",
  "type": "buttons",
  "buttons": {
    "text": "How can we help?",
    "buttons": [
      {
        "type": "postback",
        "title": "Talk to sales",
        "payload": "vendas"
      },
      {
        "type": "web_url",
        "title": "Visit site",
        "url": "https://exemplo.com"
      }
    ]
  }
}
```

For several cards with image, title and buttons, use `type: "cards"`: 1 to 10 cards, with a `title` of up to 80 characters and, optionally, `subtitle`, `image_url`, `default_url` and `buttons`. See [Message types](/en/connect/instagram/#message-types).

## Other interactive types

- Flows: [Flows](/en/guides/flows/).
- Catalog, products and Pix order: [Selling on WhatsApp](/en/guides/commerce/).
- Call permission request: [Calls](/en/guides/calls/).
- Option list: [Send list](/en/send/list/).

## Common errors

- [`outside_service_window`](/en/errors#outside_service_window) (422): outside the 24 hours ([windows](/en/api/limits/#windows)). The window end is in `details[0].message`.
- [`type_not_supported_by_channel`](/en/errors#type_not_supported_by_channel) (422): the channel does not accept this type. For example, `interactive` on Instagram or Messenger, or `buttons` on WhatsApp.
- [`validation_failed`](/en/errors#validation_failed) (400): the body breaks the rules, such as more than 3 buttons or a title over the limit.
