Contacts

Manage the user's contacts, relationship graph, access control (trusted contacts), and invite links. This skill covers contact CRUD with multi-channel tracking, controlling who can message the assistant through external channels (Telegram, phone), and creating/managing invite links that grant access.

Contact Management

Every contact write goes through the guardian. You can list and search contacts on your own. To create, edit, delete, merge, or bind a channel to one, run the matching command below: each opens a form in the guardian's app, and the write happens only if they submit it. You are proposing, not writing. Say so: "I'll put that up for you to confirm," not "Done."

Two things a contact record does not do: it grants no access (a record has no channels, so nobody can message the assistant through it), and it is not a channel. Use assistant contacts channels add <contact_id> to bind an address to a contact that already exists, or assistant contacts invites create to let someone bind their own.

The form needs the guardian's desktop or web app to be open. If a command reports that it timed out, nobody answered: tell the user, and do not retry in a loop.

One exception you must not take: the contact_merge tool writes immediately, with no confirmation. Use assistant contacts merge instead, so the guardian sees what is being combined before the donor record is deleted.

A form the guardian closes without answering is not a failure. The command prints Cancelled: nothing was written, exits 130, and writes nothing. Report that as "the guardian did not confirm", not as an error, and do not retry in a loop.

Create a contact

assistant contacts create --name "Alice" --json

Opens an add-contact form prefilled with what you pass. The guardian can edit the name and notes before submitting, so treat the result as theirs, not yours: read the command's output rather than assuming the values you proposed were the ones written.

Optional flags:

• --notes -- proposed notes, prefilled into the form
• --channel -- also bind a channel on the same form (email, phone, telegram, whatsapp, slack). Requires --name.
• --address -- address to pre-fill for that channel; the guardian can edit it before submitting. Requires --channel.
• --verify -- pre-check the form's "mark verified" box. Requires --channel.
• --label / --description -- what the form says about why you are asking
• --timeout -- how long the form stays open, in ms (default 300000)

With --channel, the record and the channel are one form and one guardian confirmation:

assistant contacts create --name "Alice" --channel email --address "alice@example.com" --json

--name is required in that mode, because the contact is created under it. The form shows --notes but does not let the guardian edit them, so they are written as passed; use assistant contacts update to change them afterwards. --address and --verify each need --channel, so either one without it is refused rather than ignored.

The --json shape follows the mode: without --channel it is {ok, contact}, so the new id is contact.id; with --channel it is the address form's {ok, contactId, channelId, channelType, address, verified}, so the id is contactId. Read the right one before passing it to contacts invites create --contact-id.

Use this before creating an invite for someone who is not in the contact graph yet.

Bind a channel to an existing contact

assistant contacts channels add "<contact_id>" --channel email --address "alice@example.com" --json

Opens an address form naming that contact, so the guardian can see where the channel is going. Whatever address they submit binds to that contact: one confirmation, and no second record. This is how you add an address to somebody who is already in the graph. --channel is required.

Optional flags:

• --address -- address to pre-fill; the guardian can edit it before submitting
• --verify -- pre-check the form's "mark verified" box. The guardian decides: unchecked, the channel stays unverified and cannot message the assistant.
• --label / --description -- what the form says about why you are asking
• --timeout -- how long the form stays open, in ms (default 300000)

Two contacts cannot share one address. An address held by a different contact when the form is submitted is refused, the refusal names that contact, and nothing is written. Passing --address also checks up front and warns when the address looks taken, without refusing.

For an address that belongs to nobody yet, assistant contacts prompt is the create-or-bind path:

assistant contacts prompt --channel email --json
assistant contacts prompt --contact-id "<contact_id>" --channel email --json

On its own it looks up the (channel type, address) pair the guardian submits: a match reuses that contact and channel, and no match creates a new contact named after the address. --contact-id targets an existing contact instead, the same bind channels add does under its own verb.

Update a contact

assistant contacts update "<contact_id>" --name "Alice Chen" --json
assistant contacts update "<contact_id>" --notes "Moved to Berlin" --json

Opens an edit form showing the current name next to the proposed change. At least one of --name or --notes is required. This edits the record only. To revoke or block someone's access, use assistant contacts channels update-status.

Delete a contact

assistant contacts delete "<contact_id>" --json

Opens a confirmation showing the contact and its channels. Deleting a contact deletes its channels too, so anyone reaching the assistant through them loses access. A guardian contact cannot be deleted. When two records are the same person, run assistant contacts merge <surviving_contact_id> <donor_contact_id> instead: the donor's channels move to the survivor rather than being destroyed with it.

Search contacts

Search for contacts by name, channel address, or other criteria.

assistant contacts list --query "<search_term>" --json

Optional flags:

• --query -- search by display name (partial match)
• --channel-address -- search by channel address (email, phone, handle)
• --channel-type -- filter by channel type when searching by address
• --limit -- maximum results to return (default 50, max 100)

Merge contacts

When you discover two contacts are the same person (e.g. same person on email and Slack), merge them to consolidate.

assistant contacts merge <surviving_contact_id> <donor_contact_id> --json

Opens a confirmation naming both contacts and listing the channels that move. Nothing is merged unless the guardian submits it. On submit:

• The donor's channels move to the surviving contact
• Notes from both contacts are combined
• The donor record is deleted

A contact's interaction count is the sum over its channels, so a moved channel brings its history with it. An address the survivor already holds is left where it is, and its donor-side history goes with the deleted record.

Nobody loses access: every address that reached the donor reaches the survivor afterwards. A guardian contact cannot be the donor, so keep the guardian as the survivor.

The survivor keeps its own name unless the guardian edits it on the form. --keep-donor-name seeds that field with the donor's name, for when the donor is the better-named record of the two.

Access Control (Trusted Contacts)

Trusted contacts control who is allowed to send messages to the assistant through external channels like Telegram and voice (phone calls).

Concepts

• Contact channel: A user identity (external user ID or chat ID) on a specific messaging platform, stored as an entry in a contact's channels array. Each channel entry has its own status and policy.
• Policy: Controls what the contact channel can do -- allow (can message freely) or deny (blocked from messaging).
• Status: The channel's lifecycle state -- active (currently effective), revoked (access removed), or blocked (explicitly denied).
• Channel type: The messaging platform (e.g., telegram, phone).

List trusted contacts

Use this to show the user who currently has access, or to look up a specific contact.

assistant contacts list --json

Optional query parameters for filtering:

• --role <role> -- filter by role (default: contact; use guardian to list guardians)
• --limit <limit> -- maximum number of contacts to return
• --query <query> -- search query to filter contacts

Example:

assistant contacts list --role contact --json

The response contains { ok: true, contacts: [...] } where each contact has:

• id -- unique contact ID
• role -- the contact's role (contact, guardian)
• displayName -- human-readable name
• channels -- array of channel entries, each with:
  • id -- channel ID (needed for status/policy changes)
  • channel -- the channel type (e.g., telegram, phone)
  • externalUserId -- the user's ID on that channel
  • externalChatId -- the chat ID on that channel
  • displayName -- channel-specific display name
  • username -- channel username (e.g., Telegram @handle)
  • status -- current status (active, revoked, blocked, etc.)
  • policy -- current policy (allow, deny)
• createdAt -- when the contact was added

Presenting results: Format the contact list as a readable table or list. Include display name, role, and per-channel status/policy. If no contacts exist, tell the user their contact list is empty.

Allow a user (add trusted contact)

Access is granted per channel, not per contact, and it always takes proof that the person holds the address. Creating the contact record is only the first step.

1. Contact record -- if they are not in the graph yet, assistant contacts create --name "<name>". The guardian confirms it. This alone grants nothing.
2. Invite link -- assistant contacts invites create --source-channel <channel> --contact-id <contact_id>. The invitee redeems it from the address they actually control, which is what makes the channel trusted. This is the path to prefer: it works even when nobody knows the invitee's handle on that channel up front.
3. Address the guardian already knows -- for someone already in the graph, assistant contacts channels add <contact_id> --channel <channel> opens a form naming that contact and binds the address there. For a brand new address with no record behind it, assistant contacts prompt --channel <channel> creates the contact from what the guardian types. Either way the channel lands unverified unless the guardian checks the verify box on that form, and an unverified channel cannot message the assistant.

Only the guardian's own submission can complete any of these, so never promise access is live until the command returns.

Revoke a user (remove access)

Use this when the user wants to remove someone's access. Always confirm with the user before executing this action.

Ask the user: "I'll revoke access for [name/identifier]. They will no longer be able to message the assistant. Should I proceed?"

First, list contacts to find the channel's id (each entry in a contact's channels array has an id field -- visible in assistant contacts list --json output), then revoke:

Important: Before revoking, check the channel's current status. If the channel is blocked, do not attempt to revoke it -- blocking is stronger than revoking. Inform the user that the contact is already blocked and revoking is not applicable. Only channels with active or pending status can be revoked.

assistant contacts channels update-status <channel_id> --status revoked --reason "<optional reason>" --json

Replace <channel_id> with the channel's id from the contact's channels array.

Block a user

Use this when the user wants to explicitly block someone. Blocking is stronger than revoking -- it marks the contact as actively denied. Always confirm with the user before executing this action.

Ask the user: "I'll block [name/identifier]. They will be permanently denied from messaging the assistant. Should I proceed?"

assistant contacts channels update-status <channel_id> --status blocked --reason "<optional reason>" --json

Replace <channel_id> with the channel's id from the contact's channels array (visible in assistant contacts list --json output).

Invite Links

Invite links let the guardian share a link or code that automatically grants access when used. Telegram invites use a deep link; voice invites use a phone number + numeric code; email, WhatsApp, Slack, and Discord invites use a 6-digit code that the invitee sends to the assistant on the respective channel. Discord invitees must share a server with the bot and have DMs from server members enabled before they can send it the code.

Every invite must be bound to a contact. Before creating an invite, look up the contact with assistant contacts list and pass the contact's id via the required --contact-id flag. If the target contact doesn't exist yet, create it first with assistant contacts create --name "<name>" and wait for the guardian to confirm; the invite needs only a name, never the invitee's address on that channel.

Create a Telegram invite link

Use this when the guardian wants to invite someone to message the assistant on Telegram without needing their user ID upfront. The invite link is a shareable Telegram deep link -- when someone opens it, they automatically get trusted-contact access.

Important: The shell snippet below emits a <vellum-sensitive-output> directive containing the raw invite token. The tool executor automatically strips this directive and replaces the raw token with a placeholder so the LLM never sees it. The placeholder is resolved back to the real token in the final assistant reply.

INVITE_JSON=$(assistant contacts invites create --source-channel telegram --contact-id "<contact_id>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json)

INVITE_TOKEN=$(printf '%s' "$INVITE_JSON" | python3 -c "
import json, sys
data = json.load(sys.stdin)
invite = data.get('invite', {})
print(invite.get('token', ''), end='')
")
INVITE_URL=$(printf '%s' "$INVITE_JSON" | python3 -c "
import json, sys
data = json.load(sys.stdin)
invite = data.get('invite', {})
share = invite.get('share') or {}
print(share.get('url', ''), end='')
")

if [ -z "$INVITE_TOKEN" ]; then
  printf '%s\n' "$INVITE_JSON"
  exit 1
fi

# Prefer backend-provided canonical link when available.
if [ -z "$INVITE_URL" ]; then
  BOT_USERNAME=$(assistant config get telegram.botUsername)
  if [ -z "$BOT_USERNAME" ] || [ "$BOT_USERNAME" = "(not set)" ]; then
    echo "error:no_share_url_or_bot_username"
    exit 1
  fi
  INVITE_URL="https://t.me/$BOT_USERNAME?start=iv_$INVITE_TOKEN"
fi

echo "<vellum-sensitive-output kind=\"invite_code\" value=\"$INVITE_TOKEN\" />"
echo "$INVITE_URL"

Required flags:

• --source-channel -- must be telegram
• --contact-id -- the ID of the contact this invite is for. Look up the contact first with assistant contacts list, or create one with assistant contacts create if they are not in the graph yet.

Optional flags:

• --max-uses -- how many times the link can be used (default: 1). Use a higher number for group invites.
• --expires-in-ms -- expiration time in milliseconds from now (e.g., 86400000 for 24 hours). Defaults to 7 days (604800000) if omitted.
• --note -- a human-readable label for the invite (e.g., "For Mom", "Family group").

The create response contains { ok: true, invite: { id, token, share?, ... } }.

• token is the raw invite token and is only returned at creation time.
• share.url is the canonical shareable deep link (when channel transport config is available).

Always use invite.share.url when present. Do not manually construct ?start= links if the API already provided one.

Presenting to the guardian: Give the guardian the link with clear copy-paste instructions:

Here's your Telegram invite link:

https://t.me/<botUsername>?start=iv_<token>

Share this link with the person you want to invite. When they open it in Telegram and press "Start", they'll automatically be added as a trusted contact and can message the assistant directly.

This link can be used <maxUses> time(s)<and expires in X hours/days if applicable>.

If the Telegram bot username is not available (integration not set up), tell the guardian they need to set up the Telegram integration first using the Telegram Setup skill.

Create a voice invite

Use this when the guardian wants to authorize a specific phone number to call the assistant. Voice invites are identity-bound: the invitee must call from the specified phone number AND enter a one-time numeric code.

Important: The response includes a voiceCode field that is only returned at creation time and cannot be retrieved later. Extract and present it clearly.

assistant contacts invites create --source-channel phone --contact-id "<contact_id>" --expected-external-user-id "<phone_E164>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json

Required flags:

• --source-channel -- must be phone
• --contact-id -- the ID of the contact this invite is for. Look up the contact first with assistant contacts list, or create one with assistant contacts create if they are not in the graph yet. The contact's displayName is used to personalize the voice greeting; the guardian label is resolved at runtime.
• --expected-external-user-id -- the invitee's phone number in E.164 format (e.g., +15551234567)

Optional flags:

• --max-uses -- how many times the code can be used (default: 1)
• --expires-in-ms -- expiration time in milliseconds from now (e.g., 86400000 for 24 hours). Defaults to 7 days if omitted.
• --note -- a human-readable label for the invite (e.g., "For Mom", "Dr. Smith")

The create response contains { ok: true, invite: { id, voiceCode, expectedExternalUserId, ... } }.

• voiceCode is the numeric code the invitee must enter and is only returned at creation time.
• Voice invite responses do not include token or share.url. Do not try to build or send a deep link for voice invites.

Presenting to the guardian: Give the guardian clear instructions to relay to the invitee:

Voice invite created for <phone_number>:

Invite code: <voiceCode>

Share these instructions with the person you are inviting:

1. Call the assistant's phone number from <phone_number> (the call must come from this exact number)
2. When prompted, enter the code <voiceCode>
3. Once verified, they will be added as a trusted contact and can call the assistant directly in the future

This code can be used <maxUses> time(s)<and expires in X hours/days if applicable>.

There is no "open link" step for voice invites. The invite is redeemed only during a live phone call from the bound number.

If the user provides a phone number without the + country code prefix, ask them to confirm the full E.164 number (e.g., US numbers should be +1XXXXXXXXXX).

Create an email invite

Use this when the guardian wants to invite someone to message the assistant via email. Email invites use a 6-digit code - the invitee sends the code to the assistant's email address to redeem access.

assistant contacts invites create --source-channel email --contact-id "<contact_id>" --max-uses 1 --note "<optional note, e.g. the person it is for>" --json

Required flags:

• --source-channel -- must be email
• --contact-id -- the ID of the contact this invite is for. Look up the contact first with assistant contacts list, or create one with assistant contacts create if they are not in the graph yet.

The response contains { ok: true, invite: { id, token, inviteCode, guardianInstruction, channelHandle, ... } }.

• inviteCode is the 6-digit code the invitee must send to redeem the invite. It is only returned at creation time.
• guardianInstruction is a generated instruction telling the guardian how to share the invite.
• channelHandle is the assistant's email address (e.g. hello@vellum.me).

Presenting to the guardian: Give the guardian the invite code and the assistant's email address:

Email invite created for <contact_name>:

Invite code: <inviteCode>

Tell them to send an email to <channelHandle> with the code <inviteCode> in the body. Once verified, they will be added as a trusted contact and can email the assistant directly.

This code can be used <maxUses> time(s)<and expires in X hours/days if applicable>.

If the assistant's email address is not available, tell the guardian they need to register one with assistant email register <username>.