# Respostas ricas e ações do agente de IA > Faça o agente de IA mandar imagem, botões e carrossel e executar ações: o que marcar no AI Hub, o que escrever no prompt e o formato JSON de mensagens e ações. Endereço: https://docs.nextags.com.br/ia/respostas-do-agente-em-json/ Tipo: Guia Atualizado em: 26/10/2026 Por padrão, o agente de IA responde só com texto. Para ele mandar imagem, vídeo, áudio, arquivo, texto com botões e carrossel, e para executar ações, como aplicar uma etiqueta ou passar a conversa para a equipe, o editor do agente tem dois ajustes: o **Tipo de resposta da IA** e as **Ações de IA**. A NexTags converte as respostas para o canal do contato. Este guia mostra o que configurar e o que escrever no prompt. No fim, está o formato JSON de mensagens e ações que a central antiga ensinava a pedir no prompt, com o que mudou. **Antes de começar** - Um agente de IA criado no **AI Hub**. Veja [Criar um agente de IA](https://help.nextags.com.br/tutoriais/ia/criar-agente/). - Para mandar mídia: cada arquivo publicado num endereço `https://` que abre o arquivo direto, sem login. - Os fluxos, as etiquetas e os campos personalizados que as ações vão usar. ## Passo a passo ### Passo 1: Marque os formatos em Tipo de resposta da IA No menu **AI Hub**, na aba **Agentes de IA**, clique no agente. No editor, clique no ícone de ajustes, à direita de **Mensagem do sistema**, e marque os formatos em **Tipo de resposta da IA**. Dá para marcar mais de um; um agente novo vem só com **Texto**. ```text Tipo de resposta da IA: Texto Imagem | Vídeo | Áudio | Arquivo Texto + Botões Carrossel ``` O ⓘ do campo avisa: a IA envia imagens, vídeos, áudios e arquivos quando os links deles estão no prompt. Clique em **Salvar**, no topo da tela. O passo a passo de tela está em [Tipos de resposta: texto, mídia, botões e carrossel](https://help.nextags.com.br/tutoriais/ia/respostas-elaboradas/). ### Passo 2: Diga no prompt quando usar cada formato Na **Mensagem do sistema**, liste as mídias que o agente pode mandar, cada uma com o link, e diga quando usar cada formato. Não é preciso pedir JSON nem descrever o formato técnico: a NexTags faz a conversão a partir do **Tipo de resposta da IA**. ```text ENVIO DE MÍDIA, BOTÕES E CARROSSEL - Quando o cliente pedir o cardápio, envie o PDF como arquivo: https://seusistema.exemplo.com.br/cardapio.pdf - Fotos de produto: envie como imagem, com a legenda "Nome – tamanho – preço". - Para mostrar de 2 a 10 produtos de uma vez, use o carrossel, um cartão por produto. - Para escolhas fechadas, como Retirada ou Entrega, use texto com até 3 botões de títulos curtos. - Nas outras respostas, use só texto. ``` Os limites do formato valem também aqui: até 3 botões por mensagem, com títulos de até 20 caracteres, e até 10 cartões num carrossel. Como escrever o resto do prompt: [Escrever a mensagem do sistema (prompt)](https://help.nextags.com.br/tutoriais/ia/escrever-o-prompt/). ### Passo 3: Configure as ações em Ações de IA No cartão **Ações de IA**, clique em **+ Adicionar regra**. Em **Quando**, descreva a situação da conversa; em **O que a IA deve fazer?**, escolha as ações, na ordem, com **+ Adicionar ação** para cada uma. Uma regra de transferência, por exemplo: ```text Quando: O cliente aprovou o resumo do pedido e o agente respondeu "Seu pedido foi pré-confirmado e já passei para a nossa equipe". Não vale se o cliente só pediu o resumo ou pediu uma mudança. Ação 1: Adicionar Etiqueta → Pedido pré-confirmado Ação 2: Definir Campo Personalizado → resumo_pedido (Da conversa) Ação 3: Transferir conversa para humano Ação 4: Atribuir conversa a um administrador → quem atende os pedidos ``` As ações disponíveis: **Enviar Fluxo**, **Atribuir conversa a um administrador**, **Remover atribuição**, **Transferir conversa para humano**, **Adicionar Etiqueta**, **Remover Etiqueta**, **Definir Campo Personalizado**, **Limpar Campo Personalizado**, **Seguir**, **Remover do acompanhamento**, **Transferir conversa para bot**, **Arquivar** e **Bloquear contato**. Com pelo menos uma regra, o ícone de ajustes do cartão abre o **Prompt da ação**: instruções que valem para todas as regras e que a NexTags junta ao prompt principal. Veja [Ações de IA: o agente que envia fluxos, etiqueta e transfere](https://help.nextags.com.br/tutoriais/ia/acoes-do-agente/). ### Passo 4: Teste o agente No AI Hub, abra o menu ⋮ do agente e clique em **Testar Agora**: o chat de teste abre numa nova aba. A opção aparece só no agente padrão; veja [Agente padrão e resposta automática por IA](https://help.nextags.com.br/tutoriais/ia/agente-padrao/). Faça as perguntas que levam a cada formato e a cada regra: ```text "Me manda o cardápio" → o PDF chega como arquivo "Quais sabores vocês têm?" → um carrossel com as fotos "Quero retirar na loja" → texto com botões "Pode confirmar o pedido" → a etiqueta, o campo e a transferência para a equipe ``` Ajuste o prompt e as regras e teste de novo. Veja [Testar e ajustar o agente](https://help.nextags.com.br/tutoriais/ia/testar-agente/). ## O formato JSON de mensagens e ações A NexTags usa um mesmo formato JSON para mensagens e ações em vários lugares: na API ([Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/)), na resposta da requisição externa (o conteúdo dinâmico) e no agente de IA que responde em JSON, como a central antiga ensinava. O formato completo está em [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). Em resumo: - `messages`: a lista das mensagens, na ordem. Cada item é um objeto com a chave `message`, no formato de mensagens do Messenger, e a NexTags converte para o canal do contato. Alguns formatos não existem em todos os canais. - Um número sozinho entre duas mensagens mostra "digitando" por esse número de segundos. - `actions`: a lista das ações, executadas na ordem. ### O que mudou A central antiga da NexTags ensinava a pôr no fim da **Mensagem do sistema** um trecho que pedia ao agente respostas nesse JSON. Hoje, o **Tipo de resposta da IA** e as **Ações de IA** fazem esse trabalho pela tela, e a skill oficial da NexTags para o Claude Code orienta não pedir JSON no prompt. Para um agente novo, use os passos acima. > **Se o seu agente ainda usa o trecho antigo:** > Teste antes de mudar qualquer coisa: abra o **Testar Agora** e confira se as mensagens chegam como imagem, botões e carrossel, e não como texto com chaves e aspas. Ao migrar, marque os formatos em **Tipo de resposta da IA**, crie as regras em **Ações de IA** e só depois tire o trecho do prompt. O trecho da central antiga, revisado: ```text Responda sempre com um JSON válido, no formato de mensagens do Messenger. Regras: 1. O JSON tem a lista "messages", a lista "actions" ou as duas. 2. "messages" é uma lista de objetos, e cada objeto tem a chave "message". 3. O objeto "message" segue o formato de mensagens do Messenger. 4. Tipos de mensagem aceitos: texto, texto com botões, imagem, vídeo, áudio, arquivo e carrossel (template do tipo "generic"). 5. Responda só com o JSON: sem explicações, sem Markdown e sem texto antes ou depois. ``` ### Exemplos Várias mensagens: ```json { "messages": [ { "message": { "text": "Olá, Ana!" } }, { "message": { "text": "Esta é a segunda mensagem." } } ] } ``` Uma imagem. Para vídeo, áudio e arquivo, troque `"image"` por `"video"`, `"audio"` ou `"file"`: ```json { "messages": [ { "message": { "attachment": { "type": "image", "payload": { "url": "https://seusistema.exemplo.com.br/fotos/bolo.jpg" } } } } ] } ``` Um carrossel com dois cartões (até 10). `image_aspect_ratio` aceita `horizontal` ou `square`: ```json { "messages": [ { "message": { "attachment": { "type": "template", "payload": { "template_type": "generic", "image_aspect_ratio": "horizontal", "elements": [ { "title": "Bolo de chocolate", "subtitle": "Fatia: R$ 12,00", "image_url": "https://seusistema.exemplo.com.br/fotos/bolo.jpg", "buttons": [] }, { "title": "Torta de limão", "subtitle": "Fatia: R$ 10,00", "image_url": "https://seusistema.exemplo.com.br/fotos/torta.jpg", "buttons": [] } ] } } } } ] } ``` Texto com dois botões: um abre um link e o outro manda o fluxo `1000001` (o `payload` do botão é o ID do fluxo): ```json { "messages": [ { "message": { "attachment": { "type": "template", "payload": { "template_type": "button", "text": "Como você quer continuar?", "buttons": [ { "type": "web_url", "title": "Ver o cardápio", "url": "https://seusistema.exemplo.com.br/cardapio" }, { "type": "postback", "title": "Fazer um pedido", "payload": "1000001" } ] } } } } ] } ``` Uma pausa de 4 segundos, com "digitando", entre duas mensagens: ```json { "messages": [ { "message": { "text": "Vou conferir para você." } }, 4, { "message": { "text": "Pronto: o seu pedido está a caminho." } } ] } ``` Mensagens e ações juntas: ```json { "messages": [ { "message": { "text": "Anotado! Já passei o seu pedido para a equipe." } } ], "actions": [ { "action": "add_tag", "tag_name": "lead" }, { "action": "set_field_value", "field_name": "Valor do pedido", "value": "89" }, { "action": "send_flow", "flow_id": "1000001" } ] } ``` ### As ações | Ação | JSON | |---|---| | Adicionar uma etiqueta | `{"action": "add_tag", "tag_name": ""}` | | Remover uma etiqueta | `{"action": "remove_tag", "tag_name": ""}` | | Preencher um campo personalizado | `{"action": "set_field_value", "field_name": "", "value": ""}` | | Limpar um campo personalizado | `{"action": "unset_field_value", "field_name": ""}` | | Mandar um fluxo | `{"action": "send_flow", "flow_id": ""}` | | Passar a conversa para a equipe | `{"action": "transfer_conversation_to", "value": "human"}` | | Devolver a conversa ao robô | `{"action": "transfer_conversation_to", "value": "bot"}` | | Atribuir a conversa a um administrador | `{"action": "assign_conversation", "admin_id": ""}` | | Remover a atribuição | `{"action": "unassign_conversation"}` | O `set_field_value` também preenche os campos do sistema `phone`, `email`, `full_name`, `first_name` e `last_name`. Onde achar o ID de um fluxo e de um administrador: [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). ## Pronto: como conferir - No **Testar Agora**, a mídia chega como arquivo, e não como link; o carrossel e os botões aparecem como cartões e botões. - Depois de uma regra disparar, a etiqueta, o campo e o responsável aparecem no painel do contato, na **Caixa de Entrada**. ## Se não funcionou ### O agente mandou o link em vez da mídia Confira se **Imagem | Vídeo | Áudio | Arquivo** está marcado em **Tipo de resposta da IA** e se você clicou em **Salvar**. Abra o link numa janela anônima: ele precisa abrir o arquivo, sem login. ### O contato recebeu um texto com chaves e aspas O agente escreveu o JSON como texto. Marque os formatos em **Tipo de resposta da IA**, use as **Ações de IA** para as ações e tire do prompt o trecho que pede JSON. ### A regra de Ações de IA não disparou Escreva o **Quando** com o que aparece na conversa, como a frase fixa que o agente manda, e uma situação só por regra. Veja [Ações de IA: o agente que envia fluxos, etiqueta e transfere](https://help.nextags.com.br/tutoriais/ia/acoes-do-agente/). ### O botão não abriu o fluxo O `payload` de um botão é o ID do fluxo, como texto. Confira o ID em [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). ### Faça com a IA Cole este pedido no ChatGPT ou no Claude: ```text Configuro um agente de IA na NexTags. Leia este guia: https://docs.nextags.com.br/ia/respostas-do-agente-em-json.md Meu negócio: [descreva]. Minhas mídias: [liste cada arquivo com o link]. Os fluxos, etiquetas e campos que já tenho: [liste]. Escreva o trecho da Mensagem do sistema que diz quando usar texto, mídia, botões e carrossel, as regras de Ações de IA (o Quando e as ações de cada uma) e um Prompt da ação curto. Não peça JSON no prompt. ``` > **O agente pela API:** > A API consulta e atualiza os agentes de IA. Veja [Agentes de IA pela API](https://docs.nextags.com.br/guias/agentes-de-ia-pela-api/).