Task Interface

Un point de terminaison. Du langage naturel. L'agent gère tout le reste.

---

Le changement

Les intégrations traditionnelles vous obligent à apprendre des points de terminaison, à mapper des champs, à versionner des schémas et à gérer chaque cas limite. Le Chat Agent Gateway remplace tout cela par la communication agentique. Décrivez ce dont vous avez besoin. L'agent propre à SOIS interprète votre intention, négocie les détails, exécute sur votre espace de travail et répond avec le résultat. C'est la rampe d'accès pour les appelants qui n'ont pas d'IA à eux. Si vous avez déjà un agent, connectez-le directement via le serveur MCP.

Aucun connecteur. Aucun middleware. Aucune couche d'automatisation tierce.

---

Authentification

Chaque message nécessite deux identifiants :

Pourquoi deux ? Votre jeton prouve votre identité. Votre clé contrôle les dépenses. Si l'un des deux fuite seul, il est inutile sans l'autre. Un utilisateur peut avoir plusieurs clés avec des budgets différents pour différentes intégrations.

Récupérez les deux depuis Settings dans votre espace de travail Sois AI.

---

Envoyer un message

POST /api/agent

Headers

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

Body

Exemple

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

Réponse 202 Accepted

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

Votre message est dans la passerelle. L'agent prend le relais à partir d'ici.

---

Recevoir la réponse

Vous avez deux options : attendre le webhook ou interroger la conversation.

Option 1 : Webhook (recommandé)

Si votre clé a une response_url, l'agent vous livre le résultat directement une fois terminé : signé, vérifié, sans 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."
}

Option 2 : Interroger la conversation

GET /api/agent/{conversation_uuid}

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

Réponse 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"
}

États de la conversation

---

Vérification des signatures de webhook

Chaque webhook est signé avec HMAC-SHA256 à l'aide du signing secret de votre clé. Vérifiez toujours avant de traiter.

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

---

Exemples de conversations

L'agent a un accès complet à votre espace de travail Sois AI. Voici quelques exemples de demandes possibles :

Rechercher :

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

Créer :

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

Tâches :

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

Résumer :

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

Multi-étapes :

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

L'agent négocie l'ambiguïté. S'il doit rechercher avant de pouvoir agir, il recherche. Si plusieurs enregistrements correspondent, il choisit le meilleur et vous explique pourquoi. Aucun schéma rigide, juste l'intention.

---

Gestion des clés

Gérez vos clés depuis Settings > API Keys dans votre espace de travail Sois AI, ou par programmation.

Créer une clé

POST /api/api-keys

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

La réponse inclut votre clé (affichée une seule fois, copiez-la immédiatement) et votre signing secret pour la vérification des webhooks.

Gérer les clés

---

Contrôles de budget

Les intégrations traditionnelles vous bridaient avec des limites de débit arbitraires : 100 requêtes par minute, 10 000 par jour. Le Chat Agent Gateway utilise des dollars.

Définissez un budget par clé. L'agent facture des credits par action. Vous décidez de la valeur de chaque intégration.

Lorsqu'un budget est dépassé, les messages renvoient 429 avec une explication claire, et non un code d'erreur obscur.

---

Erreurs

Chaque erreur suit le même format :

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

---

Limites