contacts
contacts.add_channel
Add Channel to Contact
Effects: write
🔗 Link a channel identity (email, phone, Telegram/WhatsApp handle) to an existing contact.
When to use:
- User learns a contact's email or phone and wants to save it
- Adding a second channel for an existing person
Email/phone are stamped as the contact's identity keys, so channel sync attaches the matching conversation to the same contact automatically.
If the identity already belongs to a DIFFERENT contact, the call fails unless merge_if_linked=true — which IRREVERSIBLY merges the two contacts into one. Requires contact_id (entity_id) from contacts.find.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
channel | string | yes | Channel type to add (one of email, whatsapp, telegram, linkedin, instagram) |
contact_id | string | yes | entity_id from contacts.find/contacts.sync; when sync returned no entity_id, pass its person_id instead |
display_name | string | no | Optional display label for this identity |
merge_if_linked | boolean | no | If the identity already belongs to a DIFFERENT contact, merge that contact into this one (IRREVERSIBLE — the other contact record is deleted). Default false: the call fails instead of merging. |
value | string | yes | Email address, phone number, or username for this channel |
contacts.capture_lead
Capture Lead
Effects: write
📝 Save the current contact's details as a structured lead (contact + Contacts tab).
When to use:
- In a website-chat OR voice-call conversation, AFTER the person has shared their name (plus email / phone / company / use case if given) — e.g. when booking a demo or a class.
- Call it once you have the details; then continue (e.g. share the booking link).
Creates/links a contact record and a lead entry in the workspace's lead inbox. Works in any conversation thread (website chat, voice call, DM).
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
company | string | no | The visitor's company / organization, if mentioned. |
email | string | no | The visitor's email address. |
name | string | yes | The visitor's full name (as they gave it). |
phone | string | no | Phone number, if the visitor provided one. |
use_case | string | no | Their main use case / what they want to do with DialogBrain, if mentioned. |
contacts.discover
Discover Contact
Effects: read, external_api
Search for a contact on a live channel (Telegram, WhatsApp, etc.) before adding them. Use this to look up a person by username or phone number before calling contacts.sync. This is the right tool when asked to add or find a specific person by @username or phone (use contacts.sync afterwards to actually add them) — not group_discovery.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
channel | string | yes | Channel name: telegram, whatsapp, etc. |
query | string | yes | Username, phone, or name to search for |
contacts.find
Search Contacts
Effects: read, external_api
👤 Search for contacts in your address book by name or username.
When to use:
- User asks 'find contact X' or 'who is Y?'
- User wants to know someone's username or ID
- Before sending a message to verify contact exists
- To get contact's channel reference for messaging
Examples:
❓ User: 'find contact named [name]'
→ contacts_search(query='[name]', limit=5)
❓ User: 'who is [full name]?'
→ contacts_search(query='[full name]', limit=1)
❓ User: 'search for @username'
→ contacts_search(query='username', limit=10)
Returns: name, username, channel, channel_ref, similarity_score, match_type. Plus:
- entity_id: local DB key — pass to contacts.profile. Null for live-discovered contacts (skip contacts.profile for those).
- telegram_user_id (when channel='telegram'): the Telegram user ID — pass to calls.make / messages.send. NOT entity_id.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
channel | string | no | Filter by channel. OMIT to search across all channels. (one of telegram, email, whatsapp, sms, slack) |
limit | integer | no | Maximum number of results to return (default 10; min 1.0; max 50.0) |
query | string | yes | Name or username to search for (supports partial matches) (min 1.0) |
contacts.merge
Merge Contacts
Effects: write
🧬 Merge two contacts into one: all channel identities, scores and summaries of the second contact move onto the first, and the second contact record is deleted.
When to use:
- contacts.find shows the same person twice (e.g. a messenger contact and an email contact)
- The user explicitly asks to merge two specific contacts
Both ids are entity_id values from contacts.find. The merge is recorded in Review Duplicates and can be undone there (undo is heuristic, not guaranteed). Never merge on name similarity alone — confirm the pair is really one person first.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
contact_id_keep | string | yes | entity_id (from contacts.find/sync) of the contact to KEEP; a person_id is accepted when sync returned no entity_id |
contact_id_merge | string | yes | entity_id (from contacts.find/sync) of the contact to merge INTO the kept one; a person_id is accepted too |
contacts.profile
Get Contact Profile
Effects: read
👤 Get full profile for a contact: all channel identities, notes, role, capabilities, birthday.
When to use:
- After contacts.find to get complete info about a specific person
- To see all channels a contact is reachable on
- To read notes, role, or capabilities for a contact
Requires contact_id (entity_id) from contacts.find.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
contact_id | string | yes | entity_id from contacts.find |
contacts.research
Contact Research
Effects: read, external_api
Research a person before outreach: returns a synthesized profile (current role, company, location, career history, education, LinkedIn/social URLs) plus a candidates array for disambiguating namesakes. Use to personalize a first touch or brief before a meeting. Does NOT return contact channels (email/phone/telegram) — use contacts.discover to add a reachable channel, or the LinkedIn URL from the result for a connection request.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
query | string | yes | Who to research: full name plus any disambiguating context you have (company, role, location), e.g. '[full name], founder of [company]'. |
contacts.sync
Sync Contact
Effects: write, external_api
Add a discovered contact and open a conversation thread. Returns thread_id for the new conversation, plus entity_id — the canonical handle to pass as contacts.update's contact_id. Call contacts.discover first to verify the contact exists.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
channel | string | yes | Channel name: telegram, whatsapp, etc. |
from_account_id | integer | no | Which of the workspace's accounts on this channel opens the conversation — i.e. WHO the contact will see as the sender. OMIT and the platform picks the account that already holds most of this workspace's threads. Pass it whenever the sender matters: a workspace with several numbers on one channel usually has one that must not start conversations (a personal line, or one under a spam restriction). An account that is not active in this workspace is refused, never silently swapped for another. |
identifier | string | yes | Username or phone number to add |
contacts.update
Update Contact
Effects: write
✏️ Update a contact's profile: name, notes, role, capabilities, birthday, preferred channel.
When to use:
- User wants to add notes about a contact
- User wants to set/update role or capabilities for a contact
- User wants to rename a contact or update birthday
Requires contact_id — the entity_id returned by contacts.find or contacts.sync. At least one optional field must be provided.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
birthday_day | integer | no | Birth day 1-31 (must be set together with birthday_month) (min 1.0; max 31.0) |
birthday_month | integer | no | Birth month 1-12 (must be set together with birthday_day) (min 1.0; max 12.0) |
birthday_year | integer | no | Birth year 1900-2100 (optional, standalone) (min 1900.0; max 2100.0) |
capabilities | array | no | List of capabilities (e.g. ['backend', 'design']) |
contact_id | string | yes | entity_id from contacts.find or contacts.sync |
display_name | string | no | New display name (max 255 chars) |
notes | string | no | Free-text notes/context about this contact. Empty string clears notes. |
preferred_channel | string | no | Preferred channel for contacting this person. OMIT to leave the preferred channel unchanged. (one of telegram, whatsapp, email, instagram, linkedin) |
role | string | no | Contact role (e.g. developer, client, partner). Empty string clears role. |