Managing contacts

Contact Intelligence automatically creates a contact record the first time a customer messages you on any connected channel. You don't manually create contacts.

Contact list

Contact Intelligence → Contacts

Each row shows the contact's display name (or identifier if no name is known), channel, mood, relationship stage, last active date, and churn risk.

Via the API

GET /contacts?channel=whatsapp&stage=fading&sort=churn_risk&limit=20

Response:

{
  "contacts": [
    {
      "id": "ct_01j...",
      "externalId": "+919876543210",
      "channel": "whatsapp",
      "displayName": "Priya",
      "outreachDisabled": false,
      "createdAt": "2026-01-15T08:00:00Z",
      "mood": "neutral",
      "energy": "medium",
      "relationshipStage": "fading",
      "totalMessages": 47,
      "churnRisk": 0.62,
      "lastActiveAt": "2026-06-14T09:22:10Z",
      "activeStreak": 0
    }
  ],
  "total": 234,
  "limit": 20,
  "offset": 0
}

Full contact profile

Click a contact to see their full profile:

• State — current mood, energy, relationship stage, active streak, total messages, churn risk
• Memories — everything CI has learned about them (up to 50, ranked by importance)
• Entities — named things they've mentioned: pets, family, workplace, hobbies, places

GET /contacts/:id/profile

Response includes the contact, state, an array of memories (with type, content, importance, entity links), and an array of entities.

Stopping outreach for a contact

If a customer asks not to be contacted proactively, disable outreach for their contact:

Dashboard: Contact profile → Stop outreach

This sets outreach_disabled = true. No future outreach triggers will fire for this contact, regardless of inactivity or milestones. Existing pending triggers are not cancelled automatically — cancel them separately if needed.

To re-enable:

PATCH /contacts/:id
Content-Type: application/json
 
{ "outreach_disabled": false }

Deleting a contact (GDPR)

Deleting a contact wipes their personal data while preserving the anonymised audit trail:

1. The contact record is soft-deleted (external ID is replaced with a placeholder)
2. All memories, entities, and interaction logs are permanently deleted
3. All outreach triggers are removed (via cascade)
4. The contact ID is retained for audit purposes but the record is unusable

Dashboard: Contact profile → Delete contact → Confirm

DELETE /contacts/:id

Response:

{ "deleted": true }

Exporting a contact's data

For GDPR right-of-access requests:

GET /contacts/:id/export

Returns a JSON document containing the contact record, state, all memories, all entities, and an interaction log count.

Clearing memories without deleting the contact

To wipe a contact's memories while keeping their record and state:

DELETE /contacts/:id/memories

Response:

{ "deleted": true }

This removes all memory rows but leaves the contact, state, entities, and interaction logs intact. The contact's churn risk and relationship stage are not recalculated immediately — they update on the next message or the next 6-hour cron run.