Connectors

Hubungkan aplikasimu ke layanan pihak ketiga seperti Slack, Resend, dan ElevenLabs. Kredensial dienkripsi dan aksi sudah terautentikasi.

Connectors memungkinkan kamu mengintegrasikan layanan eksternal ke dalam aplikasi tanpa harus mengelola API key mentah di dalam kode. Kamu cukup menyiapkan sebuah koneksi sekali, mengikatnya ke proyekmu, lalu memanggil aksi yang sudah tersedia melalui Proyecta SDK. Kredensial dienkripsi saat disimpan dan tidak pernah terekspos ke kode frontend-mu.

Connector yang tersedia

Connector	Kategori	Tipe autentikasi	Fungsinya
Resend	Komunikasi	API key	Kirim email transaksional, kirim email massal, daftar domain terverifikasi
Slack	Komunikasi	OAuth	Kirim pesan, daftar channel dan pengguna, beri reaksi pada pesan, baca thread
ElevenLabs	AI	API key	Text-to-speech, daftar suara yang tersedia, buat efek suara

Connector baru terus ditambahkan secara rutin.

Cara kerja connector

1. Kamu membuat koneksi — berikan kredensial (API key atau masuk melalui OAuth)
2. Kamu mengikat koneksi ke sebuah proyek — ini mengotorisasi proyek untuk menggunakan kredensial tersebut
3. Aplikasimu memanggil aksi — SDK mengirimkan permintaan melalui Proyecta Cloud, yang menyuntikkan kredensial di sisi server

Kode aplikasimu tidak pernah menyentuh API key mentah atau token OAuth. Sistem connector menangani autentikasi, rate limiting, dan audit logging.

Menyiapkan connector

1. Buka proyekmu di builder
2. Buka Settings > Connectors
3. Klik sebuah connector dari katalog (misalnya, Resend)
4. Masukkan kredensialmu:
   • Connector API key (Resend, ElevenLabs): Tempel secret key-mu
   • Connector OAuth (Slack): Masuk dan berikan izin akses
5. Beri nama koneksi tersebut (misalnya, “Production Resend”)
6. Koneksi diuji secara otomatis dan ditandai Active jika valid

Menggunakan connector di aplikasimu

Aksi connector dipanggil dari kode sisi server (Convex actions) menggunakan Proyecta SDK:

'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;
    },
});

Method execute mengembalikan:

Field	Deskripsi
output	Nilai kembalian aksi (bentuknya bergantung pada aksi yang dipanggil)
durationMs	Waktu eksekusi dalam milidetik
invocationId	ID entri audit log

Biarkan AI yang menghubungkannya

Kamu tidak perlu menulis kode connector secara manual. AI builder mengetahui connector mana yang terikat ke proyekmu dan dapat membuat integrasi tersebut untukmu:

• "Send a welcome email when users sign up" — menggunakan connector Resend
• "Post a Slack message when a new order comes in" — menggunakan connector Slack
• "Play audio narration on the article page" — menggunakan connector ElevenLabs

Referensi aksi connector

Resend

Aksi	Efek samping	Deskripsi
sendEmail	write	Kirim satu email transaksional
sendBatch	write	Kirim beberapa email sekaligus
listDomains	read	Daftar domain pengirim yang terverifikasi

Slack

Aksi	Efek samping	Deskripsi
postMessage	write	Kirim pesan ke sebuah channel
listChannels	read	Daftar channel di workspace
listUsers	read	Daftar anggota workspace
reactToMessage	write	Tambahkan reaksi emoji
getThread	read	Ambil balasan dalam sebuah thread

ElevenLabs

Aksi	Efek samping	Deskripsi
textToSpeech	write	Ubah teks menjadi audio suara
listVoices	read	Daftar suara yang tersedia
generateSoundEffect	write	Buat efek suara berbasis AI

Status koneksi

Status	Arti
Active	Kredensial valid dan koneksi siap digunakan
Broken	Kredensial kedaluwarsa atau dicabut — perbarui untuk memulihkan koneksi

Keamanan

• Kredensial dienkripsi dengan AES-256-GCM saat disimpan
• Aksi dibatasi hingga 1.000 permintaan per menit per connector per proyek
• Setiap pemanggilan aksi dicatat dengan audit trail (koneksi, aksi, durasi, status)
• Koneksi berlaku untuk seluruh workspace

FAQ

Bisakah saya menggunakan koneksi yang sama di beberapa proyek?

Bisa. Buat koneksi sekali lalu ikat ke proyek mana pun dalam workspace yang sama.

Apa yang terjadi jika API key saya kedaluwarsa atau dicabut?

Status koneksi berubah menjadi Broken. Perbarui kredensial di Settings > Connectors untuk memulihkannya.

Bisakah saya memanggil aksi connector dari frontend?

Tidak. Aksi connector harus dipanggil dari kode sisi server (Convex actions) agar kredensial tetap aman. SDK merutekan melalui Proyecta Cloud, yang menyuntikkan autentikasi di sisi server.

Bisakah saya menambahkan connector kustom sendiri?

Belum bisa. Definisi connector kustom sudah ada di roadmap.

Segera hadir

• Connector tambahan (Google, Twilio, SendGrid, dan lainnya)
• Definisi connector kustom — bawa API-mu sendiri
• Webhook ingestion untuk event masuk dari layanan yang terhubung
• OAuth gateway — simpan token di sisi server bahkan untuk alur yang dimulai dari klien