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,
    InteractiveRequestContactInfo,
    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).

InteractiveRequestContactInfo

Solicita ao usuário o compartilhamento do contato (nome + telefone) via WhatsApp — usado quando a conversa chega identificada apenas por um BSUID (business-scoped user id), sem o número de telefone real exposto. Referência oficial: Webhook reference — messages/contacts.

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

return ResponseToUser(
    instruction="Action solicitou o contato do usuário.",
    message=InteractiveRequestContactInfo(
        body="Para continuar, preciso que você compartilhe seu contato",
    ),
)

Campos de InteractiveRequestContactInfo

Campo	Tipo	Obrigatório	Restrição	Descrição
`body`	`str`	✅	máx. 1024 chars	Texto principal da mensagem

Diferente de InteractiveCtaUrl, não aceita header/footer — a Meta não documenta esses campos para este tipo.

O disparo do componente não é automático: fica a critério da action/agente decidir quando solicitar o contato (ex.: ao detectar ausência de phone_number na sessão).

Resposta do usuário

Quando o usuário compartilha o contato, o WhatsApp envia uma mensagem contacts (diferente do payload interactive usado pelos demais componentes desta página). O t4ai-agents processa esse retorno, filtra por origin == "contact_request" e grava o telefone (contacts[0].phones[0].phone, com fallback para wa_id) como string em session.state["contact_info"] — compatível com a config external_identifier_key do agente, caso configurada.

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
`InteractiveRequestContactInfo.body` com mais de 1024 chars	`ValidationError` do Pydantic

TextMessage​

InteractiveReplyButtons​

Campos de InteractiveReplyButtons​

Campos de ReplyButton​

Cabeçalhos​

InteractiveList​

Campos de InteractiveList​

Campos de ListSection​

Campos de ListRow​

InteractiveCtaUrl​

Campos de InteractiveCtaUrl​

InteractiveRequestContactInfo​

Campos de InteractiveRequestContactInfo​

Resposta do usuário​

Múltiplos componentes​

Erros e Exceções​