# Mensagens e ações em JSON > O formato JSON de mensagens e ações da NexTags (texto, botões, respostas rápidas, mídia, cartões, galeria e as 8 ações), com os limites e onde ele vale. Endereço: https://docs.nextags.com.br/comecar/mensagens-e-acoes/ Tipo: Referência Atualizado em: 26/10/2026 A NexTags usa um formato só para mensagens e ações em JSON. Você escreve a mensagem uma vez, no formato de mensagens do Messenger, e a NexTags converte para o canal do contato. Para o WhatsApp, dá também para mandar mensagens no formato da API do WhatsApp. As ações rodam no contato: põem etiquetas, preenchem campos, enviam fluxos e passam a conversa para a equipe. ## Onde o formato vale | Onde | O que vai | |---|---| | [Criar contato](https://docs.nextags.com.br/referencia/contatos/criar-contato/), `POST /contacts` | `actions` | | [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/), `POST /contacts/{contact_id}/send_content` | `messages` e `actions` | | A resposta do seu sistema a uma [requisição externa no fluxo](https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/) | `messages` e `actions` | | A resposta de um [agente de IA em JSON](https://docs.nextags.com.br/ia/respostas-do-agente-em-json/) | `messages` e `actions` | O corpo tem duas listas, e as duas podem ir vazias: ```json { "messages": [], "actions": [] } ``` ## Mensagens Cada mensagem da lista `messages` é um objeto com `message` dentro, e elas saem na ordem da lista. As exceções são a pausa de "digitando" e a mensagem só do WhatsApp, mais abaixo. ### Texto ```json { "messages": [ {"message": {"text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega."}}, {"message": {"text": "Qualquer dúvida, é só responder aqui."}} ] } ``` ### Pausa de "digitando" Um número solto entre duas mensagens mostra o "digitando" por esse tanto de segundos. Este formato aparece nas respostas do agente de IA; nos outros lugares, confira no seu teste. ```json { "messages": [ {"message": {"text": "Oi, Ana!"}}, 3, {"message": {"text": "Seu pedido PED-1001 saiu para entrega."}} ] } ``` ### Texto com botões Até 3 botões, com título de até 20 caracteres. Cada botão tem um tipo: | `type` | O que faz | Campo | |---|---|---| | `web_url` | Abre um site | `url` | | `postback` | Envia um fluxo ou uma etapa | `payload` com o ID do fluxo ou da etapa, ou ações (abaixo) | | `phone_number` | Liga para um número | `payload` com o telefone e o código do país | ```json { "messages": [ { "message": { "attachment": { "type": "template", "payload": { "template_type": "button", "text": "Seu boleto está pronto. Como prefere seguir?", "buttons": [ { "type": "web_url", "title": "Abrir o boleto", "url": "https://seusistema.exemplo.com.br/boleto/PED-1001" }, {"type": "postback", "title": "Falar com a equipe", "payload": "1000001"}, {"type": "phone_number", "title": "Ligar para a loja", "payload": "+551133445566"} ] } } } } ] } ``` ### Respostas rápidas Até 11 respostas rápidas, em qualquer tipo de mensagem. O `payload` funciona como o do botão. ```json { "messages": [ { "message": { "text": "Qual sabor você prefere?", "quick_replies": [ {"content_type": "text", "title": "Chocolate", "payload": "1000001"}, {"content_type": "text", "title": "Morango", "payload": "1000002"} ] } } ] } ``` ### Imagem, vídeo, áudio e arquivo O `type` é `image`, `video`, `audio` ou `file`, e o `url` aponta para o arquivo, num endereço público (sem login). Os tamanhos que cada canal aceita estão em [Tipos de arquivo e limites por canal](https://help.nextags.com.br/tutoriais/canais/tipos-de-arquivo-e-limites/). ```json { "messages": [ { "message": { "attachment": { "type": "image", "payload": {"url": "https://seusistema.exemplo.com.br/img/bolo-de-chocolate.jpg"} } } } ] } ``` ### Cartão Título e subtítulo com até 80 caracteres cada, imagem e até 3 botões. O `image_aspect_ratio` é `horizontal` ou `square`. ```json { "messages": [ { "message": { "attachment": { "type": "template", "payload": { "template_type": "generic", "image_aspect_ratio": "horizontal", "elements": [ { "title": "Bolo de chocolate", "subtitle": "R$ 89,90 · serve 12 pessoas", "image_url": "https://seusistema.exemplo.com.br/img/bolo-de-chocolate.jpg", "buttons": [ {"type": "postback", "title": "Quero este", "payload": "1000001"} ] } ] } } } } ] } ``` ### Galeria A galeria é um cartão com vários `elements`, até 10. ```json { "messages": [ { "message": { "attachment": { "type": "template", "payload": { "template_type": "generic", "image_aspect_ratio": "square", "elements": [ { "title": "Bolo de chocolate", "subtitle": "R$ 89,90", "image_url": "https://seusistema.exemplo.com.br/img/chocolate.jpg", "buttons": [] }, { "title": "Bolo de morango", "subtitle": "R$ 94,90", "image_url": "https://seusistema.exemplo.com.br/img/morango.jpg", "buttons": [] } ] } } } } ] } ``` ### Mensagem só do WhatsApp Para o que só o WhatsApp tem, como lista de opções, contatos, localização e catálogo, mande o objeto no formato da API do WhatsApp (Cloud API), com `"to": null`: a NexTags preenche o destinatário. No `id` de cada botão vai o ID do fluxo ou da etapa. Os formatos de cada tipo estão na documentação da Meta, como a de [botões de resposta](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-reply-buttons-messages) e a de [listas](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-list-messages). ```json { "messages": [ { "messaging_product": "whatsapp", "recipient_type": "individual", "to": null, "type": "interactive", "interactive": { "type": "button", "body": {"text": "Confirma a entrega para amanhã?"}, "action": { "buttons": [ {"type": "reply", "reply": {"id": "1000001", "title": "Confirmo"}}, {"type": "reply", "reply": {"id": "1000002", "title": "Outro dia"}} ] } } } ] } ``` ## Limites | Item | Limite | |---|---| | Botões num texto | 3 | | Título do botão | 20 caracteres | | Respostas rápidas numa mensagem | 11 | | Título e subtítulo do cartão | 80 caracteres cada | | Botões num cartão | 3 | | Cartões numa galeria | 10 | ## Botões e cartões em cada canal No editor de fluxo, numa mensagem para todos os canais, a NexTags tira da lista de quem recebe os canais que não aceitam o conteúdo: | Conteúdo | Não vai para | |---|---| | Cartão ou galeria | Telegram e TikTok | | Galeria com mais de um cartão | WhatsApp | | Botão que liga (`phone_number`) | WhatsApp | | Mais de um botão, quando um deles abre site (`web_url`) | WhatsApp | | Arquivo ou áudio | TikTok | No JSON, a conversão acontece na hora do envio, e o resultado de cada caso não foi conferido. Teste no canal de verdade antes de usar com clientes. As regras de cada conteúdo nos fluxos estão em [Texto, botões e respostas rápidas](https://help.nextags.com.br/tutoriais/fluxos/texto-e-botoes/) e [Cartão e carrossel](https://help.nextags.com.br/tutoriais/fluxos/cartoes-e-galeria/). ## Ações | Ação | O que faz | JSON | |---|---|---| | `add_tag` | Põe uma etiqueta, pelo nome | `{"action": "add_tag", "tag_name": "cliente-vip"}` | | `remove_tag` | Tira uma etiqueta, pelo nome | `{"action": "remove_tag", "tag_name": "cliente-vip"}` | | `set_field_value` | Preenche um campo, pelo nome. Vale também para `phone`, `email`, `full_name`, `first_name` e `last_name` | `{"action": "set_field_value", "field_name": "cidade", "value": "São Paulo"}` | | `unset_field_value` | Limpa um campo, pelo nome | `{"action": "unset_field_value", "field_name": "cidade"}` | | `send_flow` | Envia um fluxo | `{"action": "send_flow", "flow_id": 1000001}` | | `transfer_conversation_to` | Passa a conversa para a equipe (`human`) ou de volta para o robô (`bot`) | `{"action": "transfer_conversation_to", "value": "human"}` | | `assign_conversation` | Atribui a conversa a um administrador | `{"action": "assign_conversation", "admin_id": 10001}` | | `unassign_conversation` | Tira a atribuição da conversa | `{"action": "unassign_conversation"}` | Várias ações vão juntas na mesma lista. Ponha na ordem em que fazem sentido, como preencher o campo antes de enviar o fluxo que usa o campo, e confira o resultado no primeiro teste: ```json { "messages": [{"message": {"text": "Recebemos o seu pagamento. Obrigado, Ana!"}}], "actions": [ {"action": "add_tag", "tag_name": "cliente-vip"}, {"action": "set_field_value", "field_name": "cidade", "value": "São Paulo"}, {"action": "send_flow", "flow_id": 1000001} ] } ``` O ID do fluxo e do administrador: [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/). Os campos e o formato de cada valor: [Campos personalizados, campos do bot e variáveis](https://docs.nextags.com.br/comecar/campos-e-variaveis/). ### Ações num botão O `payload` de um botão ou de uma resposta rápida pode levar ações no lugar do ID do fluxo. Como o `payload` é texto, as ações vão como JSON dentro do texto, com as aspas escapadas: ```json { "type": "postback", "title": "Quero o desconto", "payload": "{\"actions\":[{\"action\":\"add_tag\",\"tag_name\":\"cliente-vip\"},{\"action\":\"send_flow\",\"flow_id\":1000001}]}" } ``` Monte esse texto com a função de JSON da sua linguagem, em vez de escapar à mão: **Montar o payload com ações** ```javascript const payload = JSON.stringify({ actions: [ { action: 'add_tag', tag_name: 'cliente-vip' }, { action: 'send_flow', flow_id: 1000001 }, ], }); const botao = { type: 'postback', title: 'Quero o desconto', payload }; ``` ```python import json payload = json.dumps({ "actions": [ {"action": "add_tag", "tag_name": "cliente-vip"}, {"action": "send_flow", "flow_id": 1000001}, ], }) botao = {"type": "postback", "title": "Quero o desconto", "payload": payload} ``` ```php [ ['action' => 'add_tag', 'tag_name' => 'cliente-vip'], ['action' => 'send_flow', 'flow_id' => 1000001], ], ]); $botao = ['type' => 'postback', 'title' => 'Quero o desconto', 'payload' => $payload]; ``` ## A janela de 24 horas No WhatsApp, mensagem livre (texto, mídia, botões, cartões e as mensagens só do WhatsApp) só sai até 24 horas depois da última mensagem do contato. Fora dessa janela, só sai um Modelo de Mensagem aprovado pela Meta, e pela API isso se faz por um fluxo que comece com o modelo, enviado com [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/). - A regra vale para tudo o que sai do número: a API, os fluxos, a **Caixa de Entrada** e os Broadcasts. - No Instagram e no Messenger, a Meta dá 24 horas para mensagens automáticas; os 7 dias valem só para a resposta da equipe pela **Caixa de Entrada**. Veja [Mensagens fora da janela no Instagram e no Messenger](https://help.nextags.com.br/tutoriais/instagram-e-facebook/mensagens-fora-da-janela/). - A ação `send_flow` envia mensagens e segue a mesma regra: fora da janela, o fluxo precisa começar com o modelo. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/), [Criar um modelo e enviar para aprovação](https://help.nextags.com.br/tutoriais/disparos/criar-modelo/) e [Modelo de mensagem do WhatsApp no fluxo](https://help.nextags.com.br/tutoriais/fluxos/modelos-no-fluxo/).