As Ações de código são scripts de JavaScript que o bot executa dentro de uma conversa. São a alternativa recomendada para adicionar lógica arbitrária ou para conectar serviços externos e obter informações relevantes em tempo real. Cada Ação de código recebe o contexto do usuário (identidade, mensagem recebida, variáveis) e determina a resposta que será gerada.

Você pode:

• Validar dados do usuário (CPF, etc.) antes de avançar no fluxo.
• Integrar serviços externos via REST ou SOAP e salvar as informações em variáveis.
• Gerar mensagens interativas: botões, quick replies e carrosséis de produtos.
• Persistir o estado do contato entre execuções com user e db.
• Diagnosticar o comportamento em produção por meio de logs etiquetados.

Pré-requisitos

Acesso à sua conta da Botmaker com permissões para desenvolver na seção Código.

Conhecimentos básicos de JavaScript: variáveis, funções, async/await e chamadas HTTP. Não é necessária experiência prévia com a Botmaker.

A plataforma suporta Node.js v22. Se você precisar de uma biblioteca que não esteja disponível, escreva para architecture@botmaker.com e nossa equipe avaliará a solicitação.

Conceitos-chave

Ação de código: script de JavaScript que o bot executa ao alcançar uma regra do fluxo.

context: objeto somente leitura com as informações da conversa (dados do contato, mensagem recebida e parâmetros de um botão).

result: objeto com o qual você define a resposta ao usuário (texto, imagem, botões, etc.). Toda execução deve terminar com result.done().

user: permite ler e escrever variáveis do contato, que persistem entre execuções.

db: banco de dados chave-valor do business, compartilhado entre todos os chats.

rp (request-promise): cliente HTTP recomendado para chamar serviços externos.

bmconsole: ferramenta de logging que etiqueta os logs no painel de Eventos do editor.

Nota: cada execução tem um limite de 90 segundos. Além disso, cada execução é independente e não compartilha memória com as seguintes: as informações que você quiser conservar devem ser salvas com user ou db.

Como criar e disparar uma Ação de código

Passo 1: Acesse a seção Código

No menu lateral esquerdo, procure a palavra Código e clique. Você será redirecionado para a tela de Ações de código.

[ IMAGEN ]

Legenda: captura do menu lateral com a opção "Código" destacada.

[ IMAGEN ]

Legenda: tela principal de "Ações de código" com a lista de ações existentes.

Passo 2: Crie uma nova ação

Clique em Criar nova ação de código. Atribua um nome à ação (não se esqueça), escolha a versão do Node.js e o tipo de ação. Você pode partir de um modelo de código para impulsionar seu desenvolvimento.

[ IMAGEN ]

Legenda: modal de criação mostrando os campos de nome, versão do Node.js e tipo de ação.

Passo 3: Publique a ação

Quando terminar de escrever o código, clique em Publicar para que a ação fique disponível para uso.

[ IMAGEN ]

Legenda: editor de código com o botão "Publicar" destacado.

Passo 4: Use a ação dentro de um bot

Vá até o Botdesigner. Na interseção de um fluxo, clique no botão Mais e selecione Ação. Depois clique em Ações de Código: você poderá escolher entre Ações de código e Ações de código com parâmetros, e selecionar qualquer uma das que tiver publicado.

[ IMAGEN ]

Legenda: menu de blocos do Botdesigner com "Ações de Código" destacado.

Como escrever sua primeira Ação de código

Passo 1: Teste um "Olá, mundo"

Crie uma Ação de código no editor, insira o código a seguir e teste-o no simulador:

result.text('Olá, mundo!');

result.done();

result.text(...) define uma mensagem de texto e result.done() finaliza a execução e dispara o envio ao usuário.

Para ler o nome do contato:

const nome = context.userData.FIRST_NAME || 'amigo';

result.text(`Olá, ${nome}!`);

result.done();

Passo 2: Adote o modelo recomendado

A partir daqui, é recomendável usar este modelo em todas as suas Ações de código. Isole a lógica em uma função main, capture os erros e garanta o encerramento da execução:

// ====== CONSTANTS ======

const CA_NAME = 'minha-acao-de-codigo';

// ====== HELPERS ======

// (funções auxiliares, se aplicável)

// ====== MAIN ======

const main = async () => {

  // lógica principal

};

main()

  .catch(err => {

    const errorMessage = `[${CA_NAME}] Error - ${err.message}`;

    user.set('ca_error', errorMessage);

    bmconsole.log(errorMessage);

  })

  .finally(() => result.done());

• async main() permite usar await em qualquer chamada e isola a lógica principal.
• .catch(err => ...) captura exceções e evita que um erro interrompa a resposta do bot. O último erro fica salvo em ca_error para ser visto pelo chat.
• .finally(() => result.done()) garante o encerramento da execução em qualquer cenário. Sem essa chamada, o bot não envia resposta ao usuário.

Como responder ao usuário

Estes são os métodos de result disponíveis para responder:

• result.text(texto) — mensagem de texto.
• result.image(url, caption) — imagem com caption opcional.
• result.video(url) — vídeo.
• result.audio(url) — áudio.
• result.file(url, caption) — arquivo (PDF, Excel, etc.).
• result.fileFromBuffer(buffer, mimeType, fileName) — arquivo gerado dinamicamente.
• result.gotoRule('nome da regra') — redireciona o fluxo para outra regra.

Você pode encadear várias mensagens em uma mesma execução:

// ====== CONSTANTS ======

const CA_NAME = 'enviar-fatura';

const URL_FATURA = 'https://meudominio.com/faturas/123.pdf';

// ====== MAIN ======

const main = async () => {

  result.text('A seguir, sua fatura:');

  result.file(URL_FATURA, 'fatura.pdf');

  result.text('Em caso de dúvidas, escreva.');

};

main()

  .catch(err => {

    user.set('ca_error', `[${CA_NAME}] ${err.message}`);

    bmconsole.log(err.message);

  })

  .finally(() => result.done());