> ## Documentation Index
> Fetch the complete documentation index at: https://developers.datafyapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Enviar botões

> Envie um cartão com até três botões que permanecem na conversa.

O cartão fica **fixo na conversa** e os botões continuam clicáveis depois do primeiro toque. É a forma indicada para ofertas e menus que a pessoa pode consultar de novo.

Até **3** botões por cartão. Acima disso a Meta recusa:

```json theme={null}
{
  "error": {
    "message": "Limite de botões de modelos genéricos excedido. O número máximo de botões permitidos para modelos genéricos é 3",
    "code": 100,
    "error_subcode": 2018343
  }
}
```

## Tipos de botão

| Tipo | O que faz | Gera evento |
| - | - | - |
| `postback` | Devolve o `payload` para o seu webhook, sem tirar a pessoa do Instagram | Sim |
| `web_url` | Abre o endereço informado em `url` | Não |

Um clique em `web_url` não chega para a sua integração. Para medir o clique, use um link com parâmetros próprios ou um redirecionador.

> [!WARNING]
>
> Os campos `payload` e `url` são **exclusivos**. Um botão `postback` aceita apenas `payload`; um botão `web_url` aceita apenas `url`. Enviar os dois no mesmo botão é recusado:
>
> ```json theme={null}
> {
>   "error": {
>     "message": "Invalid message data for IG Generic templates",
>     "type": "IGApiException",
>     "code": 100,
>     "error_subcode": 2018340
>   }
> }
> ```

## Retorno no webhook

O clique em um `postback` chega como um evento **separado**, sem o campo `message`:

```json theme={null}
"postback": {
  "mid": "aWdfZAG1faXRlbTo...",
  "title": "Quero assinar",
  "payload": "ASSINAR_PRO"
}
```

Essa é a diferença prática em relação às [respostas rápidas](https://developers.datafyapi.com.br/api-reference/instagram/mensagens/enviar-respostas-rapidas.md), que chegam dentro de uma mensagem. Sua integração precisa tratar os dois caminhos para montar um fluxo encadeado.


## OpenAPI

````yaml api-reference/instagram/specs/botoes.json POST /ig/me/messages
openapi: 3.1.0
info:
  title: Datafy API — Enviar botões
  version: 1.0.0
servers:
  - url: https://cloud.datafyapi.com.br
    description: Produção
security:
  - bearerAuth: []
paths:
  /ig/me/messages:
    post:
      summary: Enviar botões
      operationId: igEnviarBotoes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - recipient
                - message
              properties:
                recipient:
                  type: object
                  required:
                    - id
                  description: Quem recebe a mensagem.
                  properties:
                    id:
                      type: string
                      description: IGSID do contato, recebido no webhook em `sender.id`.
                      example: '1000000000000001'
                message:
                  type: object
                  required:
                    - attachment
                  properties:
                    attachment:
                      type: object
                      required:
                        - type
                        - payload
                      properties:
                        type:
                          type: string
                          enum:
                            - template
                          default: template
                          description: Sempre `template`.
                        payload:
                          type: object
                          required:
                            - template_type
                            - elements
                          properties:
                            template_type:
                              type: string
                              enum:
                                - generic
                              default: generic
                              description: Sempre `generic`.
                            elements:
                              type: array
                              maxItems: 1
                              description: Um cartão.
                              items:
                                type: object
                                required:
                                  - title
                                properties:
                                  title:
                                    type: string
                                    description: Título do cartão.
                                    example: Plano Pro
                                  subtitle:
                                    type: string
                                    description: Linha de apoio, opcional.
                                    example: Tudo liberado
                                  image_url:
                                    type: string
                                    format: uri
                                    description: Imagem do cartão, opcional.
                                  buttons:
                                    type: array
                                    maxItems: 3
                                    description: >-
                                      Até 3 botões. Acima disso a Meta recusa
                                      com `code 100` e `error_subcode 2018343`.
                                    items:
                                      type: object
                                      required:
                                        - type
                                        - title
                                      properties:
                                        type:
                                          type: string
                                          enum:
                                            - postback
                                            - web_url
                                          description: >-
                                            `postback` devolve o payload no webhook.
                                            `web_url` abre um endereço e não gera
                                            evento.
                                        title:
                                          type: string
                                          maxLength: 20
                                          description: Texto do botão.
                                          example: Quero assinar
                                        payload:
                                          type: string
                                          description: >-
                                            Só para `postback`. Valor devolvido no
                                            webhook.
                                          example: ASSINAR_PRO
                                        url:
                                          type: string
                                          format: uri
                                          description: >-
                                            Só para `web_url`. Endereço aberto no
                                            clique.
            example:
              recipient:
                id: '1000000000000001'
              message:
                attachment:
                  type: template
                  payload:
                    template_type: generic
                    elements:
                      - title: Plano Pro
                        subtitle: Tudo liberado
                        buttons:
                          - type: postback
                            title: Quero assinar
                            payload: ASSINAR_PRO
                          - type: web_url
                            title: Ver site
                            url: https://exemplo.com
      responses:
        '200':
          description: Aceito pela Meta. Não confirma a entrega.
          content:
            application/json:
              example:
                recipient_id: '1000000000000001'
                message_id: aWdfZAG1faXRlbTo......
        '400':
          description: Erro retornado pela Meta.
          content:
            application/json:
              example:
                error:
                  message: Não foi possível encontrar o usuário solicitado.
                  type: IGApiException
                  code: 100
                  error_subcode: 2534014
                  fbtrace_id: AbCdEfGhIjK
        '401':
          description: Token ausente ou inválido.
          content:
            application/json:
              example:
                statusCode: 401
                message: Token inválido ou não encontrado.
        '402':
          description: Assinatura da Datafy inativa.
          content:
            application/json:
              example:
                statusCode: 402
                message: >-
                  Assinatura inativa (status: canceled). Ative sua assinatura no
                  painel para voltar a usar a API.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Token do canal do Instagram, gerado no painel da Datafy. Formato:
        `sk_live_xxx`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.