Eventos de billing

Esses eventos permitem que você monitore a situação financeira do workspace de forma proativa — receba alertas antes de ficarem sem créditos, seja notificado de mudanças de plano e acompanhe o ciclo de trial sem precisar acessar o dashboard manualmente.

Lista de eventos

Evento	Quando dispara
`credit.low`	O saldo de créditos cai abaixo do limite de alerta configurado
`credit.depleted`	Os créditos chegam a zero — o workspace fica sem capacidade de processar mensagens
`plan.changed`	O plano do workspace é alterado (upgrade, downgrade ou cancelamento)
`trial.expiring`	O período de trial está a 3 dias do fim
`trial.expired`	O trial encerrou sem conversão para plano pago

`credit.low`

Quando dispara

O saldo de créditos do workspace cai abaixo do threshold de alerta configurado em Configurações → Billing. Por padrão, o alerta é acionado quando restam menos de 20% dos créditos do ciclo atual.

Payload

{
  "event": "credit.low",
  "event_id": "evt_01HX9A1K9MFQR4YZDNV7P9WCE",
  "timestamp": "2026-04-19T18:00:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "credits_remaining": 1850,
    "credits_total": 10000,
    "credits_used": 8150,
    "usage_percentage": 81.5,
    "alert_threshold_percentage": 80,
    "estimated_depletion_at": "2026-04-21T12:00:00Z",
    "billing_period_end": "2026-04-30T23:59:59Z",
    "plan_id": "plan_pro",
    "plan_name": "Pro"
  }
}

Campos principais

Campo	Tipo	Descrição
`credits_remaining`	integer	Créditos ainda disponíveis
`credits_total`	integer	Total de créditos do ciclo
`credits_used`	integer	Créditos consumidos até agora
`usage_percentage`	number	Percentual de uso (0–100)
`alert_threshold_percentage`	number	Threshold configurado que gerou o alerta
`estimated_depletion_at`	string \| null	Estimativa de quando os créditos vão zerar, baseada no consumo médio
`billing_period_end`	string	Data de fim do ciclo de billing atual
`plan_id`	string	ID do plano atual

Exemplo de uso

Use credit.low para acionar um alerta automático no Slack ou WhatsApp do gestor financeiro antes que o serviço seja interrompido. O campo estimated_depletion_at ajuda a priorizar a urgência.

`credit.depleted`

Quando dispara

O saldo de créditos chega a zero. Quando isso acontece, o workspace entra em modo restrito: o agente de IA para de responder mensagens novas até que créditos sejam adicionados ou o ciclo de billing renove.

Payload

{
  "event": "credit.depleted",
  "event_id": "evt_01HX9B3M2PGTS6YADOV8Q1XDF",
  "timestamp": "2026-04-21T14:35:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "credits_remaining": 0,
    "credits_total": 10000,
    "credits_used": 10000,
    "billing_period_end": "2026-04-30T23:59:59Z",
    "plan_id": "plan_pro",
    "plan_name": "Pro",
    "service_status": "restricted",
    "depleted_at": "2026-04-21T14:35:00Z"
  }
}

Campos principais

Campo	Tipo	Descrição
`credits_remaining`	integer	Sempre `0` nesse evento
`service_status`	enum	`restricted` — o agente de IA está pausado
`depleted_at`	string	Timestamp ISO 8601 do esgotamento

Exemplo de uso

credit.depleted é crítico. Quando disparado, o agente de IA para de responder — contatos podem ficar sem atendimento. Configure uma automação que adicione créditos automaticamente ou notifique imediatamente o responsável pelo billing.

`plan.changed`

Quando dispara

O plano do workspace é alterado: upgrade para um plano superior, downgrade para um plano menor, migração entre planos do mesmo nível ou cancelamento de assinatura. Inclui o plano anterior e o novo.

Payload

{
  "event": "plan.changed",
  "event_id": "evt_01HX9C5P4RHTW7ZBEPV9S2YEG",
  "timestamp": "2026-04-19T11:00:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "previous_plan_id": "plan_starter",
    "previous_plan_name": "Starter",
    "new_plan_id": "plan_pro",
    "new_plan_name": "Pro",
    "change_type": "upgrade",
    "effective_at": "2026-04-19T11:00:00Z",
    "billing_period_end": "2026-05-19T23:59:59Z",
    "changed_by": "usr_321"
  }
}

Campos principais

Campo	Tipo	Descrição
`previous_plan_id`	string	ID do plano anterior
`previous_plan_name`	string	Nome do plano anterior
`new_plan_id`	string	ID do novo plano
`new_plan_name`	string	Nome do novo plano
`change_type`	enum	`upgrade`, `downgrade`, `canceled`, `reactivated`
`effective_at`	string	Quando a mudança entrou em vigor
`changed_by`	string \| null	ID do usuário que realizou a mudança

Exemplo de uso

Use plan.changed com change_type: "canceled" para acionar um fluxo de retenção — envie uma mensagem de acompanhamento ou ofereça suporte antes que o cliente encerre definitivamente o uso da plataforma.

`trial.expiring`

Quando dispara

O período de trial do workspace está a 3 dias do vencimento e ainda não houve conversão para plano pago. Esse evento é disparado uma única vez por ciclo de trial.

Payload

{
  "event": "trial.expiring",
  "event_id": "evt_01HX9D7Q5SJUW8ZCFQWA3ZFH",
  "timestamp": "2026-04-17T09:00:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "trial_end_at": "2026-04-20T23:59:59Z",
    "days_remaining": 3,
    "plan_id": "plan_trial",
    "conversations_used": 142,
    "messages_used": 1834,
    "contacts_total": 87,
    "upgrade_url": "https://app.timelyai.com.br/billing/upgrade"
  }
}

Campos principais

Campo	Tipo	Descrição
`trial_end_at`	string	Data/hora de expiração do trial
`days_remaining`	integer	Dias restantes até o fim do trial
`conversations_used`	integer	Total de conversas abertas durante o trial
`messages_used`	integer	Total de mensagens trocadas durante o trial
`contacts_total`	integer	Total de contatos no workspace
`upgrade_url`	string	Link direto para a página de upgrade

`trial.expired`

Quando dispara

O período de trial terminou sem que o workspace tenha assinado um plano pago. Após essa data, o workspace entra em modo somente leitura — nenhum agente de IA responde e novos canais não podem ser conectados.

Payload

{
  "event": "trial.expired",
  "event_id": "evt_01HX9E9R6TKXV9ADGRXB4AGI",
  "timestamp": "2026-04-21T00:00:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "trial_end_at": "2026-04-20T23:59:59Z",
    "plan_id": "plan_trial",
    "service_status": "read_only",
    "conversations_used": 198,
    "messages_used": 2540,
    "contacts_total": 115,
    "upgrade_url": "https://app.timelyai.com.br/billing/upgrade",
    "expired_at": "2026-04-21T00:00:00Z"
  }
}

Campos principais

Campo	Tipo	Descrição
`service_status`	enum	`read_only` — o workspace está bloqueado para operações
`conversations_used`	integer	Total de conversas abertas durante o trial
`messages_used`	integer	Total de mensagens durante o trial
`expired_at`	string	Timestamp ISO 8601 da expiração
`upgrade_url`	string	Link direto para a página de upgrade

Exemplo de uso

Se você é um parceiro ou revendedor da Timely.ai e gerencia múltiplos workspaces, use trial.expiring e trial.expired para automatizar follow-ups de conversão. Os campos conversations_used e messages_used mostram o engajamento do cliente durante o trial — ótimos dados para personalizar a abordagem.

Eventos de billing são enviados apenas para webhooks que têm os eventos credit.*, plan.* ou trial.* na lista de subscrição. Certifique de incluir essas categorias ao criar o webhook se quiser receber essas notificações.

​Lista de eventos

​credit.low

​Quando dispara

​Payload

​Campos principais

​Exemplo de uso

​credit.depleted

​Quando dispara

​Payload

​Campos principais

​Exemplo de uso

​plan.changed

​Quando dispara

​Payload

​Campos principais

​Exemplo de uso

​trial.expiring

​Quando dispara

​Payload

​Campos principais

​trial.expired

​Quando dispara

​Payload

​Campos principais

​Exemplo de uso

Lista de eventos

`credit.low`

Quando dispara

Payload

Campos principais

Exemplo de uso

`credit.depleted`

Quando dispara

Payload

Campos principais

Exemplo de uso

`plan.changed`

Quando dispara

Payload

Campos principais

Exemplo de uso

`trial.expiring`

Quando dispara

Payload

Campos principais

`trial.expired`

Quando dispara

Payload

Campos principais

Exemplo de uso