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 trực tiếp 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 dự án, rồi gọi các action có sẵn từ ứng dụng. 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	Truyền thông	API key	Gửi email giao dịch, gửi email hàng loạt, liệt kê domain đã xác minh
Slack	Truyền thông	OAuth	Đăng tin nhắn, liệt kê kênh và người dùng, thêm reaction, đọc thread
ElevenLabs	AI	API key	Chuyển văn bản thành giọng nói, liệt kê giọng đọc có sẵn, tạo hiệu ứng âm thanh

Thêm nhiều connector đang được bổ sung thường xuyên.

Connectors hoạt động như thế nào

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 dự án — thao tác này cho phép dự án sử dụng thông tin xác thực đó
3. Ứng dụng của bạn gọi các action — yêu cầu đi qua Proyecta Cloud, nơi thông tin xác thực được đưa vào phía server

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

Thiết lập một connector

1. Mở dự án 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 được kiểm tra tự động và đánh dấu Active nếu hợp lệ

Đọc dữ liệu qua connector từ ứng dụng của bạn

Ứng dụng của bạn có thể đọc một API bên thứ ba trực tiếp từ trình duyệt mà API key không bao giờ lọt vào bundle. Thông tin xác thực vẫn được mã hóa và giữ trên nền tảng; ứng dụng của bạn chỉ nêu tên connector, action và một input có kiểu rõ ràng, còn nền tảng sẽ thực hiện lời gọi giúp bạn.

import { useConnectorData, useHttpRead } from '@/hooks/useConnector.ts';

// A connector's own read action, as a cached query
const { data, isLoading, error } = useConnectorData('eleven-labs', 'listVoices');

// The generic HTTP-read connector, by endpoint name
const { data: feed } = useHttpRead('news-feed', { limit: 10 });

Có hai lớp bảo vệ đáng lưu ý, vì chúng được thiết kế có chủ đích:

• Chỉ đọc. Chỉ những action được nền tảng đánh dấu là an toàn cho trình duyệt mới có thể truy cập — mọi thứ khác trả về 403. Các thao tác ghi (đăng bài lên Slack, gửi thư, tính phí thẻ) không bao giờ truy cập được từ trình duyệt.
• Bạn không thể truyền URL hay host. Với connector http-read tổng quát, input là { endpointKey, params }, và URL đứng sau endpointKey do bạn — chủ ứng dụng — cấu hình, chứ không phải do code ứng dụng. Phản hồi được cache ở phía server và bị giới hạn tốc độ, vì key của bên thứ ba được tính theo hạn ngạch.

Mã 404 nghĩa là chủ ứng dụng chưa kết nối connector đó — đây mới là trường hợp đáng xử lý trong giao diện của bạn.

Để AI tự kết nối

Bạn không cần phải tự viết code connector. AI builder biết những connector nào đang được gắn với dự án và có thể tự tạo phần tích hợp cho bạn:

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

Tham chiếu các action của connector

Resend (connectorId: '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 một lúc
listDomains	read	Liệt kê các domain gửi đã xác minh

Slack (connectorId: 'slack')

Action	Tác động	Mô tả
postMessage	write	Đăng một tin nhắn lên kênh
listChannels	read	Liệt kê các kênh trong workspace
listUsers	read	Liệt kê thành viên workspace
reactToMessage	write	Thêm một emoji reaction
getThread	read	Lấy các phản hồi trong một thread

ElevenLabs (connectorId: 'eleven-labs')

Action	Tác động	Mô tả
textToSpeech	write	Chuyển văn bản thành audio giọng nói
listVoices	read	Liệt kê các giọng đọc có sẵn
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 — cập nhật lại để 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 trên mỗi connector trên mỗi dự án
• Mỗi lần gọi action đều được ghi lại với nhật ký kiểm toán đầy đủ (kết nối, action, thời gian thực thi, trạng thái)
• Kết nối có phạm vi 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 dự án 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 dự án 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. Hãy cập nhật thông tin xác thực trong Settings > Connectors để khôi phục.

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

Ứng dụng của bạn không bao giờ nắm giữ chúng. Các action đọc an toàn cho trình duyệt được proxy qua Proyecta Cloud, nơi thông tin xác thực được đưa vào phía server, nên key không bao giờ nằm trong bundle của bạn. Các action ghi hoàn toàn không thể truy cập từ trình duyệt.

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

Chưa có. Định nghĩa connector tùy chỉnh đang nằm trong lộ trình phát triển.

Sắp ra mắt

• Thêm nhiều connector mới (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