Конектори

Підключіть свій застосунок до сторонніх сервісів, таких як Slack, Resend і ElevenLabs. Облікові дані шифруються, а дії автентифікуються заздалегідь.

Конектори дозволяють інтегрувати зовнішні сервіси у ваш застосунок без необхідності управляти API-ключами безпосередньо в коді. Ви налаштовуєте з’єднання один раз, прив’язуєте його до проєкту та викликаєте готові дії з застосунку через Proyecta SDK. Облікові дані шифруються при збереженні і ніколи не потрапляють до вашого frontend-коду.

Доступні конектори

Конектор	Категорія	Тип автентифікації	Що робить
Resend	Комунікації	API-ключ	Надсилання транзакційних листів, масове надсилання, перелік верифікованих доменів
Slack	Комунікації	OAuth	Публікація повідомлень, перелік каналів і користувачів, реакції на повідомлення, читання тредів
ElevenLabs	AI	API-ключ	Перетворення тексту на мовлення, перелік доступних голосів, генерація звукових ефектів

Нові конектори додаються регулярно.

Як працюють конектори

1. Ви створюєте з’єднання — надаєте облікові дані (API-ключ або авторизуєтесь через OAuth)
2. Ви прив’язуєте з’єднання до проєкту — це надає проєкту доступ до цих облікових даних
3. Ваш застосунок викликає дії — SDK надсилає запит через Proyecta Cloud, який додає облікові дані на стороні сервера

Код вашого застосунку ніколи не торкається сирого API-ключа чи OAuth-токена. Система конекторів відповідає за автентифікацію, обмеження частоти запитів і ведення журналу аудиту.

Налаштування конектора

1. Відкрийте свій проєкт у Builder
2. Перейдіть до Settings > Connectors
3. Оберіть конектор з каталогу (наприклад, Resend)
4. Введіть облікові дані:
   • Конектори з API-ключем (Resend, ElevenLabs): вставте свій секретний ключ
   • OAuth-конектори (Slack): увійдіть і надайте доступ
5. Вкажіть назву з’єднання (наприклад, “Production Resend”)
6. З’єднання перевіряється автоматично й позначається як Active, якщо дані коректні

Використання конектора в застосунку

Дії конекторів викликаються з серверного коду (Convex actions) за допомогою 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;
    },
});

Метод execute повертає:

Поле	Опис
output	Повернене значення дії (структура залежить від конкретної дії)
durationMs	Час виконання в мілісекундах
invocationId	Ідентифікатор запису в журналі аудиту

Нехай AI сам підключить конектор

Вам не потрібно писати код конектора вручну. AI Builder знає, які конектори прив’язані до вашого проєкту, і може згенерувати інтеграцію за вас:

• "Send a welcome email when users sign up" — використовує конектор Resend
• "Post a Slack message when a new order comes in" — використовує конектор Slack
• "Play audio narration on the article page" — використовує конектор 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?

Ні. Дії конекторів необхідно викликати з серверного коду (Convex actions), щоб облікові дані залишались у безпеці. SDK маршрутизує запити через Proyecta Cloud, який додає автентифікацію на стороні сервера.

Чи можна додати власні конектори?

Поки що ні. Визначення користувацьких конекторів є у дорожній карті.

Незабаром

• Додаткові конектори (Google, Twilio, SendGrid та інші)
• Визначення користувацьких конекторів — підключайте власні API
• Прийом вебхуків для вхідних подій від підключених сервісів
• OAuth-шлюз — зберігання токенів на стороні сервера навіть для потоків, ініційованих клієнтом