# Enviar botones

> Envía botones de respuesta o de enlace en WhatsApp, y botones de acción en Instagram y Messenger, con POST /v1/messages.

`POST /v1/messages` con `type: "interactive"` envía botones de respuesta o de enlace en WhatsApp. En Instagram y Messenger el equivalente es `type: "buttons"`. Los campos comunes a todos los envíos están en [Campos comunes](/es/send/text/#campos-comunes).

## Antes de empezar

- Una clave de API con el permiso `send` (consulta [Autenticación](/es/api/authentication/)).
- Una conexión **Activa** del canal.
- Un mensaje interactivo es un mensaje libre: solo sale dentro de las 24 horas posteriores al último mensaje del contacto (consulta [Ventanas](/es/api/limits/#ventanas)). Fuera de ella, usa una plantilla.

## Botones de respuesta (WhatsApp)

`interactive.type: "button"` muestra de 1 a 3 botones. Cuando el contacto toca uno, el `id` del botón te vuelve.

**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": "Tu pedido"
        },
        "body": {
          "text": "Tu pedido #123 llegó. ¿Todo salió bien?"
        },
        "footer": {
          "text": "Responde con un toque"
        },
        "action": {
          "buttons": [
            {
              "type": "reply",
              "reply": {
                "id": "sim",
                "title": "Sí"
              }
            },
            {
              "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": "Tu pedido"
    },
    "body": {
      "text": "Tu pedido #123 llegó. ¿Todo salió bien?"
    },
    "footer": {
      "text": "Responde con un toque"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "sim",
            "title": "Sí"
          }
        },
        {
          "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": "Tu pedido"
    },
    "body": {
      "text": "Tu pedido #123 llegó. ¿Todo salió bien?"
    },
    "footer": {
      "text": "Responde con un toque"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "sim",
            "title": "Sí"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "nao",
            "title": "Não"
          }
        }
      ]
    }
  }
}
```

| Campo | Regla |
|---|---|
| `interactive.body.text` | Obligatorio, de 1 a 1024 caracteres. |
| `interactive.header` | Opcional. `{ "type": "text", "text": "…" }` con hasta 60 caracteres. El tipo también puede ser `image`, `video` o `document`. |
| `interactive.footer.text` | Opcional, hasta 60 caracteres. |
| `interactive.action.buttons` | De 1 a 3 elementos `{ "type": "reply", "reply": { "id", "title" } }`. |
| `reply.id` | De 1 a 256 caracteres. Es lo que recibes de vuelta. |
| `reply.title` | De 1 a 20 caracteres. Es el texto del botón. |

## Botón con enlace (cta_url)

`interactive.type: "cta_url"` muestra un único botón que abre una URL. `header` y `footer` son opcionales, igual que en los botones de respuesta.

**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": "Sigue la entrega con el enlace."
        },
        "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": "Sigue la entrega con el enlace."
    },
    "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": "Sigue la entrega con el enlace."
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "Rastrear pedido",
        "url": "https://exemplo.com/pedido/123"
      }
    }
  }
}
```

`display_text` tiene de 1 a 20 caracteres y `url` es la página que abre.

## Recibir el toque

El toque llega como un evento [`message.received`](/es/webhooks/events/), con `data.message.content` de tipo `reply`:

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

`id` y `title` son los del botón tocado. Enlaza tu lógica al `id`, no al texto, que puedes cambiar.

## Instagram y Messenger

En estos canales usa `type: "buttons"`: un texto de 1 a 640 caracteres y de 1 a 3 botones. Cada botón es `postback` (`title` de 1 a 20 y `payload` de 1 a 1000 caracteres, devuelto cuando el contacto toca) o `web_url` (`title` de 1 a 20 y `url` con https). También se acepta `quick_replies`.

**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": "¿Cómo podemos ayudar?",
        "buttons": [
          {
            "type": "postback",
            "title": "Hablar con ventas",
            "payload": "vendas"
          },
          {
            "type": "web_url",
            "title": "Ver sitio",
            "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": "¿Cómo podemos ayudar?",
    "buttons": [
      {
        "type": "postback",
        "title": "Hablar con ventas",
        "payload": "vendas"
      },
      {
        "type": "web_url",
        "title": "Ver sitio",
        "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": "¿Cómo podemos ayudar?",
    "buttons": [
      {
        "type": "postback",
        "title": "Hablar con ventas",
        "payload": "vendas"
      },
      {
        "type": "web_url",
        "title": "Ver sitio",
        "url": "https://exemplo.com"
      }
    ]
  }
}
```

Para varias tarjetas con imagen, título y botones, usa `type: "cards"`: de 1 a 10 tarjetas, con `title` de hasta 80 caracteres y, si quieres, `subtitle`, `image_url`, `default_url` y `buttons`. Consulta [Tipos de mensaje](/es/connect/instagram/#tipos-de-mensaje).

## Otros tipos interactivos

- Flujos (Flows): [Flows](/es/guides/flows/).
- Catálogo, productos y pedido con Pix: [Ventas en WhatsApp](/es/guides/commerce/).
- Solicitud de permiso de llamada: [Llamadas](/es/guides/calls/).
- Lista de opciones: [Enviar lista](/es/send/list/).

## Errores comunes

- [`outside_service_window`](/es/errors#outside_service_window) (422): fuera de las 24 horas ([ventanas](/es/api/limits/#ventanas)). El fin de la ventana viene en `details[0].message`.
- [`type_not_supported_by_channel`](/es/errors#type_not_supported_by_channel) (422): el canal no acepta ese tipo. Por ejemplo, `interactive` en Instagram o Messenger, o `buttons` en WhatsApp.
- [`validation_failed`](/es/errors#validation_failed) (400): el cuerpo incumple las reglas, como más de 3 botones o un título por encima del límite.
