Connectors

Slack, Resend, ElevenLabs 등 서드파티 서비스를 앱에 연결하세요. 자격 증명은 암호화되며 액션은 사전 인증됩니다.

Connectors를 사용하면 코드에서 API 키를 직접 관리하지 않고도 외부 서비스를 앱에 통합할 수 있습니다. 연결을 한 번 설정하고 프로젝트에 바인딩한 다음, Proyecta SDK를 통해 앱에서 미리 빌드된 액션을 호출하면 됩니다. 자격 증명은 저장 시 암호화되며 frontend 코드에는 절대 노출되지 않습니다.

사용 가능한 커넥터

커넥터	카테고리	인증 방식	기능
Resend	커뮤니케이션	API 키	트랜잭션 이메일 발송, 배치 이메일 발송, 인증된 도메인 목록 조회
Slack	커뮤니케이션	OAuth	메시지 게시, 채널 및 사용자 목록 조회, 메시지 반응, 스레드 읽기
ElevenLabs	AI	API 키	텍스트 음성 변환(TTS), 사용 가능한 보이스 목록 조회, 사운드 이펙트 생성

더 많은 커넥터가 지속적으로 추가되고 있습니다.

커넥터 작동 방식

1. 연결을 생성합니다 — 자격 증명을 제공합니다 (API 키 또는 OAuth를 통한 로그인)
2. 연결을 프로젝트에 바인딩합니다 — 해당 프로젝트가 자격 증명을 사용할 수 있도록 권한을 부여합니다
3. 앱에서 액션을 호출합니다 — SDK가 Proyecta Cloud를 통해 요청을 전송하며, 자격 증명은 server-side에서 주입됩니다

앱 코드는 원시 API 키나 OAuth 토큰에 직접 접근하지 않습니다. 커넥터 시스템이 인증, 요청 제한, 감사 로깅을 모두 처리합니다.

커넥터 설정하기

1. Builder에서 프로젝트를 엽니다
2. Settings > Connectors로 이동합니다
3. 카탈로그에서 커넥터를 클릭합니다 (예: Resend)
4. 자격 증명을 입력합니다:
   • API 키 커넥터 (Resend, ElevenLabs): 시크릿 키를 붙여넣습니다
   • OAuth 커넥터 (Slack): 로그인 후 접근 권한을 허용합니다
5. 연결에 이름을 지정합니다 (예: “Production Resend”)
6. 연결이 자동으로 테스트되며, 유효한 경우 Active 상태로 표시됩니다

앱에서 커넥터 사용하기

커넥터 액션은 Proyecta SDK를 사용하여 server-side 코드 (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,000건으로 요청이 제한됩니다
• 모든 액션 호출은 감사 추적과 함께 기록됩니다 (연결, 액션, 실행 시간, 상태)
• 연결은 전체 워크스페이스 범위로 적용됩니다

자주 묻는 질문

여러 프로젝트에서 동일한 연결을 사용할 수 있나요?

네. 연결을 한 번 생성한 후 같은 워크스페이스 내 여러 프로젝트에 바인딩할 수 있습니다.

API 키가 만료되거나 취소되면 어떻게 되나요?

연결 상태가 Broken으로 변경됩니다. Settings > Connectors에서 자격 증명을 업데이트하여 복원하세요.

frontend에서 커넥터 액션을 호출할 수 있나요?

아니요. 자격 증명을 안전하게 보호하려면 커넥터 액션은 반드시 server-side 코드 (Convex 액션)에서 호출해야 합니다. SDK는 Proyecta Cloud를 통해 요청을 라우팅하며, 인증은 server-side에서 주입됩니다.

커스텀 커넥터를 직접 추가할 수 있나요?

아직은 불가능합니다. 커스텀 커넥터 정의 기능은 로드맵에 포함되어 있습니다.

출시 예정

• 추가 커넥터 (Google, Twilio, SendGrid 등)
• 커스텀 커넥터 정의 — 직접 만든 API 연결
• 연결된 서비스로부터 들어오는 이벤트를 위한 웹훅 수신
• OAuth 게이트웨이 — 클라이언트에서 시작된 흐름에서도 토큰을 server-side에서 유지