Conectores
Integrações OAuth com serviços externos. Gmail, Google Calendar e WhatsApp para seus assistentes e agentes.
Visão Geral
Os conectores da Polar permitem integrar seus assistentes e agentes com serviços externos via OAuth. Com conectores, seus agentes podem ler e enviar emails, gerenciar eventos de calendário e enviar mensagens pelo WhatsApp.
Conectores Disponíveis
| Conector | Ações Disponíveis | Status |
|---|---|---|
| Gmail | Ler, enviar, buscar emails | Disponível |
| Google Calendar | Criar, listar, atualizar eventos | Disponível |
| Enviar, receber mensagens | Beta |
Configuração OAuth
1. Iniciar Fluxo OAuth
import requests
# Iniciar autorização OAuth
response = requests.post(
"https://api.polarai.com.br/v1/connectors/authorize",
headers={"Authorization": "Bearer pk-sua-chave-aqui"},
json={
"provider": "gmail",
"redirect_uri": "https://meuapp.com/callback",
"scopes": ["read", "send"]
}
)
auth = response.json()
print(f"Redirecionar para: {auth['authorization_url']}")2. Callback
Após o usuário autorizar, o provedor redireciona para sua URL com o código:
# Trocar código por token
response = requests.post(
"https://api.polarai.com.br/v1/connectors/callback",
headers={"Authorization": "Bearer pk-sua-chave-aqui"},
json={
"provider": "gmail",
"code": "auth_code_recebido",
"redirect_uri": "https://meuapp.com/callback"
}
)
connection = response.json()
print(f"Conector configurado: {connection['connection_id']}")3. Armazenamento de Tokens
Os tokens OAuth são armazenados de forma segura na Polar e renovados automaticamente quando expiram. Você não precisa gerenciar tokens manualmente.
Gmail
Ações Disponíveis
Ler Emails
response = requests.post(
"https://api.polarai.com.br/v1/connectors/gmail/read",
headers={"Authorization": "Bearer pk-sua-chave-aqui"},
json={
"connection_id": "conn_abc123",
"query": "from:cliente@empresa.com is:unread",
"limit": 10
}
)
emails = response.json()
for email in emails["messages"]:
print(f"De: {email['from']} — {email['subject']}")Enviar Email
response = requests.post(
"https://api.polarai.com.br/v1/connectors/gmail/send",
headers={"Authorization": "Bearer pk-sua-chave-aqui"},
json={
"connection_id": "conn_abc123",
"to": "destinatario@example.com",
"subject": "Atualização do processo",
"body": "Prezado cliente, segue atualização...",
"html": False
}
)Buscar Emails
response = requests.post(
"https://api.polarai.com.br/v1/connectors/gmail/search",
headers={"Authorization": "Bearer pk-sua-chave-aqui"},
json={
"connection_id": "conn_abc123",
"query": "subject:contrato after:2024/01/01",
"limit": 20
}
)Google Calendar
Ações Disponíveis
Listar Eventos
response = requests.get(
"https://api.polarai.com.br/v1/connectors/gcalendar/events",
headers={"Authorization": "Bearer pk-sua-chave-aqui"},
params={
"connection_id": "conn_abc123",
"start": "2024-03-15T00:00:00Z",
"end": "2024-03-22T23:59:59Z"
}
)
events = response.json()
for event in events["items"]:
print(f"{event['start']} — {event['summary']}")Criar Evento
response = requests.post(
"https://api.polarai.com.br/v1/connectors/gcalendar/events",
headers={"Authorization": "Bearer pk-sua-chave-aqui"},
json={
"connection_id": "conn_abc123",
"summary": "Reunião com cliente",
"description": "Discussão sobre o processo 1234",
"start": "2024-03-20T14:00:00-03:00",
"end": "2024-03-20T15:00:00-03:00",
"attendees": ["cliente@example.com"],
"reminders": {
"email": 30,
"popup": 10
}
}
)Atualizar Evento
response = requests.patch(
"https://api.polarai.com.br/v1/connectors/gcalendar/events/evt_abc123",
headers={"Authorization": "Bearer pk-sua-chave-aqui"},
json={
"connection_id": "conn_abc123",
"summary": "Reunião com cliente (reagendada)",
"start": "2024-03-21T14:00:00-03:00",
"end": "2024-03-21T15:00:00-03:00"
}
)Ações Disponíveis (Beta)
Enviar Mensagem
response = requests.post(
"https://api.polarai.com.br/v1/connectors/whatsapp/send",
headers={"Authorization": "Bearer pk-sua-chave-aqui"},
json={
"connection_id": "conn_abc123",
"to": "+5511999887766",
"message": "Olá! Sua consulta foi agendada para amanhã às 14h."
}
)Receber Mensagens (Webhook)
Configure um webhook para receber mensagens:
response = requests.post(
"https://api.polarai.com.br/v1/connectors/whatsapp/webhook",
headers={"Authorization": "Bearer pk-sua-chave-aqui"},
json={
"connection_id": "conn_abc123",
"webhook_url": "https://meuapp.com/webhook/whatsapp",
"events": ["message_received", "message_delivered"]
}
)Usar Conectores com Agentes
Associe conectores a personas para que agentes possam interagir com serviços externos:
response = requests.post(
"https://api.polarai.com.br/v1/personas",
headers={"Authorization": "Bearer pk-sua-chave-aqui"},
json={
"name": "Assistente Executivo",
"system_prompt": "Você é um assistente executivo que gerencia emails e agenda.",
"tools": [
{"type": "gmail", "connection_id": "conn_gmail_123"},
{"type": "gcalendar", "connection_id": "conn_gcal_456"}
]
}
)Gerenciar Conexões
Listar Conexões
curl https://api.polarai.com.br/v1/connectors/connections \
-H "Authorization: Bearer pk-sua-chave-aqui"Revogar Conexão
curl -X DELETE https://api.polarai.com.br/v1/connectors/connections/conn_abc123 \
-H "Authorization: Bearer pk-sua-chave-aqui"Segurança
- Tokens OAuth são criptografados em repouso (AES-256)
- Tokens são renovados automaticamente
- Cada conexão tem escopos mínimos necessários
- Revogar uma conexão invalida todos os tokens associados
- Logs de auditoria disponíveis para todas as ações de conector
Limites
- Máximo de 10 conexões por conta (Free)
- Máximo de 50 conexões por conta (Pro)
- Gmail: máximo de 100 emails lidos por requisição
- Gmail: máximo de 50 emails enviados por hora
- Calendar: máximo de 250 eventos por requisição
- WhatsApp: máximo de 100 mensagens por hora