Concept
Contacts are customer records in the Timely.ai integrated CRM. Every conversation that arrives through any channel (WhatsApp, Instagram, Telegram, widget) is automatically associated with a contact — created based on the channel identifier (phone number, IGSID, Telegram chat_id) or linked to an existing contact by email or phone. You can also create and update contacts via API to sync with your external CRM, e-commerce platforms, billing systems, or any other data source. Contacts support custom fields via Custom Fields, which lets you adapt the CRM to your specific business needs.Main Fields
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Unique contact ID |
name | string | Full name |
email | string | Email address |
phone | string | Phone in E.164 format (e.g. +15551234567) |
avatar_url | string | Contact avatar URL |
tags | array | List of tags for segmentation |
custom_fields | object | Custom field values |
source | string | Contact source (whatsapp, instagram, api, etc.) |
created_at | string | ISO 8601 creation timestamp |
updated_at | string | ISO 8601 last update timestamp |
last_conversation_at | string | ISO 8601 last conversation timestamp |
Automatic Deduplication
Timely tries to avoid duplicate contacts when automatically creating one during a conversation. Deduplication uses the following priority:- Channel identifier (phone for WhatsApp, IGSID for Instagram)
- Email (if available)
- Normalized phone number (E.164)
phone or email already exists, Timely returns the existing contact instead of creating a duplicate.
Available Endpoints
See the left sidebar for the full list of endpoints in this group. Each endpoint has its own page with request/response schema, cURL/JS/Python examples, and an interactive playground.
Next Steps
Your first request
If you haven’t made your first call yet, start here.