Skip to main content
Esses eventos disparam o agente. Todos exigem customer.phone no formato E.164. No painel, em Guardrails → Eventos gatilho, você marca quais deles ativam o agente no seu produto.
Enviar um evento de gatilho que não está marcado no painel é aceito pelo endpoint e armazenado, mas não dispara conversa. Ative no painel os gatilhos que fazem sentido para o seu produto.
EventoQuando enviar
subscription.cancelledCliente cancelou a assinatura.
user.inactiveCliente parou de usar o produto por um período significativo.
usage.droppedO consumo do cliente caiu abaixo do padrão.
payment.failedFalha de pagamento ainda sem cancelamento confirmado.
trial.expiredPeríodo de trial terminou sem conversão.
plan.downgradedCliente reduziu o plano contratado.
subscription.pausedCliente pausou a assinatura em vez de cancelar.
cancel_page.visitedCliente acessou a página de cancelamento no seu produto (sinal preditivo).
export_data.requestedCliente solicitou exportar os próprios dados (sinal preditivo).

​
Referência por evento

O metadata é sempre opcional. Os campos sugeridos abaixo não são exigidos pelo schema, mas o agente usa essas informações para conduzir conversas mais contextualizadas.

​
subscription.cancelled

Cliente confirmou o cancelamento da assinatura. Envie no momento em que o cancelamento entra em vigor no seu sistema. 
{
  "event": "subscription.cancelled",
  "customer": {
    "external_id": "usr_42",
    "name": "Maria Silva",
    "email": "maria@empresa.com.br",
    "phone": "+5511999999999"
  },
  "metadata": {
    "reason": "too_expensive",
    "feedback": "Achei bom mas pesou no orçamento do mês",
    "plan": "Pro Anual",
    "monthly_value": 9900,
    "cancelled_via": "dashboard"
  }
}
Sugestões de metadata: reason (ex.: too_expensive, missing_feature, moving_to_competitor, not_using, other), feedback (texto livre), plan, monthly_value (em centavos), cancelled_via (dashboard, support, api).

​
user.inactive

Cliente ficou sem usar o produto por um período que o seu time considera relevante. Útil como sinal preditivo antes do cancelamento. 
{
  "event": "user.inactive",
  "customer": {
    "external_id": "usr_42",
    "name": "Maria Silva",
    "email": "maria@empresa.com.br",
    "phone": "+5511999999999"
  },
  "metadata": {
    "days_inactive": 14,
    "last_login_at": "2026-04-09T10:30:00.000Z",
    "last_active_feature": "reports"
  }
}
Sugestões de metadata: days_inactive, last_login_at (ISO 8601), last_active_feature.

​
usage.dropped

Consumo mensurável do cliente caiu significativamente em relação à linha de base dele. 
{
  "event": "usage.dropped",
  "customer": {
    "external_id": "usr_42",
    "name": "Maria Silva",
    "email": "maria@empresa.com.br",
    "phone": "+5511999999999"
  },
  "metadata": {
    "metric": "api_calls",
    "drop_percent": 60,
    "baseline_value": 12000,
    "current_value": 4800,
    "window_days": 30
  }
}
Sugestões de metadata: metric, drop_percent, baseline_value, current_value, window_days.

​
payment.failed

Falha na cobrança, ainda sem cancelamento definitivo. Agente pode tentar reter o cliente antes do churn involuntário. 
{
  "event": "payment.failed",
  "customer": {
    "external_id": "usr_42",
    "name": "Maria Silva",
    "email": "maria@empresa.com.br",
    "phone": "+5511999999999"
  },
  "metadata": {
    "reason": "insufficient_funds",
    "amount": 9900,
    "retry_count": 2,
    "next_retry_at": "2026-04-25T09:00:00.000Z"
  }
}
Sugestões de metadata: reason (ex.: insufficient_funds, expired_card, invalid_card, fraud_suspected), amount (centavos), retry_count, next_retry_at.

​
trial.expired

Trial do cliente terminou sem conversão para plano pago. 
{
  "event": "trial.expired",
  "customer": {
    "external_id": "usr_42",
    "name": "Maria Silva",
    "email": "maria@empresa.com.br",
    "phone": "+5511999999999"
  },
  "metadata": {
    "trial_duration_days": 14,
    "used_days": 10,
    "last_active_at": "2026-04-20T16:00:00.000Z"
  }
}
Sugestões de metadata: trial_duration_days, used_days, last_active_at.

​
plan.downgraded

Cliente reduziu o plano contratado — sinal de insatisfação parcial. 
{
  "event": "plan.downgraded",
  "customer": {
    "external_id": "usr_42",
    "name": "Maria Silva",
    "email": "maria@empresa.com.br",
    "phone": "+5511999999999"
  },
  "metadata": {
    "from_plan": "Pro",
    "to_plan": "Starter",
    "from_value": 9900,
    "to_value": 4900
  }
}
Sugestões de metadata: from_plan, to_plan, from_value (centavos), to_value (centavos).

​
subscription.paused

Cliente pausou a assinatura em vez de cancelar — sinal de reticência. 
{
  "event": "subscription.paused",
  "customer": {
    "external_id": "usr_42",
    "name": "Maria Silva",
    "email": "maria@empresa.com.br",
    "phone": "+5511999999999"
  },
  "metadata": {
    "resume_scheduled_at": "2026-07-01T00:00:00.000Z",
    "reason": "temporary_budget_cut"
  }
}
Sugestões de metadata: resume_scheduled_at (ISO 8601 ou null), reason.

​
cancel_page.visited

Cliente acessou a página de cancelamento no seu produto. Sinal preditivo — o agente pode entrar em ação antes do cancelamento acontecer. 
{
  "event": "cancel_page.visited",
  "customer": {
    "external_id": "usr_42",
    "name": "Maria Silva",
    "email": "maria@empresa.com.br",
    "phone": "+5511999999999"
  },
  "metadata": {
    "referrer": "billing_page",
    "time_on_page_seconds": 45
  }
}
Sugestões de metadata: referrer, time_on_page_seconds.

​
export_data.requested

Cliente pediu para exportar os próprios dados. Frequentemente precede cancelamento. 
{
  "event": "export_data.requested",
  "customer": {
    "external_id": "usr_42",
    "name": "Maria Silva",
    "email": "maria@empresa.com.br",
    "phone": "+5511999999999"
  },
  "metadata": {
    "export_type": "full",
    "requested_at": "2026-04-23T14:30:00.000Z"
  }
}
Sugestões de metadata: export_type (full, partial), requested_at (ISO 8601).