# Enviar botões

> Envie botões de resposta ou de link no WhatsApp, e botões de ação no Instagram e no Messenger, com POST /v1/messages.

`POST /v1/messages` com `type: "interactive"` envia botões de resposta ou de link no WhatsApp. No Instagram e no Messenger, o equivalente é `type: "buttons"`. Os campos que valem para todos os envios estão em [Campos comuns](/send/text/#campos-comuns).

## Antes de começar

- Uma chave de API com a permissão `send` (veja [Autenticação](/api/authentication/)).
- Uma conexão **Ativa** do canal.
- Mensagem interativa é mensagem livre: só sai dentro da janela de 24 horas depois da última mensagem do contato (veja [Janelas](/api/limits/#janelas)). Fora dela, use um template.

## Botões de resposta (WhatsApp)

`interactive.type: "button"` mostra de 1 a 3 botões. Quando o contato toca em um, o `id` do botão volta para você.

**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": "Seu pedido"
        },
        "body": {
          "text": "Seu pedido #123 chegou. Deu tudo certo?"
        },
        "footer": {
          "text": "Responda em um toque"
        },
        "action": {
          "buttons": [
            {
              "type": "reply",
              "reply": {
                "id": "sim",
                "title": "Sim"
              }
            },
            {
              "type": "reply",
              "reply": {
                "id": "nao",
                "title": "Não"
              }
            }
          ]
        }
      }
    }'
```

**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": "Seu pedido"
    },
    "body": {
      "text": "Seu pedido #123 chegou. Deu tudo certo?"
    },
    "footer": {
      "text": "Responda em um toque"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "sim",
            "title": "Sim"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "nao",
            "title": "Não"
          }
        }
      ]
    }
  }
});
```

**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": "Seu pedido"
    },
    "body": {
      "text": "Seu pedido #123 chegou. Deu tudo certo?"
    },
    "footer": {
      "text": "Responda em um toque"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "sim",
            "title": "Sim"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "nao",
            "title": "Não"
          }
        }
      ]
    }
  }
}
```

| Campo | Regra |
|---|---|
| `interactive.body.text` | Obrigatório, de 1 a 1024 caracteres. |
| `interactive.header` | Opcional. `{ "type": "text", "text": "…" }` com até 60 caracteres. O tipo também pode ser `image`, `video` ou `document`. |
| `interactive.footer.text` | Opcional, até 60 caracteres. |
| `interactive.action.buttons` | De 1 a 3 itens `{ "type": "reply", "reply": { "id", "title" } }`. |
| `reply.id` | De 1 a 256 caracteres. É o que você recebe de volta. |
| `reply.title` | De 1 a 20 caracteres. É o texto do botão. |

## Botão com link (cta_url)

`interactive.type: "cta_url"` mostra um único botão que abre uma URL. `header` e `footer` são opcionais, como nos botões de resposta.

**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": "Acompanhe a entrega pelo link."
        },
        "action": {
          "name": "cta_url",
          "parameters": {
            "display_text": "Rastrear pedido",
            "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": "Acompanhe a entrega pelo link."
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "Rastrear pedido",
        "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": "Acompanhe a entrega pelo link."
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "Rastrear pedido",
        "url": "https://exemplo.com/pedido/123"
      }
    }
  }
}
```

`display_text` tem de 1 a 20 caracteres e `url` é a página que abre.

## Receber o clique

O toque chega como um evento [`message.received`](/webhooks/events/), com `data.message.content` do tipo `reply`:

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

`id` e `title` são os do botão tocado. Ligue o `id` à sua lógica, e não o texto, que você pode mudar.

## Instagram e Messenger

Nesses canais use `type: "buttons"`: um texto de 1 a 640 caracteres e de 1 a 3 botões. Cada botão é `postback` (`title` de 1 a 20 e `payload` de 1 a 1000 caracteres, devolvido quando o contato toca) ou `web_url` (`title` de 1 a 20 e `url` com https). `quick_replies` também é aceito.

**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": "Como podemos ajudar?",
        "buttons": [
          {
            "type": "postback",
            "title": "Falar com vendas",
            "payload": "vendas"
          },
          {
            "type": "web_url",
            "title": "Ver 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": "Como podemos ajudar?",
    "buttons": [
      {
        "type": "postback",
        "title": "Falar com vendas",
        "payload": "vendas"
      },
      {
        "type": "web_url",
        "title": "Ver 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": "Como podemos ajudar?",
    "buttons": [
      {
        "type": "postback",
        "title": "Falar com vendas",
        "payload": "vendas"
      },
      {
        "type": "web_url",
        "title": "Ver site",
        "url": "https://exemplo.com"
      }
    ]
  }
}
```

Para vários cartões com imagem, título e botões, use `type: "cards"`: de 1 a 10 cartões, com `title` de até 80 caracteres e, se quiser, `subtitle`, `image_url`, `default_url` e `buttons`. Veja [Tipos de mensagem](/connect/instagram/#tipos-de-mensagem).

## Outros tipos interativos

- Fluxos (Flows): [Flows](/guides/flows/).
- Catálogo, produtos e pedido com Pix: [Vendas no WhatsApp](/guides/commerce/).
- Pedido de permissão de ligação: [Ligações](/guides/calls/).
- Lista de opções: [Enviar lista](/send/list/).

## Erros comuns

- [`outside_service_window`](/errors#outside_service_window) (422): fora das 24 horas ([janelas](/api/limits/#janelas)). O fim da janela vem em `details[0].message`.
- [`type_not_supported_by_channel`](/errors#type_not_supported_by_channel) (422): o canal não aceita esse tipo. Exemplo: `interactive` no Instagram ou no Messenger, ou `buttons` no WhatsApp.
- [`validation_failed`](/errors#validation_failed) (400): corpo fora das regras, como mais de 3 botões ou título acima do limite.
