Guardian Verify Setup

You are helping your user set up channel verification for a messaging channel (phone, Telegram, Slack, Discord, or email). This links their identity for verified message delivery on the chosen channel. Use the assistant channel-verification-sessions CLI for all verification operations.

When to Use

Load this skill when:

• The user says "verify me", "verify my identity", "set up verification", "verify my [phone/telegram/slack/discord/email]", or any equivalent identity-handshake intent.
• Another skill is wiring up a channel and needs to bind the guardian's identity to it (e.g., slack-app-setup invokes this skill at the end of Slack setup so the user can prove ownership of the configured workspace).

Do not load this skill for:

• Generic "set up X" intents where X is not a guardian channel (use the channel-specific setup skill instead).
• Phone-CALLS intent (use the phone-calls skill — those are outbound calls the assistant makes, not verification handshakes).

Prerequisites

• Run shell commands for this skill with bash.
• Keep narration minimal: execute required calls first, then provide a concise status update. Do not narrate internal install/check/load chatter unless something fails.

Step 1: Confirm Channel

Ask the user which channel they want to verify:

• phone -- verify a phone number for voice calls
• telegram -- verify a Telegram account
• slack -- verify a Slack account
• discord -- verify a Discord account
• email -- verify an email address

Skip the prompt and proceed directly with the named channel when:

• The user's intent already specifies a channel (e.g. "verify my phone number for voice calls", "verify me on Slack").
• This skill is loaded from another skill that has already established the channel (e.g., slack-app-setup finishes configuring Slack then loads this skill — slack is already the channel; do not re-prompt the user for which channel after they just spent the prior steps configuring one).

⚠️ CRITICAL — point of action: Do not re-prompt for channel when it is already determined. Re-prompting after a parent skill has just configured a channel makes the user feel like the assistant forgot the previous five minutes of setup.

Step 2: Collect Destination

Based on the chosen channel, ask for the required destination:

• Phone: Ask for their phone number. Accept any common format (e.g. +15551234567, (555) 123-4567, 555-123-4567). The API normalizes it to E.164.

• Email: Ask for their email address. The bot will send a verification code to that address.

• Telegram: Ask for their Telegram chat ID (numeric) or @handle. Explain:

  • If they know their numeric chat ID, provide it directly. The bot will send the code to that chat.
  • If they only know their @handle, the flow uses a bootstrap deep-link that they must click first.

• Slack: Offer to look up the user's Slack member ID automatically to reduce friction:

  1. Auto-lookup (preferred): Ask the user for their Slack display name or @handle, then look up their member ID using the Slack API.

     Set USER_QUERY to whatever the user gave you (display name, @handle, or full name — the search matches against all of them). For example, if the user says "find me, I'm @alice", set USER_QUERY="alice". If they say "Alice Example", set USER_QUERY="Alice Example". Do not leave USER_QUERY as a literal <...> placeholder string.

     USER_QUERY="alice"  # ← replace with the actual value the user provided
     USER_QUERY="${USER_QUERY#@}"  # strip leading @ — Slack .name fields have no @ prefix
     
     # Search for matching users (paginate through all workspace members).
     # The request door sends the bot token from inside the assistant; never
     # reveal it into a variable or a curl line, where it would land in the
     # transcript and the tool log. The door exits non-zero when the bot is
     # not configured, when the call is refused, and when Slack answers with
     # ok:false, so one branch covers every failure.
     CURSOR=""
     MATCHES="[]"
     while true; do
       RESPONSE=$(assistant channels request slack "/users.list?limit=200${CURSOR:+&cursor=$CURSOR}") || {
         echo "ERROR: the Slack lookup failed; fall back to manual entry"
         exit 1
       }
       PAGE_MATCHES=$(echo "$RESPONSE" | jq --arg q "$USER_QUERY" '[.members[] | select(.deleted == false) | select(.profile.display_name == $q or .name == $q or .profile.display_name_normalized == $q or .real_name == $q) | {id: .id, name: .name, display_name: .profile.display_name, real_name: .real_name}]')
       MATCHES=$(echo "$MATCHES $PAGE_MATCHES" | jq -s 'add')
       CURSOR=$(echo "$RESPONSE" | jq -r '.response_metadata.next_cursor // empty')
       [ -z "$CURSOR" ] && break
     done
     echo "$MATCHES" | jq '.[]'

     ⚠️ CRITICAL — point of action: Substitute USER_QUERY with the actual user-provided value before running the bash block. A literal USER_QUERY="<query>" or USER_QUERY="<name>" matches nothing and burns a users.list cycle.

     Result handling:

     • Single match: Present it for confirmation: "I found @username (U01ABCDEF) — is that you?" If confirmed, use the id value as the destination for Step 3.
     • Multiple matches: Present the list (up to 5) and ask the user to pick: "I found a few matches — which one is you?" Use the confirmed id as the destination.
     • No matches: Tell the user no matches were found. Suggest they double-check the spelling, or fall back to manual entry (see below).

  2. Fallback to manual entry if any of the following occur:

     • The bash block above exits 1: the Slack bot is not configured, the request door refused the call, or Slack answered users.list with an error such as missing_scope (the door prints the reason)
     • Too many matches are returned (more than 5)
     • The user prefers to enter their ID directly

     For manual entry: ask for their Slack user ID. Explain that this is their Slack member ID (e.g. U01ABCDEF), not their display name or email. They can find it in their Slack profile under "More" > "Copy member ID".

  The bot will send a verification code via Slack DM once the member ID is resolved.

• Discord: Ask for their Discord user ID, a numeric snowflake such as 900000000000000001. To find it: User Settings > Advanced > Developer Mode, then right-click their own name in any channel or the member list and choose Copy User ID. A username or @handle will not work.

  The bot DMs the code to that user. Discord only permits that DM when the bot and the user share a server, so complete the invite step of discord-app-setup first, and note that a user who has turned off direct messages from server members cannot receive it.

Step 3: Start Outbound Verification

Execute the outbound start request:

assistant channel-verification-sessions create --channel <channel> --destination "<destination>" --json

Replace <channel> with phone, telegram, slack, discord, or email, and <destination> with the phone number, Telegram destination, Slack user ID, Discord user ID, or email address.

On success (success: true)

Report the exact next action based on the channel:

• Phone: The response includes a secret field with the verification code. Tell the user the code BEFORE the call connects: "I'm calling [number] now. Your verification code is [secret]. When you answer the call, enter this code using your phone's keypad." The create command already initiates the voice call. Do NOT place a separate call_start call. After delivering the code, immediately begin the auto-check polling loop (see Auto-Check Polling below).
• Telegram with chat ID (no telegramBootstrapUrl in response): The response includes a secret field. Show it in the current chat: "Your verification code is [secret]. I've also sent it to your Telegram. Open the Telegram bot chat and reply with that 6-digit code to complete verification." If the response does not contain a secret field, treat this as a control-plane error: tell the user something went wrong and ask them to retry from Step 3 or resend (Step 4).
• Telegram with handle (telegramBootstrapUrl present in response): "Tap this deep-link first: [telegramBootstrapUrl]. After Telegram binds your identity, I'll send your verification code."
• Slack: The response includes a secret field with the verification code. Show it in the current chat: "Your verification code is [secret]. I've also sent it to you as a Slack DM. Open the DM from the Vellum bot in Slack and reply with that 6-digit code to complete verification." The DM channel ID is captured automatically during this process for future message delivery. If the response does not contain a secret field, treat this as a control-plane error: tell the user something went wrong and ask them to retry from Step 3 or resend (Step 4). After delivering the code, immediately begin the auto-check polling loop (see Auto-Check Polling below).
• Discord: The response includes a secret field with the verification code. Show it in the current chat: "Your verification code is [secret]. I've also sent it to you as a Discord DM. Open the DM from the bot and send that 6-digit code in this DM to complete verification. Any plain message containing the code works; Discord's reply feature is not required." If the response does not contain a secret field, treat this as a control-plane error: tell the user something went wrong and ask them to retry from Step 3 or resend (Step 4). After delivering the code, begin the auto-check polling loop (see Auto-Check Polling below). The DM send is fire-and-forget, so a closed-DM or not-in-a-shared-server failure shows up as the poll timing out rather than as an error here.
• Email: The response includes a secret field with the verification code. Show it in the current chat: "Your verification code is [secret]. I've also sent it to your email. Reply to the verification email with only the 6-digit code to complete verification." If the response does not contain a secret field, treat this as a control-plane error: tell the user something went wrong and ask them to retry from Step 3 or resend (Step 4). After delivering the code, immediately begin the auto-check polling loop (see Auto-Check Polling below).

After reporting the bootstrap URL for Telegram handle flows, wait for the user to confirm they clicked the link. Then check verification status (Step 6) to see if the bootstrap completed and a code was sent.

On error (success: false)

Handle each error code:

Step 4: Handle Resend

If the user says they did not receive the code or asks to resend:

assistant channel-verification-sessions resend --channel <channel> --json

On success, report the next action based on the channel:

• Phone: The resend response includes a fresh secret field with a new verification code. Tell the user the new code BEFORE the call connects - just like the initial start flow: "I'm calling [number] again. Your new verification code is [secret]. When you answer the call, enter this code using your phone's keypad." The resend command already initiates the voice call. Do NOT place a separate call_start call. After delivering the code, immediately begin the auto-check polling loop (see Auto-Check Polling below).
• Telegram: The resend response includes a fresh secret field. Show the new code in the current chat: "Your new verification code is [secret]. I've also sent it to your Telegram. Open the Telegram bot chat and reply with that 6-digit code to complete verification." If the response does not contain a secret field, treat this as a control-plane error: tell the user something went wrong and ask them to retry from Step 3.
• Slack: The resend response includes a fresh secret field. Show the new code in the current chat: "Your new verification code is [secret]. I've also sent it to you as a Slack DM. Reply to the DM with that 6-digit code to complete verification. (resent)" If the response does not contain a secret field, treat this as a control-plane error: tell the user something went wrong and ask them to retry from Step 3. After delivering the code, immediately begin the auto-check polling loop (see Auto-Check Polling below).
• Discord: The resend response includes a fresh secret field. Show the new code in the current chat: "Your new verification code is [secret]. I've also sent it to you as a Discord DM. Open the DM from the bot and send that 6-digit code in this DM to complete verification. Any plain message containing the code works. (resent)" If the response does not contain a secret field, treat this as a control-plane error: tell the user something went wrong and ask them to retry from Step 3. After delivering the code, begin the auto-check polling loop (see Auto-Check Polling below).
• Email: The resend response includes a fresh secret field. Show the new code in the current chat: "Your new verification code is [secret]. I've also sent it to your email. Reply to the verification email with only the 6-digit code to complete verification. (resent)" If the response does not contain a secret field, treat this as a control-plane error: tell the user something went wrong and ask them to retry from Step 3. After delivering the code, immediately begin the auto-check polling loop (see Auto-Check Polling below).