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.

Referência8 min

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, `POST /contacts`	`actions`
Enviar conteúdo, `POST /contacts/{contact_id}/send_content`	`messages` e `actions`
A resposta do seu sistema a uma requisição externa no fluxo	`messages` e `actions`
A resposta de um agente de IA em JSON	`messages` e `actions`

O corpo tem duas listas, e as duas podem ir vazias:

{
  "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

{
  "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.

{
  "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

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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 e a de listas.

{
  "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 e Cartão e carrossel.

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:

{
  "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. Os campos e o formato de cada valor: Campos personalizados, campos do bot e variáveis.

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:

{
  "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

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 };

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
$payload = json_encode([
    'actions' => [
        ['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.

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.
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, Criar um modelo e enviar para aprovação e Modelo de mensagem do WhatsApp no fluxo.

Obrigado! Sua resposta ajuda a melhorar a central.