Task Interface

Um endpoint. Linguagem natural. O agente cuida de todo o resto.

---

A mudança

As integrações tradicionais obrigam você a aprender endpoints, mapear campos, versionar esquemas e tratar cada caso limite. O Chat Agent Gateway substitui tudo isso por comunicação agêntica. Descreva o que você precisa. O próprio agente da SOIS interpreta sua intenção, negocia os detalhes, executa no seu espaço de trabalho e responde com o resultado. Esta é a porta de entrada para quem chama sem uma IA própria. Se você já tem um agente, conecte-o diretamente pelo servidor MCP.

Sem conectores. Sem middleware. Sem camada de automação de terceiros.

---

Autenticação

Cada mensagem exige duas credenciais:

Por que duas? Seu token prova a identidade. Sua chave controla os gastos. Se apenas uma delas vazar, ela é inútil sem a outra. Um usuário pode ter várias chaves com orçamentos diferentes para integrações diferentes.

Obtenha as duas em Settings no seu espaço de trabalho Sois AI.

---

Enviar uma mensagem

POST /api/agent

Headers

Authorization: Bearer <your_token>
X-Api-Key: sois_...
Content-Type: application/json

Body

Exemplo

curl -X POST "https://your-workspace.sois.ai/api/agent" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Api-Key: sois_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Create a contact for John Smith at Acme Corp, [email protected], +44 7700 900000",
    "context": { "entity_type": "contact", "action": "create" }
  }'

Resposta 202 Accepted

{
    "conversation_uuid": "6cafd8ba-dd51-4411-808e-671d1dd59561",
    "status": "accepted",
    "message": "Your request has been queued."
}

Sua mensagem está no gateway. O agente assume a partir daqui.

---

Receber a resposta

Você tem duas opções: aguardar o webhook ou consultar a conversa.

Opção 1: Webhook (recomendada)

Se sua chave tem uma response_url, o agente entrega o resultado diretamente a você quando termina: assinado, verificado, sem polling.

POST https://your-app.com/webhook
Content-Type: application/json
X-Signature: <hmac_sha256>
X-Conversation-UUID: 6cafd8ba-...

Resolved:

{
    "conversation_uuid": "6cafd8ba-...",
    "status": "resolved",
    "response": "Contact created: John Smith, Acme Corp, [email protected], +44 7700 900000."
}

Failed:

{
    "conversation_uuid": "6cafd8ba-...",
    "status": "failed",
    "error": "An error occurred while processing your request."
}

Opção 2: Consultar a conversa

GET /api/agent/{conversation_uuid}

Authorization: Bearer <your_token>
X-Api-Key: sois_...

Resposta 200 OK:

{
    "conversation_uuid": "6cafd8ba-...",
    "status": "resolved",
    "turns": [
        {
            "role": "user",
            "payload": { "message": "Find all contacts from London" },
            "timestamp": "2026-02-12T01:07:03+00:00"
        },
        {
            "role": "agent",
            "payload": {
                "content": "I found 12 contacts based in London..."
            },
            "timestamp": "2026-02-12T01:07:13+00:00"
        }
    ],
    "webhook": {
        "status": "delivered",
        "delivered_at": "2026-02-12T01:07:14+00:00"
    },
    "resolved_at": "2026-02-12T01:07:13+00:00",
    "expires_at": "2026-02-13T01:07:03+00:00",
    "created_at": "2026-02-12T01:07:03+00:00"
}

Status da conversa

---

Verificação das assinaturas de webhook

Cada webhook é assinado com HMAC-SHA256 usando o signing secret da sua chave. Verifique sempre antes de processar.

Python:

import hmac, hashlib

expected = hmac.new(
    key=your_signing_secret.encode(),
    msg=raw_request_body.encode(),
    digestmod=hashlib.sha256
).hexdigest()

assert expected == request.headers['X-Signature']

Node.js:

const crypto = require('crypto');
const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(rawBody)
    .digest('hex');

if (expected !== req.headers['x-signature']) {
    throw new Error('Invalid signature');
}

PHP:

$expected = hash_hmac('sha256', $rawBody, $signingSecret);
if (!hash_equals($expected, $request->header('X-Signature'))) {
    abort(403, 'Invalid signature');
}

---

Exemplos de conversas

O agente tem acesso completo ao seu espaço de trabalho Sois AI. Aqui estão algumas coisas que você pode pedir:

Pesquisar:

{ "message": "Find all contacts from London" }

Criar:

{
    "message": "Create a contact: Jane Doe, CEO of Acme Corp, [email protected]",
    "context": { "entity_type": "contact", "action": "create" }
}

E-mail:

{
    "message": "Send an email to [email protected] introducing our new product line",
    "context": { "entity_type": "inbox", "action": "compose" }
}

Tarefas:

{
    "message": "Create a task: Research competitor pricing for Q1 2026",
    "context": { "entity_type": "task", "action": "create" }
}

Resumir:

{
    "message": "Give me a full summary of this contact",
    "context": { "entity_type": "contact", "entity_id": "abc-123", "action": "summarize" }
}

Múltiplas etapas:

{ "message": "Find the Q1 report, summarise it, and email the summary to the sales team" }

O agente negocia a ambiguidade. Se ele precisa pesquisar antes de poder agir, ele pesquisa. Se vários registros correspondem, ele escolhe o melhor e diz por quê. Sem esquemas rígidos, apenas intenção.

---

Gerenciamento de chaves

Gerencie suas chaves em Settings > API Keys no seu espaço de trabalho Sois AI, ou de forma programática.

Criar uma chave

POST /api/api-keys

{
    "label": "My CRM Integration",
    "response_url": "https://your-app.com/webhook",
    "budget_usd_cents": 5000,
    "budget_period": "monthly"
}

A resposta inclui sua chave (exibida uma única vez, copie-a imediatamente) e seu signing secret para a verificação de webhooks.

Gerenciar chaves

---

Controles de orçamento

As integrações tradicionais limitam você com taxas arbitrárias: 100 solicitações por minuto, 10.000 por dia. O Chat Agent Gateway usa dólares.

Defina um orçamento por chave. O agente cobra credits por ação. Você decide quanto vale cada integração.

Quando um orçamento é excedido, as mensagens retornam 429 com uma explicação clara, não um código de erro críptico.

---

Erros

Cada erro segue o mesmo formato:

{
    "error": {
        "code": "ERROR_CODE",
        "message": "A clear, human-readable explanation."
    }
}

---

Limites