Task Interface

Un endpoint. Linguaggio naturale. L'agente gestisce tutto il resto.

---

Il cambiamento

Le integrazioni tradizionali ti costringono a imparare endpoint, mappare campi, versionare schemi e gestire ogni caso limite. Il Chat Agent Gateway sostituisce tutto questo con la comunicazione agentica. Descrivi ciò di cui hai bisogno. L'agente proprio di SOIS interpreta la tua intenzione, negozia i dettagli, esegue sul tuo workspace e risponde con il risultato. Questo è il punto di accesso per i chiamanti che non hanno una propria AI. Se hai già un agente, collegalo direttamente tramite il server MCP.

Nessun connettore. Nessun middleware. Nessuno strato di automazione di terze parti.

---

Autenticazione

Ogni messaggio richiede due credenziali:

Perché due? Il tuo token dimostra l'identità. La tua chiave controlla la spesa. Se uno solo dei due trapela, è inutile senza l'altro. Un utente può avere più chiavi con budget diversi per integrazioni diverse.

Ottieni entrambi da Settings nel tuo workspace Sois AI.

---

Invia un messaggio

POST /api/agent

Headers

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

Body

Esempio

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" }
  }'

Risposta 202 Accepted

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

Il tuo messaggio è nel gateway. L'agente prende in carico da qui.

---

Ricevi la risposta

Hai due opzioni: attendere il webhook o interrogare la conversazione.

Opzione 1: Webhook (consigliata)

Se la tua chiave ha una response_url, l'agente consegna il risultato direttamente a te quando ha finito: firmato, verificato, senza 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."
}

Opzione 2: Interroga la conversazione

GET /api/agent/{conversation_uuid}

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

Risposta 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"
}

Stati della conversazione

---

Verifica delle firme webhook

Ogni webhook è firmato con HMAC-SHA256 usando il signing secret della tua chiave. Verifica sempre prima di elaborare.

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');
}

---

Esempi di conversazioni

L'agente ha accesso completo al tuo workspace Sois AI. Ecco alcune cose che puoi chiedere:

Cercare:

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

Creare:

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

Email:

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

Attività:

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

Riassumere:

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

Multi-step:

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

L'agente negozia l'ambiguità. Se deve cercare prima di poter agire, cerca. Se più record corrispondono, sceglie il migliore e ti dice perché. Nessuno schema rigido, solo intenzione.

---

Gestione delle chiavi

Gestisci le tue chiavi da Settings > API Keys nel tuo workspace Sois AI, oppure in modo programmatico.

Crea una chiave

POST /api/api-keys

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

La risposta include la tua chiave (mostrata una sola volta, copiala subito) e il tuo signing secret per la verifica dei webhook.

Gestisci le chiavi

---

Controlli del budget

Le integrazioni tradizionali ti limitano con rate limit arbitrari: 100 richieste al minuto, 10.000 al giorno. Il Chat Agent Gateway usa i dollari.

Imposta un budget per chiave. L'agente addebita credit per azione. Tu controlli quanto vale ogni integrazione.

Quando un budget viene superato, i messaggi restituiscono 429 con una spiegazione chiara, non un codice di errore criptico.

---

Errori

Ogni errore segue lo stesso formato:

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

---

Limiti