Componentes de Mensagem

Componentes de mensagem são os tipos que compõem o campo message de ResponseToUser. Permitem enviar texto simples, botões e listas interativas do WhatsApp.

Todos os componentes são subclasses de MessageComponent e são importados de:

from actions_sdk.core.types.message_components import (
    TextMessage,
    InteractiveReplyButtons, ReplyButton,
    InteractiveList, ListSection, ListRow,
    InteractiveCtaUrl,
    TextHeader, ImageHeader, DocumentHeader, VideoHeader,
)

---

TextMessage

Componente de texto simples. O mais comum nas actions.

from actions_sdk.core.types.message_components import TextMessage
from actions_sdk.core.types.responses import ResponseToUser

return ResponseToUser(
    message=TextMessage(body="Operação concluída com sucesso!"),
)

Campo	Tipo	Descrição
body	str	Texto da mensagem

---

InteractiveReplyButtons

Mensagem com até 3 botões de resposta rápida (WhatsApp).

from actions_sdk.core.types.message_components import InteractiveReplyButtons, ReplyButton
from actions_sdk.core.types.responses import ResponseToUser

return ResponseToUser(
    instruction="Action retornou mensagem com botões de opção.",
    message=InteractiveReplyButtons(
        body="Como posso te ajudar?",
        buttons=[
            ReplyButton(id="btn_0", title="Ver pedidos"),
            ReplyButton(id="btn_1", title="Falar com suporte"),
            ReplyButton(id="btn_2", title="Cancelar"),
        ],
    ),
)

Campos de InteractiveReplyButtons

Campo	Tipo	Obrigatório	Descrição
body	str	✅	Texto principal da mensagem
buttons	list[ReplyButton]	✅	Lista de botões (máximo 3)
header	ButtonHeaderUnion | None	Não	Cabeçalho (texto, imagem, documento ou vídeo)
footer	str | None	Não	Rodapé da mensagem

Campos de ReplyButton

Campo	Tipo	Restrição	Descrição
id	str	máx. 256 chars	Identificador único do botão
title	str	máx. 20 chars	Texto exibido no botão

Cabeçalhos

Os cabeçalhos são opcionais e permitem adicionar mídia acima do texto:

from actions_sdk.core.types.message_components import TextHeader, ImageHeader

# Cabeçalho de texto (máx. 60 chars)
header=TextHeader(text="Escolha uma opção")

# Cabeçalho de imagem
header=ImageHeader(link="https://exemplo.com/imagem.jpg")

# Cabeçalho de documento
header=DocumentHeader(link="https://exemplo.com/documento.pdf")

# Cabeçalho de vídeo
header=VideoHeader(link="https://exemplo.com/video.mp4")

---

InteractiveList

Mensagem com lista de opções (WhatsApp). Suporta múltiplas seções com vários itens.

from actions_sdk.core.types.message_components import (
    InteractiveList, ListSection, ListRow,
)
from actions_sdk.core.types.responses import ResponseToUser

return ResponseToUser(
    instruction="Action retornou lista de pedidos.",
    message=InteractiveList(
        body="Selecione um pedido:",
        button="Ver opções",
        sections=[
            ListSection(
                title="Pedidos recentes",
                rows=[
                    ListRow(id="pedido_001", title="Pedido #001", description="Tênis Nike - R$ 299"),
                    ListRow(id="pedido_002", title="Pedido #002", description="Camiseta - R$ 89"),
                ],
            )
        ],
    ),
)

Campos de InteractiveList

Campo	Tipo	Obrigatório	Descrição
body	str	✅	Texto principal da mensagem
button	str	✅	Texto do botão que abre a lista
sections	list[ListSection]	✅	Seções da lista
header	str | None	Não	Cabeçalho da mensagem
footer	str | None	Não	Rodapé da mensagem

Campos de ListSection

Campo	Tipo	Obrigatório	Descrição
rows	list[ListRow]	✅	Itens da seção
title	str | None	Não	Título da seção

Campos de ListRow

Campo	Tipo	Obrigatório	Descrição
id	str	✅	Identificador único do item
title	str	✅	Texto principal do item
description	str | None	Não	Descrição secundária do item

---

InteractiveCtaUrl

Mensagem com botão que abre uma URL externa (WhatsApp), sem callback de resposta. Referência oficial: CTA URL messages.

from actions_sdk.core.types.message_components import InteractiveCtaUrl
from actions_sdk.core.types.responses import ResponseToUser

return ResponseToUser(
    instruction="Action retornou link para agendamento.",
    message=InteractiveCtaUrl(
        body="Encontrei um horário disponível para você.",
        display_text="Agendar horário",
        url="https://exemplo.com/agendamento",
    ),
)

Campos de InteractiveCtaUrl

Campo	Tipo	Obrigatório	Restrição	Descrição
body	str	✅	máx. 1024 chars	Texto principal da mensagem
display_text	str	✅	máx. 20 chars	Rótulo exibido no botão
url	str	✅	máx. 2000 chars, esquema http/https	URL de destino aberta ao clicar no botão
header	ButtonHeaderUnion | None	Não	—	Cabeçalho (texto, imagem, documento ou vídeo)
footer	str | None	Não	máx. 60 chars	Rodapé da mensagem

O header aceita os mesmos tipos usados em InteractiveReplyButtons (TextHeader, ImageHeader, DocumentHeader, VideoHeader — ver Cabeçalhos).

---

Múltiplos componentes

ResponseToUser.message aceita uma lista de componentes. Todos são enviados sequencialmente:

return ResponseToUser(
    message=[
        TextMessage(body="Encontrei as seguintes opções para você:"),
        InteractiveList(
            body="Selecione:",
            button="Ver opções",
            sections=[ListSection(rows=[ListRow(id="opt_1", title="Opção A")])],
        ),
    ]
)

---

Erros e Exceções

Situação	Comportamento
ReplyButton.title com mais de 20 chars	ValidationError do Pydantic
TextHeader.text com mais de 60 chars	ValidationError do Pydantic
Mais de 3 botões em InteractiveReplyButtons	Aceito pelo modelo, mas o WhatsApp rejeita — limite no código da action
InteractiveCtaUrl.display_text com mais de 20 chars	ValidationError do Pydantic
InteractiveCtaUrl.body com mais de 1024 chars ou footer com mais de 60 chars	ValidationError do Pydantic
InteractiveCtaUrl.url com esquema diferente de http/https ou mais de 2000 chars	ValidationError do Pydantic