Esses eventos mantêm seu banco de dados ou CRM externo em sincronia com a base de contatos da Timely.ai. Toda vez que um contato novo entra, um dado é atualizado ou um contato é deletado, você recebe um evento.
Lista de eventos
| Evento | Quando dispara |
|---|
contact.created | Um novo contato é adicionado ao workspace |
contact.updated | Dados de um contato existente são modificados |
contact.deleted | Um contato é removido permanentemente |
Quando dispara
Um novo contato é adicionado ao workspace — seja porque um número desconhecido enviou a primeira mensagem num canal, seja porque um atendente criou manualmente, seja via API.
Payload
{
"event": "contact.created",
"event_id": "evt_01HX5A1K9MFQR4YZDNV7P9WCE",
"timestamp": "2026-04-19T14:30:00Z",
"workspace_id": "ws_abc123",
"data": {
"contact_id": "cont_456",
"name": "Ana Costa",
"phone": "+5547991234567",
"email": "ana.costa@exemplo.com.br",
"avatar_url": null,
"source": "whatsapp",
"tags": [],
"custom_fields": {},
"assigned_to": null,
"created_at": "2026-04-19T14:30:00Z"
}
}
Campos principais
| Campo | Tipo | Descrição |
|---|
contact_id | string | ID único do contato no workspace |
name | string | null | Nome do contato |
phone | string | null | Telefone no formato E.164 |
email | string | null | E-mail do contato |
avatar_url | string | null | URL do avatar (quando disponível via canal) |
source | enum | Canal de origem: whatsapp, instagram, widget, telegram, api, manual |
tags | array | Lista de tags aplicadas |
custom_fields | object | Campos personalizados no formato { "chave": "valor" } |
assigned_to | string | null | ID do atendente responsável |
Exemplo de uso
Use contact.created com source para identificar de qual canal vêm mais contatos novos. Combine com contact_id para criar o registro no seu CRM antes de qualquer interação.
Quando dispara
Qualquer campo de um contato existente é modificado — nome, e-mail, telefone, tags, campos personalizados ou atendente responsável. O payload inclui tanto os valores novos quanto os anteriores.
Payload
{
"event": "contact.updated",
"event_id": "evt_01HX5B3M2PGTS6YADOV8Q1XDF",
"timestamp": "2026-04-19T15:10:00Z",
"workspace_id": "ws_abc123",
"data": {
"contact_id": "cont_456",
"changes": {
"name": {
"before": "Ana Costa",
"after": "Ana Costa Ribeiro"
},
"tags": {
"before": [],
"after": ["cliente-vip", "pagamento-pendente"]
},
"custom_fields": {
"before": {},
"after": {
"plano": "pro",
"data_contrato": "2026-04-19"
}
}
},
"updated_by": "usr_321",
"updated_by_type": "attendant",
"updated_at": "2026-04-19T15:10:00Z"
}
}
Campos principais
| Campo | Tipo | Descrição |
|---|
changes | object | Dicionário de campos alterados, cada um com before e after |
updated_by | string | null | ID de quem fez a alteração |
updated_by_type | enum | attendant, agent, api, automation |
updated_at | string | Timestamp ISO 8601 da atualização |
Exemplo de uso
Use o objeto changes para atualizar apenas os campos que realmente mudaram no seu sistema externo — evita sobrescrever dados que você pode ter enriquecido localmente.
Para sincronização bidirecional, registre o updated_by_type e ignore atualizações onde updated_by_type seja api quando você mesmo disparou — evita loops de sincronização.
Quando dispara
Um contato é removido permanentemente do workspace. A exclusão pode ser feita manualmente por um atendente com permissão ou via API. Contatos deletados não podem ser recuperados.
Payload
{
"event": "contact.deleted",
"event_id": "evt_01HX5C5P4RHTW7ZBEPV9S2YEG",
"timestamp": "2026-04-19T16:00:00Z",
"workspace_id": "ws_abc123",
"data": {
"contact_id": "cont_456",
"name": "Ana Costa Ribeiro",
"phone": "+5547991234567",
"email": "ana.costa@exemplo.com.br",
"deleted_by": "usr_321",
"deleted_by_type": "attendant",
"deleted_at": "2026-04-19T16:00:00Z"
}
}
Campos principais
| Campo | Tipo | Descrição |
|---|
contact_id | string | ID do contato deletado |
name | string | null | Nome do contato no momento da exclusão |
phone | string | null | Telefone do contato (para referência de auditoria) |
email | string | null | E-mail do contato (para referência de auditoria) |
deleted_by | string | ID de quem executou a exclusão |
deleted_by_type | enum | attendant, api |
deleted_at | string | Timestamp ISO 8601 da exclusão |
Exemplo de uso
Use contact.deleted para garantir conformidade com LGPD no seu CRM — remova ou anonimize os dados do contato nos seus sistemas assim que receber esse evento. O contact_id não existirá mais na API após a exclusão.
