# Criar gatilho

POST /chatbot/triggers

Define quando a automação responde. A cada mensagem do contato, vale o gatilho ativo de maior `priority` cujas condições batem (`keywords`, `lead_filters`, `ignore_groups`). Com `type: agent`, o agente responde, e as mensagens que chegam durante `response_delay_seconds` entram na mesma resposta. Depois disso, cada mensagem nova passa pelos gatilhos de novo.

Nenhum gatilho aciona quando:

- a automação está desligada em `PATCH /chatbot/settings`;
- o chat está pausado (`stop_keyword`, resposta à mão ou `chamar_humano`) ou tem um fluxo esperando resposta;
- a mensagem tem mais de 10 minutos (chegou depois de uma reconexão).

## Autenticação

```json
[
  {
    "token": []
  }
]
```

```json
{
  "token": {
    "name": "token",
    "type": "apiKey",
    "in": "header"
  }
}
```

## Corpo da requisição

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AITriggerCreate"
      },
      "example": {
        "type": "agent",
        "agent_id": "r1a2b3c4d5e6f7",
        "keywords": [],
        "ignore_groups": true,
        "response_delay_seconds": 10
      }
    }
  }
}
```

## Respostas

```json
{
  "201": {
    "description": "Gatilho criado",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AITrigger"
        },
        "example": {
          "id": "rt1b2c3d4e5f6a7",
          "active": true,
          "type": "agent",
          "agent_id": "ra1b2c3d4e5f6a7",
          "ignore_groups": true,
          "keywords": [],
          "priority": 1,
          "response_delay_seconds": 5,
          "event": "message",
          "lead_filters": [],
          "lead_match": "all",
          "created_at": "2026-10-17T12:00:00.000Z",
          "updated_at": "2026-10-17T12:00:00.000Z"
        }
      }
    }
  },
  "400": {
    "description": "`invalid_request`: JSON malformado ou campo desconhecido; ou valor fora do permitido, `agent_id` ou `quick_reply_id` que não existe na inbox, `flow_id` de fluxo não publicado, `field` do filtro que não é campo do chat, ou `event` diferente de `message` sem `type: flow`.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "invalid_request",
          "message": "JSON malformado ou campo desconhecido."
        }
      }
    }
  },
  "401": {
    "description": "Token ausente ou inválido.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "unauthorized",
          "message": "Token inválido."
        }
      }
    }
  },
  "409": {
    "description": "A inbox ainda não foi conectada ao WhatsApp. Os dados pertencem ao número conectado; conecte a inbox antes (`inbox_not_paired`).",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "inbox_not_paired",
          "message": "A inbox ainda não foi conectada ao WhatsApp. Os dados pertencem ao número conectado; conecte a inbox antes (`inbox_not_paired`)."
        }
      }
    }
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "description": "Falha inesperada ao gravar ou ler os dados.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/OrkesioError"
        },
        "example": {
          "error": "internal_error",
          "message": "Erro interno; tente de novo."
        }
      }
    }
  }
}
```

**Estado:** Disponível

## Compatibilidade de canais

| Canal | Compatível | Observação |
|---|---|---|
| WhatsApp (Web) | Sim |  |
| WhatsApp (API oficial) | Sim |  |
| Instagram | Sim |  |
| Messenger | Sim |  |
| Telegram | Sim |  |

## Eventos que esta rota gera

Nenhum. Esta rota não gera evento no webhook (nem em `GET /events`): o resultado vem só na resposta.

## Antes e depois (uazapi → Orkesio)

Na uazapi: `POST /chatbot/triggers`.

- Mesmo caminho e mesmas funções; muda o formato: campos em `snake_case`, datas em ISO 8601 (`_at`) e erros em `{error, message}`.
- Campos renomeados: `createdAt` → `created_at`, `ignoreGroups` → `ignore_groups`, `leadFilters` → `lead_filters`, `leadMatch` → `lead_match`, `responseDelaySeconds` → `response_delay_seconds`, `silenceMinutes` → `silence_minutes`, `updatedAt` → `updated_at`.

## #/components/schemas/AITriggerCreate

```json
{
  "type": "object",
  "description": "Na criação, `type` e o `agent_id`, `quick_reply_id` ou `flow_id` correspondente são obrigatórios; `active` começa `true` e `response_delay_seconds` em 10. Na edição, só os campos enviados mudam; `lead_filters: []` remove o filtro.",
  "additionalProperties": false,
  "properties": {
    "active": {
      "type": "boolean",
      "description": "Gatilho desligado não aciona. Padrão `true`."
    },
    "type": {
      "type": "string",
      "enum": [
        "agent",
        "quickreply",
        "flow"
      ],
      "description": "`agent` responde com o agente; `quickreply` envia uma resposta rápida; `flow` começa o fluxo."
    },
    "agent_id": {
      "type": "string",
      "description": "Agente que responde (`type: agent`)."
    },
    "quick_reply_id": {
      "type": "string",
      "description": "Resposta rápida enviada (`type: quickreply`)."
    },
    "flow_id": {
      "type": "string",
      "description": "Fluxo publicado que começa (`type: flow`)."
    },
    "ignore_groups": {
      "type": "boolean",
      "description": "Não aciona em grupos."
    },
    "keywords": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Aciona quando a mensagem tem uma destas palavras ou frases inteiras, sem diferença de maiúsculas: `oi` aciona em \"Oi, tudo bem?\", não em \"boi\" nem em \"noite\". Vazio aciona em qualquer mensagem. Não aceita `|`."
    },
    "priority": {
      "type": "integer",
      "description": "Com mais de um gatilho válido, vale o de maior prioridade."
    },
    "response_delay_seconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3600,
      "description": "Espera antes de responder, juntando as mensagens que chegarem nesse tempo numa resposta só."
    },
    "event": {
      "type": "string",
      "enum": [
        "message",
        "silence",
        "column"
      ],
      "description": "Quando o gatilho age. `message` (padrão): mensagem do contato. Os outros só começam fluxo (`type: flow`): `silence`, o contato não respondeu `silence_minutes` minutos depois da nossa mensagem (a resposta dele cancela; campanha não arma; a mensagem do próprio fluxo de silêncio não arma de novo); `column`, o lead entrou na coluna `column_id` do kanban (renomear a coluna não quebra o gatilho). Evento não tira a conversa de outro fluxo que pergunta ou aguarda."
    },
    "silence_minutes": {
      "type": "integer",
      "minimum": 10,
      "maximum": 43200,
      "description": "`event: silence`: minutos sem resposta do contato (10 a 43200, 30 dias)."
    },
    "column_id": {
      "type": "string",
      "description": "`event: column`: id da coluna do kanban (a etiqueta com kanban, de `GET /leads/tags`)."
    },
    "lead_filters": {
      "type": "array",
      "maxItems": 10,
      "items": {
        "$ref": "#/components/schemas/AILeadFilter"
      },
      "description": "Filtro de lead: o gatilho só aciona quando as condições batem (`lead_match`). Vazio aciona para todos. Para não responder contatos salvos na agenda do número que recebeu, use a condição `{ \"field\": \"wa_contactName\", \"operator\": \"empty\" }` (o nome salvo no celular). Na edição, ausente não muda; `[]` remove."
    },
    "lead_match": {
      "type": "string",
      "enum": [
        "all",
        "any"
      ],
      "default": "all",
      "description": "`all`: todas as condições; `any`: qualquer uma."
    }
  },
  "required": [
    "type"
  ],
  "allOf": [
    {
      "if": {
        "properties": {
          "type": {
            "const": "agent"
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "required": [
          "agent_id"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "type": {
            "const": "quickreply"
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "required": [
          "quick_reply_id"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "type": {
            "const": "flow"
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "required": [
          "flow_id"
        ]
      }
    }
  ]
}
```

## #/components/schemas/AILeadFilter

```json
{
  "type": "object",
  "description": "Uma condição sobre um campo do chat.",
  "required": [
    "field",
    "operator"
  ],
  "properties": {
    "field": {
      "type": "string",
      "minLength": 1,
      "description": "Campo da conversa, com o nome da coluna que a api guarda; aceita qualquer coluna do chat (um gatilho vindo do v1 pode trazer `wa_chatid`, por exemplo). Os de uso comum: o nome salvo na agenda (`wa_contactName`), o nome no WhatsApp (`wa_name`), as etiquetas (`wa_label`), `wa_unreadCount`, `wa_isGroup` ou um campo do CRM (`lead_status`, `lead_tags`, `lead_fullName`, `lead_personalid`, `lead_isTicketOpen`, `lead_field01` a `lead_field20`...).",
      "examples": [
        "wa_contactName",
        "lead_status",
        "lead_tags",
        "lead_field01"
      ]
    },
    "operator": {
      "type": "string",
      "enum": [
        "equals",
        "not_equals",
        "contains",
        "not_contains",
        "greater",
        "less",
        "empty",
        "not_empty"
      ],
      "description": "Comparação: `equals`/`not_equals` (igual/diferente), `contains`/`not_contains` (contém/não contém), `greater`/`less` (maior/menor), `empty`/`not_empty` (vazio/preenchido)."
    },
    "value": {
      "type": "string",
      "description": "Obrigatório, exceto em `empty` e `not_empty`. `greater` e `less` comparam números quando os dois lados são números."
    }
  }
}
```

## #/components/schemas/AITrigger

```json
{
  "type": "object",
  "description": "Gatilho: decide quando a IA (ou uma resposta rápida) responde.",
  "required": [
    "id",
    "active",
    "type",
    "ignore_groups",
    "keywords",
    "lead_filters",
    "priority",
    "response_delay_seconds",
    "created_at",
    "updated_at",
    "event",
    "lead_match"
  ],
  "properties": {
    "id": {
      "type": "string",
      "readOnly": true,
      "description": "ID do gatilho, usado em `/chatbot/triggers/{trigger_id}`."
    },
    "active": {
      "type": "boolean",
      "description": "Gatilho desligado não aciona."
    },
    "type": {
      "type": "string",
      "enum": [
        "agent",
        "quickreply",
        "flow"
      ],
      "description": "`agent` responde com o agente; `quickreply` envia uma resposta rápida; `flow` começa o fluxo."
    },
    "agent_id": {
      "type": "string",
      "description": "Agente que responde (`type: agent`)."
    },
    "quick_reply_id": {
      "type": "string",
      "description": "Resposta rápida enviada (`type: quickreply`)."
    },
    "flow_id": {
      "type": "string",
      "description": "Fluxo publicado que começa (`type: flow`)."
    },
    "ignore_groups": {
      "type": "boolean",
      "description": "Não aciona em grupos."
    },
    "keywords": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Aciona quando a mensagem tem uma destas palavras ou frases inteiras, sem diferença de maiúsculas: `oi` aciona em \"Oi, tudo bem?\", não em \"boi\" nem em \"noite\". Vazio aciona em qualquer mensagem."
    },
    "priority": {
      "type": "integer",
      "description": "Com mais de um gatilho válido, vale o de maior prioridade."
    },
    "response_delay_seconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3600,
      "description": "Espera antes de responder, juntando as mensagens que chegarem nesse tempo numa resposta só."
    },
    "event": {
      "type": "string",
      "enum": [
        "message",
        "silence",
        "column"
      ],
      "description": "Quando o gatilho age. `message` (padrão): mensagem do contato. Os outros só começam fluxo (`type: flow`): `silence`, o contato não respondeu `silence_minutes` minutos depois da nossa mensagem (a resposta dele cancela; campanha não arma; a mensagem do próprio fluxo de silêncio não arma de novo); `column`, o lead entrou na coluna `column_id` do kanban (renomear a coluna não quebra o gatilho). Evento não tira a conversa de outro fluxo que pergunta ou aguarda."
    },
    "silence_minutes": {
      "type": "integer",
      "minimum": 10,
      "maximum": 43200,
      "description": "`event: silence`: minutos sem resposta do contato (10 a 43200, 30 dias)."
    },
    "column_id": {
      "type": "string",
      "description": "`event: column`: id da coluna do kanban (a etiqueta com kanban, de `GET /leads/tags`)."
    },
    "column": {
      "type": "string",
      "readOnly": true,
      "description": "`event: column`: nome atual da coluna; vazio quando a etiqueta foi apagada."
    },
    "lead_filters": {
      "type": "array",
      "maxItems": 10,
      "items": {
        "$ref": "#/components/schemas/AILeadFilter"
      },
      "description": "Filtro de lead: o gatilho só aciona quando as condições batem (`lead_match`). Vazio aciona para todos. Para não responder contatos salvos na agenda do número que recebeu, use a condição `{ \"field\": \"wa_contactName\", \"operator\": \"empty\" }` (o nome salvo no celular)."
    },
    "lead_match": {
      "type": "string",
      "enum": [
        "all",
        "any"
      ],
      "default": "all",
      "description": "`all`: todas as condições; `any`: qualquer uma."
    },
    "created_at": {
      "description": "Criação. ISO 8601 em UTC com milissegundos.",
      "readOnly": true,
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "description": "Última alteração. ISO 8601 em UTC com milissegundos.",
      "readOnly": true,
      "type": "string",
      "format": "date-time"
    }
  }
}
```

## #/components/schemas/OrkesioError

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Código estável do erro, em inglês e `snake_case`. Os de uso geral: `invalid_request` (400): pedido inválido: JSON malformado, campo desconhecido ou valor fora do permitido (o detalhe em `message`; o campo em `field`, quando é um só); `unauthorized` (401): `token` ou `admintoken` ausente ou inválido; `forbidden` (403): o token não pode fazer isso (no servidor de demonstração, por exemplo); `not_admin` (403): o WhatsApp recusou por falta de permissão no grupo ou na newsletter; `account_restricted` (403): o WhatsApp restringiu a conta de iniciar conversas novas (mandar para quem já conversa continua valendo; até quando, em `GET /inbox/limits`); `new_chat_limit` (403): a conta atingiu a cota do WhatsApp de conversas novas neste ciclo (veja `GET /inbox/limits`); os dois também no `error` de `OrkesioMessage` e de `message.status`, e não adianta repetir o envio; `payment_required` (403): na API oficial, a Meta recusou o envio por um problema no pagamento da conta do WhatsApp Business (erro 131042 da Meta); acerte a forma de pagamento no gerenciador da Meta, porque repetir não adianta; também no `error` de `OrkesioMessage` e de `message.status`; `whatsapp_rejected` (400): o WhatsApp recusou a mudança pedida (o campo, em `field`, quando é um só); `not_found` (404): o recurso não existe nesta inbox; `conflict` (409): o recurso já existe ou mudou (id em uso, inbox de outro canal); `inbox_not_paired` (409): a inbox ainda não conectou um número; `payload_too_large` (413): o corpo passou do limite; `canceled` e `expired`: só no `error` de `OrkesioMessage` e de `message.status` (envio cancelado antes de sair, ou que passou do prazo na fila); `rate_limited` (429): muitos pedidos; espere o `Retry-After`; `internal_error` (500): falha inesperada na api; tente de novo; `send_failed` (500): o envio falhou (o motivo em `message`); também no `error` de `OrkesioMessage` e de `message.status`; `unsupported_for_channel` (501): o canal da inbox não atende esta rota ou este tipo de mensagem; `meta_error` (502): a Meta recusou ou não respondeu; `disconnected` (503): a inbox está desconectada (sem sessão do WhatsApp, ou token do canal oficial vencido); `unavailable` (503 ou 504): o WhatsApp não respondeu a tempo, ou algo em andamento impede agora; tente de novo. Cada rota lista os códigos próprios dela (`outside_window`, `number_invalid`, `flow_invalid`...). A lista pode crescer: trate código desconhecido pelo status HTTP."
    },
    "message": {
      "type": "string",
      "description": "Descrição para pessoas (às vezes o texto do WhatsApp ou da Meta). Não compare o texto: use `error`."
    },
    "field": {
      "type": "string",
      "description": "O campo do pedido que causou o erro, quando é um só (por exemplo, o campo que o WhatsApp recusou num `PATCH`)."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": true,
  "description": "O objeto de erro da Orkesio, o mesmo em todo lugar: o corpo das respostas de erro e o `error` de `OrkesioMessage`, `message.status` e `message.failed`. Algumas rotas juntam campos próprios (`request_id`, `errors`...)."
}
```

## #/components/responses/RateLimited

```json
{
  "description": "`rate_limited`: passou do limite de chamadas desta inbox (ou do admin); espere o tempo do header `Retry-After` e tente de novo.",
  "headers": {
    "Retry-After": {
      "description": "Segundos até poder chamar de novo.",
      "schema": {
        "type": "integer",
        "minimum": 1
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OrkesioError"
      },
      "example": {
        "error": "rate_limited",
        "message": "Muitas requisições."
      }
    }
  }
}
```

## Guias relacionados

[Visão geral](/docs/overview) · [O que funciona em cada canal](/docs/canais) · [O que muda da uazapi](/docs/o-que-muda)