Contact events - Timely.ai

These events keep your external database or CRM in sync with Timely.ai’s contact base. Every time a new contact comes in, a field is updated, or a contact is deleted, you receive an event.

Event list

Event	When it fires
`contact.created`	A new contact is added to the workspace
`contact.updated`	Data for an existing contact is modified
`contact.deleted`	A contact is permanently removed

`contact.created`

When it fires

A new contact is added to the workspace — either because an unknown number sent the first message on a channel, because an agent created it manually, or 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"
  }
}

Key fields

Field	Type	Description
`contact_id`	string	Unique contact ID in the workspace
`name`	string \| null	Contact name
`phone`	string \| null	Phone number in E.164 format
`email`	string \| null	Contact email
`avatar_url`	string \| null	Avatar URL (when available via channel)
`source`	enum	Origin channel: `whatsapp`, `instagram`, `widget`, `telegram`, `api`, `manual`
`tags`	array	List of applied tags
`custom_fields`	object	Custom fields in `{ "key": "value" }` format
`assigned_to`	string \| null	ID of the responsible agent

Usage example

Use contact.created with source to identify which channel brings in the most new contacts. Combine with contact_id to create the record in your CRM before any interaction.

`contact.updated`

When it fires

Any field of an existing contact is modified — name, email, phone, tags, custom fields, or responsible agent. The payload includes both the new and previous values.

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"
  }
}

Key fields

Field	Type	Description
`changes`	object	Dictionary of changed fields, each with `before` and `after`
`updated_by`	string \| null	ID of who made the change
`updated_by_type`	enum	`attendant`, `agent`, `api`, `automation`
`updated_at`	string	ISO 8601 timestamp of the update

Usage example

Use the changes object to update only the fields that actually changed in your external system — this avoids overwriting data you may have enriched locally.

For bidirectional sync, record the updated_by_type and ignore updates where updated_by_type is api when you triggered the update yourself — this prevents sync loops.

`contact.deleted`

When it fires

A contact is permanently removed from the workspace. Deletion can be done manually by an agent with the appropriate permission or via API. Deleted contacts cannot be recovered.

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"
  }
}

Key fields

Field	Type	Description
`contact_id`	string	ID of the deleted contact
`name`	string \| null	Contact name at the time of deletion
`phone`	string \| null	Contact phone (for audit reference)
`email`	string \| null	Contact email (for audit reference)
`deleted_by`	string	ID of who performed the deletion
`deleted_by_type`	enum	`attendant`, `api`
`deleted_at`	string	ISO 8601 timestamp of deletion

Usage example

Use contact.deleted to ensure LGPD compliance in your CRM — remove or anonymize the contact’s data in your systems as soon as you receive this event. The contact_id will no longer exist in the API after deletion.

​Event list

​contact.created

​When it fires

​Payload

​Key fields

​Usage example

​contact.updated

​When it fires

​Payload

​Key fields

​Usage example

​contact.deleted

​When it fires

​Payload

​Key fields

​Usage example

Event list

`contact.created`

When it fires

Payload

Key fields

Usage example

`contact.updated`

When it fires

Payload

Key fields

Usage example

`contact.deleted`

When it fires

Payload

Key fields

Usage example