Contacts

Contacts manage your agent's address book with multi-channel identity support.

Overview

Features:

• Multi-channel identity (email, phone, social)
• Tags and metadata
• Identity resolution
• Contact grouping
• History tracking

Contact Fields

Field	Description
name	Contact name
email	Email address
phone	Phone number
telegram	Telegram username
whatsapp	WhatsApp number
twitter	Twitter/X handle
external_id	External system ID
notes	Free-form notes
tags	JSON array of tags
metadata	JSON metadata

Creating Contacts

Via Dashboard

1. Navigate to Contacts
2. Click Add Contact
3. Fill in details
4. Save

Via API

curl -X POST https://your-domain.com/api/agents/{id}/contacts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "telegram": "@johndoe",
    "tags": ["customer", "vip"],
    "metadata": {
      "company": "Acme Corp",
      "plan": "enterprise"
    }
  }'

Managing Contacts

List Contacts

curl "https://your-domain.com/api/agents/{id}/contacts?limit=50"

Search Contacts

curl "https://your-domain.com/api/agents/{id}/contacts?search=john"

Get Contact

curl https://your-domain.com/api/agents/{id}/contacts/{contactId}

Update Contact

curl -X PUT https://your-domain.com/api/agents/{id}/contacts/{contactId} \
  -d '{
    "name": "John D. Doe",
    "tags": ["customer", "vip", "enterprise"]
  }'

Delete Contact

curl -X DELETE https://your-domain.com/api/agents/{id}/contacts/{contactId}

Identity Resolution

Uranus automatically resolves identities across channels:

┌─────────────────────────────────────────────────────────┐
│                  Incoming Message                        │
│                                                          │
│   Email: john@example.com                               │
│   or                                                     │
│   Phone: +1234567890                                    │
│   or                                                     │
│   Telegram: @johndoe                                    │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│               Identity Resolution                        │
│                                                          │
│   1. Search by email                                    │
│   2. Search by phone                                    │
│   3. Search by telegram                                 │
│   4. Search by whatsapp                                 │
│   5. Search by twitter                                  │
│   6. Search by external_id                              │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                 Resolved Contact                         │
│                                                          │
│   ID: contact-123                                       │
│   Name: John Doe                                        │
│   Email: john@example.com                               │
│   Phone: +1234567890                                    │
│   Telegram: @johndoe                                    │
└─────────────────────────────────────────────────────────┘

Tags

Organize contacts with tags:

{
  "tags": ["customer", "vip", "west-coast"]
}

Filter by Tag

curl "https://your-domain.com/api/agents/{id}/contacts?tag=vip"

Common Tags

• customer - Paying customers
• prospect - Potential customers
• vip - High-value contacts
• support - Support contacts
• partner - Business partners

Metadata

Store custom data:

{
  "metadata": {
    "company": "Acme Corp",
    "industry": "Technology",
    "plan": "enterprise",
    "mrr": 5000,
    "contract_end": "2025-12-31"
  }
}

Conversations

Link contacts to conversations:

Contact
  └── Conversation 1 (Email)
  └── Conversation 2 (Telegram)
  └── Conversation 3 (WhatsApp)

Get Contact Conversations

curl "https://your-domain.com/api/agents/{id}/conversations?contact_id={contactId}"

Integration

With Workflows

{
  "type": "lookup-contact",
  "data": {
    "email": "{{message.from}}"
  },
  "output": "contact"
}

With Chat

Contact context is available in conversations:

System: Current contact: John Doe (john@example.com)
        Tags: customer, vip
        Company: Acme Corp

With Gateways

Route messages based on contact:

{
  "type": "send-message",
  "data": {
    "contact_id": "{{contact.id}}",
    "message": "Hello {{contact.name}}!",
    "channel": "{{contact.preferred_channel}}"
  }
}

Import/Export

Import Contacts

curl -X POST https://your-domain.com/api/agents/{id}/contacts/import \
  -F "file=@contacts.csv"

CSV format:

name,email,phone,telegram,tags
John Doe,john@example.com,+1234567890,@johndoe,"customer,vip"
Jane Smith,jane@example.com,+0987654321,@janesmith,prospect

Export Contacts

curl "https://your-domain.com/api/agents/{id}/contacts/export?format=csv" > contacts.csv

Best Practices

1. Consistent Formatting

Normalize data:

• Phone: E.164 format (+1234567890)
• Email: lowercase
• Social: without @ prefix

2. Use Tags Wisely

Create a tagging strategy:

• Keep tags simple
• Use consistent naming
• Document tag meanings

3. Regular Cleanup

Maintain data quality:

• Merge duplicates
• Remove stale contacts
• Update outdated info

4. Privacy Compliance

Respect privacy:

• Track consent
• Honor opt-outs
• Secure data access

5. Enrich Data

Add context over time:

• Interaction history
• Preferences
• Purchase history

API Reference

See Contacts API for complete endpoint documentation.