Eventos de agendamento

Esses eventos cobrem o ciclo de vida dos agendamentos gerenciados pela Timely.ai — seja via agente de IA integrando com Google Calendar, seja via fluxo manual do atendente. Use-os para sincronizar com sistemas de gestão de clínicas, academias, salões ou qualquer negócio com agenda.

Lista de eventos

Evento	Quando dispara
`appointment.scheduled`	Um novo agendamento é confirmado
`appointment.rescheduled`	Data ou horário de um agendamento é alterado
`appointment.canceled`	Um agendamento é cancelado
`appointment.reminder_sent`	Um lembrete automático é enviado ao contato

`appointment.scheduled`

Quando dispara

Um novo agendamento é criado e confirmado — pode ser pelo agente de IA via integração com Google Calendar, pelo atendente manualmente ou via API. O evento só dispara quando o status está confirmed, não em rascunhos ou tentativas pendentes.

Payload

{
  "event": "appointment.scheduled",
  "event_id": "evt_01HX7A1K9MFQR4YZDNV7P9WCE",
  "timestamp": "2026-04-19T14:30:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "appointment_id": "appt_01HX7A1K",
    "conversation_id": "conv_01HX3B2K",
    "contact_id": "cont_456",
    "title": "Consulta - Ana Costa",
    "description": "Primeira consulta de avaliação",
    "start_at": "2026-04-22T09:00:00-03:00",
    "end_at": "2026-04-22T09:30:00-03:00",
    "timezone": "America/Sao_Paulo",
    "location": "Online — Google Meet",
    "meet_link": "https://meet.google.com/abc-defg-hij",
    "calendar_event_id": "cal_event_google_xyz",
    "calendar_id": "gcal_abc123",
    "attendant_id": "usr_321",
    "created_by": "agt_101",
    "created_by_type": "agent",
    "reminders": [
      { "method": "whatsapp", "minutes_before": 1440 },
      { "method": "whatsapp", "minutes_before": 60 }
    ],
    "created_at": "2026-04-19T14:30:00Z"
  }
}

Campos principais

Campo	Tipo	Descrição
`appointment_id`	string	ID único do agendamento
`conversation_id`	string \| null	ID da conversa onde o agendamento foi criado
`contact_id`	string	ID do contato
`title`	string	Título do compromisso
`start_at`	string	Data/hora de início com fuso (ISO 8601 com offset)
`end_at`	string	Data/hora de término com fuso
`timezone`	string	Fuso horário em formato IANA
`location`	string \| null	Local físico ou link
`meet_link`	string \| null	Link do Google Meet (quando criado via integração)
`calendar_event_id`	string \| null	ID do evento no Google Calendar
`attendant_id`	string \| null	Atendente responsável pelo compromisso
`created_by_type`	enum	`agent`, `attendant`, `api`, `automation`
`reminders`	array	Lista de lembretes configurados com `method` e `minutes_before`

Exemplo de uso

Use appointment.scheduled para registrar o compromisso no seu sistema interno, confirmar com o contato por e-mail separado ou bloquear horários em outro calendário.

`appointment.rescheduled`

Quando dispara

Data, horário ou local de um agendamento existente é alterado. O evento inclui tanto os valores anteriores quanto os novos para facilitar auditoria e notificações direcionadas.

Payload

{
  "event": "appointment.rescheduled",
  "event_id": "evt_01HX7B3M2PGTS6YADOV8Q1XDF",
  "timestamp": "2026-04-20T10:00:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "appointment_id": "appt_01HX7A1K",
    "contact_id": "cont_456",
    "changes": {
      "start_at": {
        "before": "2026-04-22T09:00:00-03:00",
        "after": "2026-04-23T14:00:00-03:00"
      },
      "end_at": {
        "before": "2026-04-22T09:30:00-03:00",
        "after": "2026-04-23T14:30:00-03:00"
      }
    },
    "rescheduled_by": "usr_321",
    "rescheduled_by_type": "attendant",
    "rescheduled_at": "2026-04-20T10:00:00Z"
  }
}

Campos principais

Campo	Tipo	Descrição
`appointment_id`	string	ID do agendamento alterado
`changes`	object	Campos modificados com `before` e `after`
`rescheduled_by`	string	ID de quem reagendou
`rescheduled_by_type`	enum	`agent`, `attendant`, `contact`, `api`
`rescheduled_at`	string	Timestamp ISO 8601 do reagendamento

`appointment.canceled`

Quando dispara

Um agendamento é cancelado. O cancelamento pode ser iniciado pelo contato, pelo atendente, pelo agente de IA ou via API. O evento no Google Calendar também é atualizado automaticamente quando há integração ativa.

Payload

{
  "event": "appointment.canceled",
  "event_id": "evt_01HX7C5P4RHTW7ZBEPV9S2YEG",
  "timestamp": "2026-04-21T08:30:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "appointment_id": "appt_01HX7A1K",
    "contact_id": "cont_456",
    "title": "Consulta - Ana Costa",
    "start_at": "2026-04-23T14:00:00-03:00",
    "cancellation_reason": "contact_requested",
    "cancellation_note": "Cliente solicitou cancelamento via WhatsApp",
    "canceled_by": "agt_101",
    "canceled_by_type": "agent",
    "canceled_at": "2026-04-21T08:30:00Z"
  }
}

Campos principais

Campo	Tipo	Descrição
`cancellation_reason`	enum	`contact_requested`, `attendant_decision`, `no_show`, `api`, `automation`
`cancellation_note`	string \| null	Observação sobre o motivo do cancelamento
`canceled_by`	string	ID de quem executou o cancelamento
`canceled_by_type`	enum	`agent`, `attendant`, `contact`, `api`
`canceled_at`	string	Timestamp ISO 8601 do cancelamento

Após um appointment.canceled, o appointment_id permanece acessível na API para histórico, mas o status é canceled. Novos eventos não serão emitidos para esse agendamento.

`appointment.reminder_sent`

Quando dispara

Um lembrete automático é enviado ao contato antes do horário do compromisso. Os lembretes são configurados no momento da criação do agendamento e disparados automaticamente pelo sistema.

Payload

{
  "event": "appointment.reminder_sent",
  "event_id": "evt_01HX7D7Q5SJUW8ZCFQWA3ZFH",
  "timestamp": "2026-04-22T13:00:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "appointment_id": "appt_01HX7A1K",
    "contact_id": "cont_456",
    "title": "Consulta - Ana Costa",
    "start_at": "2026-04-23T14:00:00-03:00",
    "reminder_method": "whatsapp",
    "minutes_before": 1440,
    "message_id": "msg_01HX7D7Q",
    "sent_at": "2026-04-22T13:00:00Z"
  }
}

Campos principais

Campo	Tipo	Descrição
`appointment_id`	string	ID do agendamento ao qual o lembrete se refere
`reminder_method`	enum	`whatsapp`, `email`, `sms`
`minutes_before`	integer	Antecedência do lembrete em minutos (ex: `1440` = 24h antes)
`message_id`	string \| null	ID da mensagem enviada pelo canal (quando `whatsapp`)
`sent_at`	string	Timestamp ISO 8601 do envio

Exemplo de uso

Use appointment.reminder_sent para registrar no seu sistema que o contato foi notificado. Se um lembrete falhar (o evento não chegar), investigue se o canal associado ao contato ainda está conectado.

​Lista de eventos

​appointment.scheduled

​Quando dispara

​Payload

​Campos principais

​Exemplo de uso

​appointment.rescheduled

​Quando dispara

​Payload

​Campos principais

​appointment.canceled

​Quando dispara

​Payload

​Campos principais

​appointment.reminder_sent

​Quando dispara

​Payload

​Campos principais

​Exemplo de uso

Lista de eventos

`appointment.scheduled`

Quando dispara

Payload

Campos principais

Exemplo de uso

`appointment.rescheduled`

Quando dispara

Payload

Campos principais

`appointment.canceled`

Quando dispara

Payload

Campos principais

`appointment.reminder_sent`

Quando dispara

Payload

Campos principais

Exemplo de uso