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.
