Task Interface

Un endpoint. Lenguaje natural. El agente se encarga de todo lo demás.

---

El cambio

Las integraciones tradicionales te obligan a aprender endpoints, mapear campos, versionar esquemas y gestionar cada caso límite. El Chat Agent Gateway sustituye todo eso por comunicación agéntica. Describe lo que necesitas. El propio agente de SOIS interpreta tu intención, negocia los detalles, ejecuta en tu espacio de trabajo y responde con el resultado. Esta es la vía de acceso para quienes llaman sin una IA propia. Si ya tienes un agente, conéctalo directamente a través del servidor MCP.

Sin conectores. Sin middleware. Sin capa de automatización de terceros.

---

Autenticación

Cada mensaje requiere dos credenciales:

¿Por qué dos? Tu token demuestra tu identidad. Tu clave controla el gasto. Si solo una de las dos se filtra, es inútil sin la otra. Un usuario puede tener varias claves con presupuestos distintos para integraciones distintas.

Obtén ambas en Settings dentro de tu espacio de trabajo Sois AI.

---

Enviar un mensaje

POST /api/agent

Headers

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

Body

Ejemplo

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

Respuesta 202 Accepted

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

Tu mensaje está en el gateway. El agente toma el control a partir de aquí.

---

Recibir la respuesta

Tienes dos opciones: esperar el webhook o consultar la conversación.

Opción 1: Webhook (recomendada)

Si tu clave tiene una response_url, el agente entrega el resultado directamente cuando termina: firmado, verificado, sin 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."
}

Opción 2: Consultar la conversación

GET /api/agent/{conversation_uuid}

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

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

Estados de la conversación

---

Verificación de las firmas de webhook

Cada webhook se firma con HMAC-SHA256 usando el signing secret de tu clave. Verifica siempre antes de procesar.

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

---

Ejemplos de conversaciones

El agente tiene acceso completo a tu espacio de trabajo Sois AI. Aquí tienes algunas cosas que puedes pedir:

Buscar:

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

Crear:

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

Correo:

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

Tareas:

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

Multipaso:

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

El agente negocia la ambigüedad. Si necesita buscar antes de poder actuar, busca. Si coinciden varios registros, elige el mejor y te dice por qué. Sin esquemas rígidos, solo intención.

---

Gestión de claves

Gestiona tus claves desde Settings > API Keys en tu espacio de trabajo Sois AI, o de forma programática.

Crear una clave

POST /api/api-keys

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

La respuesta incluye tu clave (mostrada una sola vez, cópiala de inmediato) y tu signing secret para la verificación de webhooks.

Gestionar claves

---

Controles de presupuesto

Las integraciones tradicionales te limitan con tasas arbitrarias: 100 solicitudes por minuto, 10.000 al día. El Chat Agent Gateway usa dólares.

Define un presupuesto por clave. El agente cobra credits por acción. Tú decides cuánto vale cada integración.

Cuando se supera un presupuesto, los mensajes devuelven 429 con una explicación clara, no un código de error críptico.

---

Errores

Cada error sigue el mismo formato:

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

---

Límites