From 7b86e084b3609c010575d89f62bfbbeab3b0fb49 Mon Sep 17 00:00:00 2001 From: Noa Flaherty Date: Mon, 23 Feb 2026 20:14:59 -0500 Subject: [PATCH] feat: add chat-based sms-setup skill with catalog wiring Co-Authored-By: Claude --- assistant/README.md | 2 +- .../config/bundled-skills/messaging/SKILL.md | 12 +- .../src/config/vellum-skills/catalog.json | 7 ++ .../config/vellum-skills/sms-setup/SKILL.md | 119 ++++++++++++++++++ skills/catalog.json | 7 ++ skills/sms-setup/SKILL.md | 119 ++++++++++++++++++ 6 files changed, 259 insertions(+), 7 deletions(-) create mode 100644 assistant/src/config/vellum-skills/sms-setup/SKILL.md create mode 100644 skills/sms-setup/SKILL.md diff --git a/assistant/README.md b/assistant/README.md index 123d2e77696..3af35a9a2eb 100644 --- a/assistant/README.md +++ b/assistant/README.md @@ -194,7 +194,7 @@ The `/channels/inbound` endpoint requires a valid `X-Gateway-Origin` header to p ## Twilio Setup Primitive -Twilio is the shared telephony provider for both voice calls and SMS messaging. Configuration is managed through the `twilio_config` IPC contract and the `twilio-setup` skill. +Twilio is the shared telephony provider for both voice calls and SMS messaging. Configuration is managed through the `twilio_config` IPC contract and the `twilio-setup` skill. For SMS-specific onboarding (including compliance verification and test sending), the `sms-setup` skill provides a guided conversational flow that layers on top of `twilio-setup`. ### `twilio_config` IPC Contract diff --git a/assistant/src/config/bundled-skills/messaging/SKILL.md b/assistant/src/config/bundled-skills/messaging/SKILL.md index dc3b1013e18..a8655504aeb 100644 --- a/assistant/src/config/bundled-skills/messaging/SKILL.md +++ b/assistant/src/config/bundled-skills/messaging/SKILL.md @@ -42,14 +42,14 @@ The telegram-setup skill handles: verifying the bot token from @BotFather, gener The telegram-setup skill also includes **guardian verification**, which links your Telegram account as the trusted guardian for the bot. ### SMS (Twilio) -SMS messaging uses Twilio as the telephony provider. Twilio credentials and phone number configuration are shared with the **phone-calls** skill. Load the **twilio-setup** skill to configure Twilio: - - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "twilio-setup"`. - - Then call `skill_load` with `skill: "twilio-setup"`. - - Tell the user: *"I've loaded a setup guide for Twilio. It will walk you through configuring your Twilio account for SMS and voice calls."* +SMS messaging uses Twilio as the telephony provider. Twilio credentials and phone number configuration are shared with the **phone-calls** skill. Load the **sms-setup** skill for complete SMS configuration including compliance and testing: + - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "sms-setup"`. + - Then call `skill_load` with `skill: "sms-setup"`. + - Tell the user: *"I've loaded the SMS setup guide. It will walk you through configuring Twilio, handling compliance requirements, and testing SMS delivery."* -The twilio-setup skill handles: credential storage (Account SID + Auth Token), phone number provisioning or assignment, and public ingress setup. Once Twilio is configured, SMS is available automatically — no additional feature flag is needed. The assistant's Twilio phone number is used for both outbound SMS and voice calls. +The sms-setup skill handles: Twilio credential storage (Account SID + Auth Token), phone number provisioning or assignment, public ingress setup, SMS compliance verification, and end-to-end test sending. Once SMS is set up, messaging is available automatically — no additional feature flag is needed. -The twilio-setup skill also includes optional **guardian verification** for SMS, which links your phone number as the trusted guardian. This is the same guardian concept used by Telegram — it ensures only verified users can approve sensitive operations via SMS. +The sms-setup skill also includes optional **guardian verification** for SMS (inherited from twilio-setup), which links your phone number as the trusted guardian. ## Platform Selection diff --git a/assistant/src/config/vellum-skills/catalog.json b/assistant/src/config/vellum-skills/catalog.json index 4e0e8665f0f..1f39bdcc7c1 100644 --- a/assistant/src/config/vellum-skills/catalog.json +++ b/assistant/src/config/vellum-skills/catalog.json @@ -47,6 +47,13 @@ "description": "Configure Twilio credentials and phone numbers for voice calls and SMS messaging", "emoji": "\ud83d\udcf1", "includes": ["public-ingress"] + }, + { + "id": "sms-setup", + "name": "SMS Setup", + "description": "Set up and troubleshoot SMS messaging with guided Twilio configuration, compliance, and verification", + "emoji": "\ud83d\udce8", + "includes": ["twilio-setup"] } ] } diff --git a/assistant/src/config/vellum-skills/sms-setup/SKILL.md b/assistant/src/config/vellum-skills/sms-setup/SKILL.md new file mode 100644 index 00000000000..35eeaa3801a --- /dev/null +++ b/assistant/src/config/vellum-skills/sms-setup/SKILL.md @@ -0,0 +1,119 @@ +--- +name: "SMS Setup" +description: "Set up and troubleshoot SMS messaging with guided Twilio configuration, compliance, and verification" +user-invocable: true +includes: ["twilio-setup"] +metadata: {"vellum": {"emoji": "\ud83d\udce8"}} +--- + +You are helping your user set up SMS messaging. This skill orchestrates Twilio setup, SMS-specific compliance, and end-to-end testing through a conversational flow. + +## Step 1: Check Channel Readiness + +First, check the current SMS channel readiness state by sending the `channel_readiness` IPC message: + +```json +{ + "type": "channel_readiness", + "action": "get", + "channel": "sms" +} +``` + +Inspect the `channel_readiness_response`. The response contains `snapshots` with each channel's readiness state. + +- If the SMS channel shows `ready: true` and all `localChecks` pass, skip to Step 3. +- If any local checks fail, proceed to Step 2 to fix the baseline. + +## Step 2: Establish Baseline (Twilio Setup) + +If SMS baseline is not ready (missing credentials, phone number, or ingress), load the `twilio-setup` skill to walk the user through the basics: + +``` +skill_load skill=twilio-setup +``` + +Tell the user: *"SMS needs Twilio configured first. I've loaded the Twilio setup guide — let's walk through it."* + +After twilio-setup completes, re-check readiness: + +```json +{ + "type": "channel_readiness", + "action": "refresh", + "channel": "sms" +} +``` + +If baseline is still not ready, report the specific failures and ask the user to address them before continuing. + +## Step 3: Remote Compliance Check + +Once baseline is ready, run a full readiness check including remote (Twilio API) checks: + +```json +{ + "type": "channel_readiness", + "action": "refresh", + "channel": "sms", + "includeRemote": true +} +``` + +Examine the remote check results: +- If all remote checks pass, proceed to Step 4. +- If compliance issues are found (e.g., toll-free verification needed), guide the user through the compliance flow: + 1. Check compliance status using the `twilio_config` IPC with `action: "sms_compliance_status"` (if available). + 2. If toll-free verification is needed, collect user information and submit via `twilio_config` with `action: "sms_submit_tollfree_verification"`. + 3. Report verification status and next steps. + +**Note:** Compliance actions (sms_compliance_status, sms_submit_tollfree_verification, etc.) may not be available yet. If the IPC action is not recognized, tell the user: *"Compliance automation isn't available yet. You may need to check Twilio Console manually for toll-free verification status."* + +### Data Collection for Verification (Individual-First) + +When collecting information for toll-free verification: +- Assume the user is an **individual / sole proprietor** by default +- Do NOT ask for EIN, business registration number, or business registration authority +- Explain that Twilio labels some fields as "business" fields even for individual submitters +- Only collect what's required: business name (can be personal name), website (can be personal site), notification email, use case, message samples, opt-in info +- If Twilio rejects the submission requiring business registration, explain the situation and guide through the fallback path + +## Step 4: Test Send + +Run a test SMS to verify end-to-end delivery: + +Tell the user: *"Let's send a test SMS to verify everything works. What phone number should I send the test to?"* + +After the user provides a number, send a test message using the messaging tools: +- Use `messaging_send` with `platform: "sms"`, `conversation_id: ""`, and a test message like "Test SMS from your Vellum assistant." +- Report the result honestly: + - If the send succeeds: *"The message was accepted by Twilio. Note: 'accepted' means Twilio received it for delivery, not that it reached the handset yet. Delivery can take a few seconds to a few minutes."* + - If the send fails: report the error and suggest troubleshooting steps + +## Step 5: Final Status Report + +After completing (or skipping) the test, present a clear summary: + +**If everything passed:** +*"SMS is ready! Here's your setup status:"* +- Twilio credentials: configured +- Phone number: {number} +- Ingress: configured +- Compliance: {status} +- Test send: {result} + +**If there are blockers:** +*"SMS setup is partially complete. Here's what still needs attention:"* +- List each blocker with the specific next action + +## Troubleshooting + +If the user returns to this skill after initial setup: +1. Always start with Step 1 (readiness check) to assess current state +2. Skip steps that are already complete +3. Focus on the specific issue the user is experiencing + +Common issues: +- **"Messages not delivering"** — Check compliance status, verify the number isn't flagged +- **"Twilio error on send"** — Check credentials, phone number assignment, and ingress +- **"Trial account limitations"** — Explain that trial accounts can only send to verified numbers diff --git a/skills/catalog.json b/skills/catalog.json index 4e0e8665f0f..1f39bdcc7c1 100644 --- a/skills/catalog.json +++ b/skills/catalog.json @@ -47,6 +47,13 @@ "description": "Configure Twilio credentials and phone numbers for voice calls and SMS messaging", "emoji": "\ud83d\udcf1", "includes": ["public-ingress"] + }, + { + "id": "sms-setup", + "name": "SMS Setup", + "description": "Set up and troubleshoot SMS messaging with guided Twilio configuration, compliance, and verification", + "emoji": "\ud83d\udce8", + "includes": ["twilio-setup"] } ] } diff --git a/skills/sms-setup/SKILL.md b/skills/sms-setup/SKILL.md new file mode 100644 index 00000000000..35eeaa3801a --- /dev/null +++ b/skills/sms-setup/SKILL.md @@ -0,0 +1,119 @@ +--- +name: "SMS Setup" +description: "Set up and troubleshoot SMS messaging with guided Twilio configuration, compliance, and verification" +user-invocable: true +includes: ["twilio-setup"] +metadata: {"vellum": {"emoji": "\ud83d\udce8"}} +--- + +You are helping your user set up SMS messaging. This skill orchestrates Twilio setup, SMS-specific compliance, and end-to-end testing through a conversational flow. + +## Step 1: Check Channel Readiness + +First, check the current SMS channel readiness state by sending the `channel_readiness` IPC message: + +```json +{ + "type": "channel_readiness", + "action": "get", + "channel": "sms" +} +``` + +Inspect the `channel_readiness_response`. The response contains `snapshots` with each channel's readiness state. + +- If the SMS channel shows `ready: true` and all `localChecks` pass, skip to Step 3. +- If any local checks fail, proceed to Step 2 to fix the baseline. + +## Step 2: Establish Baseline (Twilio Setup) + +If SMS baseline is not ready (missing credentials, phone number, or ingress), load the `twilio-setup` skill to walk the user through the basics: + +``` +skill_load skill=twilio-setup +``` + +Tell the user: *"SMS needs Twilio configured first. I've loaded the Twilio setup guide — let's walk through it."* + +After twilio-setup completes, re-check readiness: + +```json +{ + "type": "channel_readiness", + "action": "refresh", + "channel": "sms" +} +``` + +If baseline is still not ready, report the specific failures and ask the user to address them before continuing. + +## Step 3: Remote Compliance Check + +Once baseline is ready, run a full readiness check including remote (Twilio API) checks: + +```json +{ + "type": "channel_readiness", + "action": "refresh", + "channel": "sms", + "includeRemote": true +} +``` + +Examine the remote check results: +- If all remote checks pass, proceed to Step 4. +- If compliance issues are found (e.g., toll-free verification needed), guide the user through the compliance flow: + 1. Check compliance status using the `twilio_config` IPC with `action: "sms_compliance_status"` (if available). + 2. If toll-free verification is needed, collect user information and submit via `twilio_config` with `action: "sms_submit_tollfree_verification"`. + 3. Report verification status and next steps. + +**Note:** Compliance actions (sms_compliance_status, sms_submit_tollfree_verification, etc.) may not be available yet. If the IPC action is not recognized, tell the user: *"Compliance automation isn't available yet. You may need to check Twilio Console manually for toll-free verification status."* + +### Data Collection for Verification (Individual-First) + +When collecting information for toll-free verification: +- Assume the user is an **individual / sole proprietor** by default +- Do NOT ask for EIN, business registration number, or business registration authority +- Explain that Twilio labels some fields as "business" fields even for individual submitters +- Only collect what's required: business name (can be personal name), website (can be personal site), notification email, use case, message samples, opt-in info +- If Twilio rejects the submission requiring business registration, explain the situation and guide through the fallback path + +## Step 4: Test Send + +Run a test SMS to verify end-to-end delivery: + +Tell the user: *"Let's send a test SMS to verify everything works. What phone number should I send the test to?"* + +After the user provides a number, send a test message using the messaging tools: +- Use `messaging_send` with `platform: "sms"`, `conversation_id: ""`, and a test message like "Test SMS from your Vellum assistant." +- Report the result honestly: + - If the send succeeds: *"The message was accepted by Twilio. Note: 'accepted' means Twilio received it for delivery, not that it reached the handset yet. Delivery can take a few seconds to a few minutes."* + - If the send fails: report the error and suggest troubleshooting steps + +## Step 5: Final Status Report + +After completing (or skipping) the test, present a clear summary: + +**If everything passed:** +*"SMS is ready! Here's your setup status:"* +- Twilio credentials: configured +- Phone number: {number} +- Ingress: configured +- Compliance: {status} +- Test send: {result} + +**If there are blockers:** +*"SMS setup is partially complete. Here's what still needs attention:"* +- List each blocker with the specific next action + +## Troubleshooting + +If the user returns to this skill after initial setup: +1. Always start with Step 1 (readiness check) to assess current state +2. Skip steps that are already complete +3. Focus on the specific issue the user is experiencing + +Common issues: +- **"Messages not delivering"** — Check compliance status, verify the number isn't flagged +- **"Twilio error on send"** — Check credentials, phone number assignment, and ingress +- **"Trial account limitations"** — Explain that trial accounts can only send to verified numbers