Connectors

Kết nối ứng dụng của bạn với các dịch vụ bên thứ ba như Slack, Resend và ElevenLabs. Thông tin xác thực được mã hóa và các action đã được xác thực sẵn.

Connectors cho phép bạn tích hợp các dịch vụ bên ngoài vào ứng dụng mà không cần quản lý API key thô trong code. Bạn chỉ cần thiết lập một kết nối một lần, gắn nó vào project, rồi gọi các action dựng sẵn từ ứng dụng thông qua Proyecta SDK. Thông tin xác thực được mã hóa khi lưu trữ và không bao giờ bị lộ ra frontend.

Các connector hiện có

Connector	Danh mục	Kiểu xác thực	Chức năng
Resend	Giao tiếp	API key	Gửi email giao dịch, gửi email hàng loạt, liệt kê các domain đã xác minh
Slack	Giao tiếp	OAuth	Đăng tin nhắn, liệt kê kênh và người dùng, react tin nhắn, đọc thread
ElevenLabs	AI	API key	Chuyển văn bản thành giọng nói, liệt kê giọng đọc, tạo hiệu ứng âm thanh

Nhiều connector hơn đang được bổ sung thường xuyên.

Cách connector hoạt động

1. Bạn tạo một kết nối — cung cấp thông tin xác thực (API key hoặc đăng nhập qua OAuth)
2. Bạn gắn kết nối vào một project — việc này cấp quyền cho project sử dụng thông tin xác thực đó
3. Ứng dụng của bạn gọi các action — SDK gửi yêu cầu qua Proyecta Cloud, nơi sẽ inject thông tin xác thực ở phía server

Code ứng dụng của bạn không bao giờ chạm vào API key thô hay OAuth token. Hệ thống connector xử lý xác thực, rate limiting và ghi nhật ký kiểm tra.

Thiết lập connector

1. Mở project của bạn trong builder
2. Vào Settings > Connectors
3. Nhấp vào một connector trong danh mục (ví dụ: Resend)
4. Nhập thông tin xác thực:
   • Connector dùng API key (Resend, ElevenLabs): Dán secret key của bạn vào
   • Connector dùng OAuth (Slack): Đăng nhập và cấp quyền truy cập
5. Đặt tên cho kết nối (ví dụ: “Production Resend”)
6. Kết nối sẽ được kiểm tra tự động và đánh dấu Active nếu hợp lệ

Dùng connector trong ứng dụng

Các connector action được gọi từ code phía server (Convex actions) bằng 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;
    },
});

Phương thức execute trả về:

Trường	Mô tả
output	Giá trị trả về của action (cấu trúc tùy thuộc vào từng action)
durationMs	Thời gian thực thi tính bằng mili giây
invocationId	ID bản ghi nhật ký kiểm tra

Để AI tự kết nối

Bạn không cần tự viết code connector bằng tay. AI builder biết connector nào đang được gắn vào project của bạn và có thể tự tạo phần tích hợp cho bạn:

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

Tham chiếu các connector action

Resend

Action	Tác động	Mô tả
sendEmail	write	Gửi một email giao dịch đơn lẻ
sendBatch	write	Gửi nhiều email cùng lúc
listDomains	read	Liệt kê các domain gửi đã xác minh

Slack

Action	Tác động	Mô tả
postMessage	write	Đăng tin nhắn vào một kênh
listChannels	read	Liệt kê các kênh trong workspace
listUsers	read	Liệt kê các thành viên workspace
reactToMessage	write	Thêm biểu tượng cảm xúc vào tin nhắn
getThread	read	Lấy các phản hồi trong một thread

ElevenLabs

Action	Tác động	Mô tả
textToSpeech	write	Chuyển đổi văn bản thành âm thanh giọng nói
listVoices	read	Liệt kê các giọng đọc hiện có
generateSoundEffect	write	Tạo hiệu ứng âm thanh bằng AI

Trạng thái kết nối

Trạng thái	Ý nghĩa
Active	Thông tin xác thực hợp lệ và kết nối sẵn sàng sử dụng
Broken	Thông tin xác thực đã hết hạn hoặc bị thu hồi — hãy cập nhật để khôi phục

Bảo mật

• Thông tin xác thực được mã hóa bằng AES-256-GCM khi lưu trữ
• Các action bị giới hạn tốc độ ở mức 1.000 yêu cầu mỗi phút cho mỗi connector trên mỗi project
• Mỗi lần gọi action đều được ghi lại với nhật ký kiểm tra đầy đủ (kết nối, action, thời gian thực thi, trạng thái)
• Các kết nối có phạm vi cho toàn bộ workspace

Câu hỏi thường gặp

Tôi có thể dùng cùng một kết nối cho nhiều project không?

Có. Tạo kết nối một lần và gắn nó vào bất kỳ số lượng project nào trong cùng một workspace.

Điều gì xảy ra nếu API key của tôi hết hạn hoặc bị thu hồi?

Trạng thái kết nối sẽ chuyển sang Broken. Cập nhật thông tin xác thực trong Settings > Connectors để khôi phục.

Tôi có thể gọi connector action từ frontend không?

Không. Connector action phải được gọi từ code phía server (Convex actions) để giữ an toàn cho thông tin xác thực. SDK định tuyến qua Proyecta Cloud, nơi inject xác thực ở phía server.

Tôi có thể thêm connector tùy chỉnh của riêng mình không?

Chưa được. Tính năng định nghĩa connector tùy chỉnh đang có trong lộ trình phát triển.

Sắp ra mắt

• Thêm nhiều connector (Google, Twilio, SendGrid và nhiều hơn nữa)
• Định nghĩa connector tùy chỉnh — tích hợp API của riêng bạn
• Webhook ingestion cho các sự kiện đến từ các dịch vụ đã kết nối
• OAuth gateway — giữ token ở phía server ngay cả với các luồng do client khởi tạo