Documentação oficial

Triggers e Comandos

Os triggers são comandos estruturados que uma integração pode devolver ao Ticketz por mensagem ou resposta de webhook para executar ações no ticket atual.

Formato da mensagem

As mensagens usam a seguinte estrutura:

{
  "type": "text",
  "content": "texto da mensagem",
  "mediaUrl": "https://example.com/arquivo"
}
  • type pode ser text, image, video, audio, gif ou document.
  • content é usado para mensagens de texto.
  • mediaUrl é usado para mídias não textuais.
  • expandMustaches (opcional, booleano) — quando true, o content de uma mensagem de texto é processado pelo helper de mustache antes de ser enviado, permitindo interpolar campos do ticket (por exemplo Olá, ).

Formas de enviar comandos

1. Bolha de texto no Typebot

Integrações Typebot podem enviar um comando por vez em uma bolha de texto iniciando com # e seguida por um payload JSON.

#{
  "queueId": 99
}

2. Retorno de webhook

Integrações webhook podem responder com:

  • um comando isolado
  • uma mensagem com trigger opcional
  • um array de mensagens, cada uma com trigger opcional

Exemplo:

[
  {
    "type": "text",
    "content": "Uma mensagem"
  },
  {
    "type": "text",
    "content": "Outra mensagem",
    "trigger": { "action": "wait", "seconds": 2 }
  },
  {
    "type": "text",
    "content": "Uma mensagem com trigger",
    "trigger": { "closeTicket": true }
  }
]

3. Requisição HTTP direta para o backend

Typebot, Webhook ou qualquer sistema externo pode chamar o backend diretamente se possuir o token de autorização.

  • Endpoint: ${BACKEND_URL}/integrations/webhook
  • Método: POST
  • Cabeçalho: Authorization: Bearer ${token}

O payload pode seguir qualquer formato aceito no retorno por webhook.

Comandos disponíveis

Enviar mensagem

message pode ser um único objeto de mensagem ou um array de objetos.

{
  "message": {
    "type": "text",
    "content": "conteúdo da mensagem"
  }
}

Enviar mensagem com menu de opções

{
  "message": {
    "type": "text",
    "content": "Uma mensagem"
  },
  "action": "menu",
  "menuOptions": [{ "text": "Opção 1" }, { "text": "Opção 2" }]
}

Enviar mensagem com botão de URL

No momento isso depende de canais que suportam esse formato, como o Notificamehub WhatsApp Oficial.

{
  "message": {
    "type": "text",
    "content": "Clique no botão abaixo para conhecer mais"
  },
  "action": "menu",
  "menuOptions": [
    {
      "text": "Ticketz PRO",
      "url": "https://pro.ticke.tz"
    }
  ]
}

Transferir para outra fila

{
  "queueId": 99
}

Se a nova fila não for atendida por chatbot, o Ticketz também remove esse atributo.

Transferir para fila e usuário

{
  "queueId": 99,
  "userId": 42
}

O ticket é aceito automaticamente e aparece na aba de atendimento do novo usuário.

Encerrar a sessão da integração

{
  "action": "endSession"
}

Parar o chatbot

É equivalente a endSession e existe por compatibilidade com automações antigas.

{
  "stopbot": true
}

Encerrar o ticket atual

{
  "closeTicket": true
}

Adicionar anotação interna no ticket

{
  "action": "note",
  "message": {
    "content": "Texto da anotação"
  }
}

Atualizar várias propriedades do ticket

{
  "action": "updateTicket",
  "ticketData": {
    "status": "pending",
    "userId": 42,
    "queueId": 99,
    "justClose": false,
    "annotation": "Escalonado por automação"
  }
}

Campos aceitos em ticketData:

  • status: pending, open ou closed
  • userId: transfere para outro usuário
  • queueId: transfere para outra fila
  • justClose: fecha sem outras regras de transição
  • annotation: adiciona uma anotação ao transferir

Aguardar alguns segundos

Só faz efeito dentro de um array de comandos.

{
  "action": "wait",
  "seconds": 2
}

Ping

Faz o Ticketz responder automaticamente com pong, o que ajuda a preservar a ordem de processamento no Typebot.

{
  "action": "ping"
}

Enviar requisição para um webhook externo

Envia uma requisição POST para a url informada com os dados atuais do ticket (a mesma saída produzida pelo ShowTicketService) como corpo JSON. A resposta é interpretada como comandos e processada de forma aninhada, então o webhook pode responder com qualquer um dos comandos documentados aqui.

  • timeout (opcional, número) — tempo limite em segundos. O padrão é 5.
  • Erros ao chamar o webhook são registrados em log, mas não interrompem a execução.
  • Um postRequest aninhado dentro da resposta é permitido, mas a resposta dele não será processada. Isso limita a recursão a um nível, evitando cadeias infinitas de webhooks chamando uns aos outros.
{
  "action": "postRequest",
  "url": "https://example.com/hook",
  "timeout": 10
}

Adicionar tag no ticket

Se advanceOnly for verdadeiro, uma tag de funil não substitui outra tag do mesmo funil que já esteja mais avançada.

{
  "action": "addTag",
  "tagId": 99,
  "advanceOnly": true
}

Remover tag do ticket

{
  "action": "removeTag",
  "tagId": 99
}

Limpar todas as tags do ticket

{
  "action": "clearTags"
}

Adicionar tag no contato

{
  "action": "addContactTag",
  "tagId": 99,
  "advanceOnly": true
}

Remover tag do contato

{
  "action": "removeContactTag",
  "tagId": 99
}

Limpar todas as tags do contato

{
  "action": "clearContactTags"
}

Para exemplos prontos de payload, veja Arquivos de exemplo.