Contacts tools

Twenty-three tools cover the contact-intelligence CRM — directory, memory, live context, proactive outreach, analytics, and AI-assisted drafting.

All endpoints follow the pattern POST https://mcp.vlozi.app/tools/contacts.<name> with Authorization: Bearer ls_xxx. All responses use this envelope:

{ "data": <payload>, "error": null }   // success
{ "data": null,      "error": "..." }  // failure (with HTTP 4xx/5xx)

Directory

contacts.list_contacts

List contacts with their live state (mood, energy, relationship stage, churn risk, message count, last-active). Use before get_contact_profile to find a contact id.

Scope: contacts:contacts.read

Input:

Response: { contacts: ContactRow[], total: number, limit: number, offset: number } — each row includes mood/energy/relationshipStage/totalMessages/churnRisk/lastActiveAt (null if the contact has no state row yet).

curl -X POST https://mcp.vlozi.app/tools/contacts.list_contacts \
  -H "Authorization: Bearer $VLOZI_API_KEY" \
  -d '{"stage": "fading", "sort": "churn_risk", "limit": 10}'

contacts.get_contact_profile

Full profile for one contact: the contact row, its state, up to 50 top memories by importance, and resolved entities.

Scope: contacts:contacts.read

Input: { contact_id: string } (required)

Response: { contact, state: object | null, memories: Memory[], entities: Entity[] }

contacts.get_contact_channels

List the channels a contact has been reached on, with the external id and match confidence per channel. Reflects multi-channel identity after merges.

Scope: contacts:contacts.read

Input: { contact_id: string } (required)

Response: { channels: { id, channelType, externalId, confidence, linkedAt }[] }, newest-linked first

contacts.get_contact_timeline

Emotional + relationship trajectory over a lookback window: per-message mood/energy points, weekly emotional snapshots, and relationship snapshots (stage, score, trajectory, velocity).

Scope: contacts:contacts.read

Input: { contact_id: string, days?: number } (days 1–365, default 90)

Response: { days: number, mood_points: { mood, energy, role, at }[], emotional_snapshots: { periodType, periodStart, dominantMood, moodScore, variance, trendDirection, keyTriggers }[], relationship_snapshots: { periodStart, stage, relationshipScore, trajectory, velocity }[] }

contacts.create_contact

Create a contact for a channel identity, or return the existing one if that (channel, external_id) is already known.

Scope: contacts:contacts.create

Input:

Response: { contact: { id, ... }, created: boolean }, HTTP 201 on a true create

curl -X POST https://mcp.vlozi.app/tools/contacts.create_contact \
  -H "Authorization: Bearer $VLOZI_API_KEY" \
  -d '{"external_id": "+15551234567", "channel": "whatsapp", "display_name": "Ben"}'

contacts.merge_contacts

Merge a source contact into a target: re-parents memories, entities, channels, logs, and outreach onto the target (deduping collisions), folds engagement counters, then soft-deletes the source.

Scope: contacts:contacts.delete

Input: { target_contact_id: string, source_contact_id: string } (both required)

Response: { merged: true, target: string, channel_count: number }

contacts.delete_contact

GDPR deletion: soft-deletes and anonymises the contact, then hard-deletes its memories, entities, and interaction logs.

Scope: contacts:contacts.delete

Input: { contact_id: string } (required)

Response: { deleted: true }

contacts.export_contact

GDPR data export: the contact row, its state, all memories and entities, and the interaction count — everything held about the contact.

Scope: contacts:contacts.read

Input: { contact_id: string } (required)

Response: { export_date: string, contact, state: object | null, memories: Memory[], entities: Entity[], interaction_count: number }

Memory

contacts.list_memories

List a contact's memories (facts, preferences, episodes, patterns), highest-importance first, with type, importance, access count, and linked entity ids.

Scope: contacts:memory.read

Input: { contact_id: string } (required)

Response: { memories: { id, memoryType, content, importance, accessCount, entityIds, createdAt, accessedAt }[] } (up to 100)

contacts.delete_all_memories

Delete ALL memories for a contact — the contact and its state row are kept.

Scope: contacts:memory.delete

Input: { contact_id: string } (required)

Response: { deleted: true }

contacts.correct_memory

Correct a contact's memory. hint fuzzy-matches (case-insensitive substring) the highest-importance active memory; that memory is superseded and a new corrected memory is stored.

Scope: contacts:context.write

Input: { contact_id: string, hint: string, correction: string } (all required — hint 1–500 chars, correction 1–2000 chars)

Response: { corrected: true, memory_id: string } — id of the new corrected memory, not the one it replaced

Context

contacts.get_context

Build the LLM context packet for a contact — the same hot-path context the chat engine itself uses.

Scope: contacts:context.read

Input:

Response:

{
  "session_core": "string | null",
  "message_relevance": "string | null",
  "has_message_context": false,
  "relationship": { "stage": "...", "trajectory": null, "velocity": null, "mood_trend": null },
  "crisis_level": "...",
  "triggers": []
}

Outreach

contacts.list_outreach

List outreach triggers (scheduled proactive messages), newest scheduled first.

Scope: contacts:outreach.read

Input:

Response: { triggers: OutreachTrigger[], total: number, limit: number, offset: number }

contacts.schedule_outreach

Schedule a proactive outreach message to a contact at a future time.

Scope: contacts:outreach.create

Input:

Response: { trigger: { id, contact_id, trigger_type, scheduled_at, message, message_template, context, status: "pending" } }, HTTP 201

curl -X POST https://mcp.vlozi.app/tools/contacts.schedule_outreach \
  -H "Authorization: Bearer $VLOZI_API_KEY" \
  -d '{
    "contact_id": "ct_xxx",
    "trigger_type": "milestone",
    "scheduled_at": "2026-09-01T09:00:00Z",
    "message": "You have been with us a full month — how is it going?"
  }'

contacts.cancel_outreach

Cancel a pending outreach trigger by id.

Scope: contacts:outreach.create

Input: { id: string } (required — outreach trigger id)

Response: { cancelled: true }

contacts.get_outreach_config

Get the workspace outreach config. Returns sensible defaults if none has been saved yet.

Scope: contacts:outreach.read

Input: none

Response: { config: { enabled, inactivityDays, maxInactivityAttempts, minGapDays, maxPerDay, quietHoursStart, quietHoursEnd, timezone } }

contacts.update_outreach_config

Update (upsert) the workspace outreach config. Pass only the fields to change.

Scope: contacts:outreach.create

Input:

Response: { config: object }

contacts.trigger_outreach_scan

Ops action: run the outreach scanner immediately (fires due triggers, creates inactivity/milestone triggers). Normally runs on a 6-hour cron — use this to force a scan.

Scope: contacts:outreach.create

Input: none

Response: { triggered: number, inactivityCreated: number, milestonesCreated: number, errors: string[] }

Analytics

contacts.analytics_trends

Engagement overview: total contacts, contacts active in the last 7 days, and the distribution of contacts across relationship stages.

Scope: contacts:analytics.read

Input: none

Response: { total_contacts: number, active_last_7_days: number, stage_distribution: Record<string, number> }

contacts.analytics_churn

Churn-risk report: a high/medium-risk count summary plus the top at-risk contacts, ordered by risk.

Scope: contacts:analytics.read

Input: { limit?: number } (1–100, default 20)

Response: { summary: { high_risk: number, medium_risk: number }, at_risk_contacts: { contactId, churnRisk, relationshipStage, lastActiveAt, totalMessages, displayName, channel }[] }

contacts.analytics_moods

Workspace mood + energy distribution — a count of contacts per current mood and per current energy level.

Scope: contacts:analytics.read

Input: none

Response: { moods: Record<string, number>, energy: Record<string, number> }

AI

contacts.draft_outreach_message

AI-write a personalized proactive message for a contact, using their memories, mood, and relationship context. Returns the text — does not send it. Pair with schedule_outreach.

Scope: contacts:outreach.create

Input: { contact_id: string, goal?: string, tone?: string } (goal e.g. "win-back", "check-in"; tone e.g. "warm", "professional")

Response: { message: string, creditsCharged: number } — message capped at 300 chars

contacts.summarize_contact

AI-summarize what you know about a contact — key memories, preferences, mood, and relationship state — into a short 2–4 sentence brief.

Scope: contacts:contacts.read

Input: { contact_id: string } (required)

Response: { summary: string, creditsCharged: number }