twilio-sms

Twilio SMS

Twilio の電話番号や SMS に関する作業に使用します。番号の作成・購入、所有している番号の一覧表示、番号の保持・ラベル付け、テキストメッセージの送信、受信・送信メッセージの確認ができます。

安全性

• Account SID、認証トークン、API シークレット、TOTP コード、または 1Password アイテムの完全な JSON を表示しないでください。
• 実際の電話番号、SID、名前、アカウント固有のアイテム ID をこのスキルに保存しないでください。
• シークレットの読み取りには $one-password を使用してください。op は tmux 内でのみ使用してください。
• デスクトップ版 1Password へのアクセスが必要な場合は、該当コマンドでサービスアカウント認証を解除してください：env -u OP_SERVICE_ACCOUNT_TOKEN op ...。
• 認証情報の形式のみを表示してください：フィールドの有無、長さ、必要に応じてプレフィックスの種類。
• 公開される書き込みやログでは、ユーザーが SMS の内容を読む・確認するよう求めていない限り、メッセージ本文の漏えいを避けてください。

認証情報の確認手順

1. Twilio CLI／プロファイルを確認します：
   • twilio --version または npx -y twilio-cli --version
   • twilio profiles:list または npx -y twilio-cli profiles:list
2. 環境変数の有無のみを確認します：
   • TWILIO_ACCOUNT_SID
   • TWILIO_AUTH_TOKEN
   • 任意の API キー／シークレット変数
3. 環境変数が一部しかない場合は、まず 1Password のメタデータを検索します。
4. 次のフィールドに一致するアイテムを優先します：
   • TWILIO_ACCOUNT_SID
   • TWILIO_AUTH_TOKEN
   • 任意の TWILIO_FROM_NUMBER
5. op で制限付きのボールトしか認識されない場合は、env -u OP_SERVICE_ACCOUNT_TOKEN を付けて、デスクトップ経由での読み取りを再試行します。
6. 購入または送信の前に認証を確認します：

curl -sS -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID.json"

CLI のセットアップ

Twilio CLI のプロファイル作成には、API キーの認証情報だけでなく、アカウントの認証トークンが必要です：

npx -y twilio-cli profiles:create "$TWILIO_ACCOUNT_SID" \
  --auth-token "$TWILIO_AUTH_TOKEN" \
  --profile default --force --silent
npx -y twilio-cli profiles:use default

twilio がインストールされていない場合は、npx -y twilio-cli を使用します。

電話番号

所有している番号の一覧表示：

npx -y twilio-cli api:core:incoming-phone-numbers:list \
  --properties phoneNumber,friendlyName,capabilities

米国のローカル SMS 対応番号を検索：

npx -y twilio-cli api:core:available-phone-numbers:local:list \
  --country-code US --sms-enabled --voice-enabled --limit 5

CLI の形式が扱いにくい場合や必要なフラグがない場合は、REST を使用します：

curl -sS -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/AvailablePhoneNumbers/US/Local.json?SmsEnabled=true&VoiceEnabled=true&PageSize=5"

候補を 1 つ購入：

curl -sS -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
  -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers.json" \
  --data-urlencode "PhoneNumber=$PHONE_NUMBER"

購入後、所有権と機能を確認します。Twilio の JSON ではキーが小文字です：

capabilities.sms
capabilities.mms
capabilities.voice

ユーザーが保持を希望する番号に印を付けます：

npx -y twilio-cli api:core:incoming-phone-numbers:update \
  --sid "$PHONE_NUMBER_SID" \
  --friendly-name "KEEP - <purpose>"

保持ルール：Twilio アカウントに番号が残っており、請求が正常な間は、その番号を保持します。明示的に依頼されない限り、番号を解約・削除しないでください。

SMS

送信：

npx -y twilio-cli api:core:messages:create \
  --from "$FROM_NUMBER" \
  --to "$TO_NUMBER" \
  --body "$BODY" \
  -o json

ステータスを取得：

npx -y twilio-cli api:core:messages:fetch --sid "$MESSAGE_SID" -o json

ある番号への受信メッセージを確認：

npx -y twilio-cli api:core:messages:list \
  --to "$NUMBER" --limit 20 -o json

ある番号からの送信メッセージを確認：

npx -y twilio-cli api:core:messages:list \
  --from "$NUMBER" --limit 20 -o json

Twilio CLI の JSON では、単一リソースのコマンドでも配列が返されることがあります。堅牢に解析してください：

jq 'if type=="array" then .[0] else . end'

補足

• 国際 SMS では、購入した米国の番号ではなく、英数字の送信者名や通信事業者の送信者名が表示される場合があります。
• 米国の SMS にはコンプライアンス要件が適用されることがあります。米国の宛先への送信に失敗した場合、むやみに再試行する前に A2P／10DLC の登録状況を確認してください。
• トライアルアカウントでは、宛先が制限される場合があります。