Connectors

Połącz swoją aplikację z usługami zewnętrznymi, takimi jak Slack, Resend i ElevenLabs. Dane uwierzytelniające są szyfrowane, a akcje są wstępnie uwierzytelnione.

Connectors pozwalają integrować zewnętrzne usługi z Twoją aplikacją bez konieczności zarządzania surowymi kluczami API w kodzie. Konfigurujesz połączenie raz, przypisujesz je do projektu i wywołujesz gotowe akcje z aplikacji za pośrednictwem Proyecta SDK. Dane uwierzytelniające są szyfrowane w spoczynku i nigdy nie są udostępniane kodowi frontend.

Dostępne connectors

Connector	Kategoria	Typ uwierzytelnienia	Co robi
Resend	Komunikacja	Klucz API	Wysyłanie e-maili transakcyjnych, wysyłanie e-maili wsadowych, lista zweryfikowanych domen
Slack	Komunikacja	OAuth	Publikowanie wiadomości, lista kanałów i użytkowników, reagowanie na wiadomości, odczytywanie wątków
ElevenLabs	AI	Klucz API	Zamiana tekstu na mowę, lista dostępnych głosów, generowanie efektów dźwiękowych

Nowe connectors są regularnie dodawane.

Jak działają connectors

1. Tworzysz połączenie — podajesz dane uwierzytelniające (klucz API lub logujesz się przez OAuth)
2. Przypisujesz połączenie do projektu — autoryzujesz projekt do korzystania z tych danych uwierzytelniających
3. Twoja aplikacja wywołuje akcje — SDK wysyła żądanie przez Proyecta Cloud, który wstrzykuje dane uwierzytelniające po stronie serwera

Kod Twojej aplikacji nigdy nie dotyka surowego klucza API ani tokenu OAuth. System connectors obsługuje uwierzytelnianie, ograniczanie liczby żądań i rejestrowanie operacji.

Konfiguracja connectora

1. Otwórz projekt w builderze
2. Przejdź do Settings > Connectors
3. Kliknij connector z katalogu (np. Resend)
4. Wprowadź dane uwierzytelniające:
   • Connectors z kluczem API (Resend, ElevenLabs): Wklej swój tajny klucz
   • Connectors OAuth (Slack): Zaloguj się i autoryzuj dostęp
5. Nadaj połączeniu nazwę (np. „Production Resend”)
6. Połączenie jest testowane automatycznie i oznaczane jako Active, jeśli jest prawidłowe

Użycie connectora w aplikacji

Akcje connectorów są wywoływane z kodu po stronie serwera (akcje Convex) przy użyciu 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;
    },
});

Metoda execute zwraca:

Pole	Opis
output	Wartość zwrócona przez akcję (struktura zależy od akcji)
durationMs	Czas wykonania w milisekundach
invocationId	Identyfikator wpisu w logu audytowym

Pozwól AI wszystko połączyć

Nie musisz pisać kodu connectorów ręcznie. Builder AI wie, które connectors są przypisane do Twojego projektu i może wygenerować integrację za Ciebie:

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

Dokumentacja akcji connectorów

Resend

Akcja	Efekty uboczne	Opis
sendEmail	zapis	Wysyła pojedynczy e-mail transakcyjny
sendBatch	zapis	Wysyła wiele e-maili jednocześnie
listDomains	odczyt	Wyświetla listę zweryfikowanych domen nadawczych

Slack

Akcja	Efekty uboczne	Opis
postMessage	zapis	Publikuje wiadomość na kanale
listChannels	odczyt	Wyświetla listę kanałów w przestrzeni roboczej
listUsers	odczyt	Wyświetla listę członków przestrzeni roboczej
reactToMessage	zapis	Dodaje reakcję emoji
getThread	odczyt	Pobiera odpowiedzi w wątku

ElevenLabs

Akcja	Efekty uboczne	Opis
textToSpeech	zapis	Konwertuje tekst na dźwięk mowy
listVoices	odczyt	Wyświetla listę dostępnych głosów
generateSoundEffect	zapis	Generuje efekt dźwiękowy AI

Statusy połączeń

Status	Znaczenie
Active	Dane uwierzytelniające są prawidłowe i połączenie jest gotowe do użycia
Broken	Dane uwierzytelniające wygasły lub zostały odwołane — zaktualizuj je, aby przywrócić połączenie

Bezpieczeństwo

• Dane uwierzytelniające są szyfrowane w spoczynku przy użyciu AES-256-GCM
• Akcje są ograniczone do 1 000 żądań na minutę na connector na projekt
• Każde wywołanie akcji jest rejestrowane w logu audytowym (połączenie, akcja, czas trwania, status)
• Połączenia są ograniczone do całej przestrzeni roboczej

FAQ

Czy mogę używać tego samego połączenia w wielu projektach?

Tak. Utwórz połączenie raz i przypisz je do dowolnej liczby projektów w tej samej przestrzeni roboczej.

Co się stanie, jeśli mój klucz API wygaśnie lub zostanie odwołany?

Status połączenia zmienia się na Broken. Zaktualizuj dane uwierzytelniające w Settings > Connectors, aby przywrócić połączenie.

Czy mogę wywoływać akcje connectorów z frontendu?

Nie. Akcje connectorów muszą być wywoływane z kodu po stronie serwera (akcje Convex), aby zapewnić bezpieczeństwo danych uwierzytelniających. SDK kieruje żądania przez Proyecta Cloud, który wstrzykuje uwierzytelnianie po stronie serwera.

Czy mogę dodawać własne connectors?

Jeszcze nie. Definicje niestandardowych connectorów są w planach rozwoju.

Wkrótce

• Dodatkowe connectors (Google, Twilio, SendGrid i inne)
• Definicje niestandardowych connectorów — podłącz własne API
• Webhook ingestion dla zdarzeń przychodzących z połączonych usług
• OAuth gateway — przechowuj tokeny po stronie serwera nawet dla przepływów inicjowanych przez klienta