コネクター

Slack、Resend、ElevenLabsなどのサードパーティサービスをアプリに接続します。認証情報は暗号化され、アクションは事前に認証済みです。

コネクターを使うと、コード内で生のAPIキーを管理することなく、外部サービスをアプリに統合できます。接続を一度設定してプロジェクトにバインドすれば、Proyecta SDKを通じてアプリから事前構築済みのアクションを呼び出せます。認証情報は保存時に暗号化され、frontendのコードに公開されることはありません。

利用可能なコネクター

コネクター	カテゴリ	認証タイプ	機能
Resend	コミュニケーション	APIキー	トランザクションメール送信、バッチメール送信、確認済みドメイン一覧取得
Slack	コミュニケーション	OAuth	メッセージ投稿、チャンネル・ユーザー一覧取得、メッセージへのリアクション、スレッドの読み取り
ElevenLabs	AI	APIキー	テキスト読み上げ、利用可能な音声一覧取得、効果音生成

コネクターは随時追加されています。

コネクターの仕組み

接続を作成する — 認証情報（APIキー）を入力するか、OAuthでサインインする
接続をプロジェクトにバインドする — プロジェクトがその認証情報を使用することを許可する
アプリからアクションを呼び出す — SDKがリクエストをProyecta Cloudに送信し、サーバーサイドで認証情報が注入される

アプリのコードが生のAPIキーやOAuthトークンに直接触れることはありません。コネクターシステムが認証、レート制限、監査ログを処理します。

コネクターの設定

builderでプロジェクトを開く
Settings > Connectors に移動する
カタログからコネクターをクリックする（例：Resend）
認証情報を入力する：
- APIキー方式（Resend、ElevenLabs）：シークレットキーを貼り付ける
- OAuth方式（Slack）：サインインしてアクセスを承認する
接続に名前を付ける（例：“Production Resend”）
接続は自動的にテストされ、有効であれば Active とマークされる

アプリでコネクターを使用する

コネクターのアクションは、Proyecta SDKを使用してサーバーサイドのコード（Convex アクション）から呼び出します：

'use node';
import { action } from './_generated/server';
import { v } from 'convex/values';
import Proyecta from '@proyecta-ai/sdk';

const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY ?? null });

export const notifySlack = action({
    args: {
        message: v.string(),
    },
    handler: async (ctx, args) => {
        const result = await proyecta.connectors.execute({
            connectorId: 'slack',
            actionId: 'postMessage',
            input: {
                channel: '#general',
                text: args.message,
            },
        });
        return result.output;
    },
});

execute メソッドの戻り値：

フィールド	説明
`output`	アクションの戻り値（形式はアクションによって異なります）
`durationMs`	実行時間（ミリ秒）
`invocationId`	監査ログエントリーID

AIに接続コードを生成させる

コネクターのコードを手書きする必要はありません。AI builderはプロジェクトにバインドされているコネクターを把握しており、統合コードを自動生成できます：

"ユーザーがサインアップしたときにウェルカムメールを送る" — Resend コネクターを使用
"新しい注文が入ったときにSlackにメッセージを投稿する" — Slack コネクターを使用
"記事ページで音声ナレーションを再生する" — ElevenLabs コネクターを使用

コネクターアクションのリファレンス

Resend

アクション	副作用	説明
`sendEmail`	write	単一のトランザクションメールを送信する
`sendBatch`	write	複数のメールを一括送信する
`listDomains`	read	確認済みの送信ドメイン一覧を取得する

Slack

アクション	副作用	説明
`postMessage`	write	チャンネルにメッセージを投稿する
`listChannels`	read	ワークスペースのチャンネル一覧を取得する
`listUsers`	read	ワークスペースのメンバー一覧を取得する
`reactToMessage`	write	絵文字リアクションを追加する
`getThread`	read	スレッドの返信を取得する

ElevenLabs

アクション	副作用	説明
`textToSpeech`	write	テキストを音声オーディオに変換する
`listVoices`	read	利用可能な音声一覧を取得する
`generateSoundEffect`	write	AIが効果音を生成する

接続ステータス

ステータス	意味
Active	認証情報が有効で、接続は使用可能な状態です
Broken	認証情報が期限切れまたは無効化されています — 更新して復旧してください

セキュリティ

認証情報は保存時にAES-256-GCMで暗号化されます
アクションはコネクター・プロジェクトごとに1分間あたり1,000リクエストにレート制限されています
すべてのアクション呼び出しは監査証跡とともにログに記録されます（接続、アクション、実行時間、ステータス）
接続はワークスペース全体にスコープされます

よくある質問

同じ接続を複数のプロジェクトで使用できますか？

はい。接続を一度作成すれば、同じワークスペース内の任意の数のプロジェクトにバインドできます。

APIキーが期限切れになったり無効化されたりするとどうなりますか？

接続ステータスが Broken に変わります。Settings > Connectors で認証情報を更新して復旧してください。

frontendからコネクターのアクションを呼び出せますか？

いいえ。認証情報を安全に保つため、コネクターのアクションはサーバーサイドのコード（Convex アクション）から呼び出す必要があります。SDKはProyecta Cloudを経由してルーティングし、サーバーサイドで認証を注入します。

カスタムコネクターを追加できますか？

現時点ではできません。カスタムコネクター定義はロードマップに含まれています。

近日公開予定

追加コネクター（Google、Twilio、SendGridなど）
カスタムコネクター定義 — 独自のAPIを持ち込む
接続済みサービスからの受信イベント向けWebhookインジェスション
OAuthゲートウェイ — クライアント起点のフローでもトークンをサーバーサイドで保持