Connectors

Conecte seu app a serviços de terceiros como Slack, Resend e ElevenLabs. As credenciais são criptografadas e as ações são pré-autenticadas.

Os Connectors permitem integrar serviços externos ao seu app sem precisar gerenciar chaves de API brutas no código. Você configura uma conexão uma vez, vincula-a ao seu projeto e chama ações pré-construídas a partir do seu app através do Proyecta SDK. As credenciais são criptografadas em repouso e nunca ficam expostas ao seu código de frontend.

Connectors disponíveis

Connector	Categoria	Tipo de autenticação	O que faz
Resend	Comunicações	API key	Enviar e-mail transacional, enviar e-mails em lote, listar domínios verificados
Slack	Comunicações	OAuth	Postar mensagens, listar canais e usuários, reagir a mensagens, ler threads
ElevenLabs	IA	API key	Texto para voz, listar vozes disponíveis, gerar efeitos sonoros

Novos connectors são adicionados regularmente.

Como os Connectors funcionam

1. Você cria uma conexão — fornece as credenciais (uma API key ou faz login via OAuth)
2. Você vincula a conexão a um projeto — isso autoriza o projeto a usar essas credenciais
3. Seu app chama as ações — o SDK envia a requisição através do Proyecta Cloud, que injeta as credenciais no lado do servidor

O código do seu app nunca toca a API key bruta nem o token OAuth. O sistema de Connectors cuida da autenticação, limitação de taxa e registro de auditoria.

Configurar um Connector

1. Abra seu projeto no builder
2. Vá em Settings > Connectors
3. Clique em um connector do catálogo (ex.: Resend)
4. Insira suas credenciais:
   • Connectors por API key (Resend, ElevenLabs): Cole sua chave secreta
   • Connectors OAuth (Slack): Faça login e autorize o acesso
5. Dê um nome à conexão (ex.: “Production Resend”)
6. A conexão é testada automaticamente e marcada como Active se for válida

Usar um Connector no seu app

As ações dos Connectors são chamadas a partir de código server-side (actions do Convex) usando o 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;
    },
});

O método execute retorna:

Campo	Descrição
output	O valor de retorno da ação (o formato depende da ação)
durationMs	Tempo de execução em milissegundos
invocationId	ID da entrada no registro de auditoria

Deixe a IA configurar tudo

Você não precisa escrever o código do connector manualmente. O builder de IA sabe quais connectors estão vinculados ao seu projeto e pode gerar a integração para você:

• "Enviar um e-mail de boas-vindas quando usuários se cadastrarem" — usa o connector Resend
• "Postar uma mensagem no Slack quando um novo pedido chegar" — usa o connector Slack
• "Reproduzir narração em áudio na página do artigo" — usa o connector ElevenLabs

Referência de ações dos Connectors

Resend

Ação	Efeitos colaterais	Descrição
sendEmail	write	Enviar um único e-mail transacional
sendBatch	write	Enviar vários e-mails de uma vez
listDomains	read	Listar domínios de envio verificados

Slack

Ação	Efeitos colaterais	Descrição
postMessage	write	Postar uma mensagem em um canal
listChannels	read	Listar canais do workspace
listUsers	read	Listar membros do workspace
reactToMessage	write	Adicionar uma reação com emoji
getThread	read	Obter respostas de uma thread

ElevenLabs

Ação	Efeitos colaterais	Descrição
textToSpeech	write	Converter texto em áudio de voz
listVoices	read	Listar vozes disponíveis
generateSoundEffect	write	Gerar um efeito sonoro com IA

Status das conexões

Status	Significado
Active	As credenciais são válidas e a conexão está pronta para uso
Broken	As credenciais expiraram ou foram revogadas — atualize-as para restaurar

Segurança

• As credenciais são criptografadas com AES-256-GCM em repouso
• As ações têm limite de 1.000 requisições por minuto por connector por projeto
• Toda chamada de ação é registrada com trilha de auditoria (conexão, ação, duração, status)
• As conexões têm escopo para todo o workspace

Perguntas frequentes

Posso usar a mesma conexão em vários projetos?

Sim. Crie a conexão uma vez e vincule-a a quantos projetos quiser dentro do mesmo workspace.

O que acontece se minha API key expirar ou for revogada?

O status da conexão muda para Broken. Atualize as credenciais em Settings > Connectors para restaurá-la.

Posso chamar ações de connectors a partir do frontend?

Não. As ações de connectors devem ser chamadas a partir de código server-side (actions do Convex) para manter as credenciais seguras. O SDK roteia as requisições pelo Proyecta Cloud, que injeta a autenticação no lado do servidor.

Posso adicionar meus próprios connectors personalizados?

Ainda não. Definições de connectors personalizados estão no roadmap.

Em breve

• Connectors adicionais (Google, Twilio, SendGrid e mais)
• Definições de connectors personalizados — traga sua própria API
• Ingestão de webhooks para eventos recebidos de serviços conectados
• Gateway OAuth — mantenha os tokens no servidor mesmo em fluxos iniciados pelo cliente