API v2 Agenti e impostazioni

Usa questi endpoint per gestire gli agenti e le loro impostazioni. Ogni endpoint di questa pagina richiede Authorization: Bearer YOUR_API_KEY. Le rotte specifiche per agente restituiscono 404 AGENT_NOT_FOUND quando l'agente non esiste o non appartiene all'account della chiave API.

Le risposte di elenco con esito positivo usano un envelope data e pagination. Le risposte sui dettagli e sulle impostazioni dell'agente sono oggetti diretti, senza envelope data. Consulta il catalogo degli errori per gli errori di autenticazione e validazione comuni.

Oggetto agente

{
  "id": "955f28f1-8515-40bb-802c-f3f730bf0343",
  "name": "Support Agent",
  "url": "https://example.com",
  "createdAt": 1784332800,
  "settings": {
    "ai": {
      "model": "openai/gpt-5.6-luna",
      "instructionsPreset": "ai-chatbot",
      "instructionsPrompt": "Be helpful, accurate, and conversational."
    },
    "title": "AI Assistant",
    "branding": {
      "appearance": "Light",
      "bubbleColor": "#e9e9e7",
      "primaryColor": "#0a0a0a",
      "primaryColorHeader": false
    },
    "position": "bottom-right",
    "conversation": {
      "defaultPrompts": {
        "enabled": false,
        "prompts": [],
        "keepShowing": false
      },
      "initialMessages": ["Hey! What can I help with?"],
      "messagePlaceholder": "Ask our chatbot a question...",
      "showInitialMessageBubble": true
    },
    "features": {
      "attachments": true
    },
    "notification": {
      "dailyConversations": true,
      "dailyEmails": true,
      "quotaAlerts": true
    }
  }
}

Elenca gli agenti

Percorso: /api/v2/agents

GET /api/v2/agents

Autenticazione: Chiave API Bearer.

Successo: 200 OK

curl 'https://your-domain.com/api/v2/agents?limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": "955f28f1-8515-40bb-802c-f3f730bf0343",
      "name": "Support Agent",
      "url": "https://example.com/",
      "createdAt": 1784332800,
      "settings": {}
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Limiti o cursori non validi restituiscono 400 VALIDATION_INVALID_BODY.

Crea un agente

POST /api/v2/agents

Autenticazione: Chiave API Bearer.

curl -X POST 'https://your-domain.com/api/v2/agents' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Support Agent","url":"https://example.com"}'

Successo: 201 Created, con l'oggetto agente restituito diretto.

Un corpo non valido restituisce 400 VALIDATION_INVALID_BODY. Il superamento del limite di agenti del workspace restituisce 403 QUOTA_CHATBOT_LIMIT.

Recupera un agente

Percorso: /api/v2/agents/{agentId}

GET /api/v2/agents/{agentId}

Autenticazione: Chiave API Bearer con accesso a {agentId}.

Successo: 200 OK, con l'oggetto agente restituito diretto.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Aggiorna un agente

PATCH /api/v2/agents/{agentId}

Autenticazione: Chiave API Bearer con accesso a {agentId}.

È richiesto almeno un campo.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Customer Support"}'

Successo: 200 OK, con l'oggetto agente aggiornato restituito diretto. Corpi non validi o vuoti restituiscono 400 VALIDATION_INVALID_BODY.

Elimina un agente

DELETE /api/v2/agents/{agentId}

Autenticazione: Chiave API Bearer con accesso a {agentId}.

curl -X DELETE 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Successo: 200 OK

{
  "deleted": true
}

Schema delle impostazioni AI

Percorso: /api/v2/agents/{agentId}/settings/ai

Gli aggiornamenti delle impostazioni AI richiedono almeno un campo.

Per compatibilità con le versioni precedenti, model accetta anche gli slug ritirati openai/gpt-5.5, openai/gpt-5.4, openai/gpt-5.4-mini, openai/gpt-5.4-nano, anthropic/claude-opus-4.7, anthropic/claude-opus-4-6, anthropic/claude-sonnet-4-6, google/gemini-3-flash-preview e google/gemini-3.6-flash. Gli agenti esistenti possono ancora avere questi valori memorizzati (e la GET può ancora restituirli), quindi un ciclo GET→PATCH è sempre valido — ma questi modelli non sono più proposti nel selettore di modelli della dashboard, e le nuove integrazioni dovrebbero usare il catalogo attuale sopra riportato.

Recupera le impostazioni AI

GET /api/v2/agents/{agentId}/settings/ai

Autenticazione: Chiave API Bearer con accesso a {agentId}.

Successo: 200 OK. L'oggetto delle impostazioni AI viene restituito diretto; se non sono impostate, produce {}.

{
  "model": "openai/gpt-5.6-luna",
  "instructionsPreset": "customer-support",
  "instructionsPrompt": "Answer using the support documentation."
}

Aggiorna le impostazioni AI

PATCH /api/v2/agents/{agentId}/settings/ai

Autenticazione: Chiave API Bearer con accesso a {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/ai' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model":"openai/gpt-5.6-luna","instructionsPreset":"customer-support"}'

Successo: 200 OK, con l'oggetto delle impostazioni AI aggiornato restituito diretto. Un modello non disponibile restituisce 403 CHAT_MODEL_NOT_ALLOWED; corpi non validi o vuoti restituiscono 400 VALIDATION_INVALID_BODY.

Schema delle impostazioni di design

Percorso: /api/v2/agents/{agentId}/settings/design

Gli aggiornamenti delle impostazioni di design richiedono almeno un campo.

Recupera le impostazioni di design

GET /api/v2/agents/{agentId}/settings/design

Autenticazione: Chiave API Bearer con accesso a {agentId}.

Successo: 200 OK. La risposta è un oggetto diretto che contiene i gruppi correnti title, language, position, branding e conversation. Le chiavi opzionali non impostate vengono omesse.

{
  "title": "AI Assistant",
  "language": "en",
  "position": "bottom-right",
  "branding": {
    "appearance": "Light",
    "bubbleColor": "#e9e9e7",
    "primaryColor": "#0a0a0a",
    "primaryColorHeader": false
  },
  "conversation": {
    "defaultPrompts": {
      "enabled": false,
      "prompts": [],
      "keepShowing": false
    },
    "initialMessages": ["Hey! What can I help with?"],
    "messagePlaceholder": "Ask our chatbot a question...",
    "showInitialMessageBubble": true
  }
}

Aggiorna le impostazioni di design

PATCH /api/v2/agents/{agentId}/settings/design

Autenticazione: Chiave API Bearer con accesso a {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/design' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Support","language":"en-US","appearance":"Dark","prompts":["Track my order"]}'

Successo: 200 OK. A differenza della risposta GET del design, la PATCH restituisce l'intero oggetto delle impostazioni in forma diretta. Può contenere questi campi e gruppi di primo livello, quando impostati: title, language, position, branding, ai, conversation, security, guardrails, notification, training, channels e identityVerification. Gli alias di lingua vengono restituiti e memorizzati in forma canonica. Corpi non validi o vuoti restituiscono 400 VALIDATION_INVALID_BODY.

Schema delle impostazioni di sicurezza

Percorso: /api/v2/agents/{agentId}/settings/security

Gli aggiornamenti delle impostazioni di sicurezza richiedono almeno un campo di primo livello.

Recupera le impostazioni di sicurezza

GET /api/v2/agents/{agentId}/settings/security

Autenticazione: Chiave API Bearer con accesso a {agentId}.

Successo: 200 OK. L'oggetto di sicurezza viene restituito diretto; se non impostato, produce {}.

{
  "isPrivate": false,
  "rateLimit": {
    "maxMessages": 20,
    "windowSeconds": 240,
    "limitMessage": "Too many messages in a row"
  },
  "allowedDomains": {
    "enabled": true,
    "domains": ["https://example.com"]
  }
}

Aggiorna le impostazioni di sicurezza

PATCH /api/v2/agents/{agentId}/settings/security

Autenticazione: Chiave API Bearer con accesso a {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/security' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"allowedDomains":{"enabled":true,"domains":["https://example.com"]}}'

Successo: 200 OK, con l'oggetto delle impostazioni di sicurezza aggiornato restituito diretto. Corpi non validi o vuoti restituiscono 400 VALIDATION_INVALID_BODY.

Schema delle impostazioni di notifica

Percorso: /api/v2/agents/{agentId}/settings/notifications

È richiesto almeno un campo.

dailyConversations si comporta come false (disattivato) se omesso; dailyEmails e quotaAlerts si comportano come true (attivato) se omessi. La risposta GET restituisce solo i campi impostati esplicitamente.

Recupera le impostazioni di notifica

GET /api/v2/agents/{agentId}/settings/notifications

Autenticazione: Chiave API Bearer con accesso a {agentId}.

Successo: 200 OK. L'oggetto delle notifiche viene restituito diretto; se non impostato, produce {}.

{
  "dailyConversations": true,
  "dailyEmails": true,
  "quotaAlerts": true
}

Aggiorna le impostazioni di notifica

PATCH /api/v2/agents/{agentId}/settings/notifications

Autenticazione: Chiave API Bearer con accesso a {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/notifications' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"dailyConversations":false}'

Successo: 200 OK, con l'oggetto delle impostazioni di notifica aggiornato restituito diretto. Corpi non validi o vuoti restituiscono 400 VALIDATION_INVALID_BODY.

Schema delle impostazioni di addestramento

Percorso: /api/v2/agents/{agentId}/settings/training

Recupera le impostazioni di addestramento

GET /api/v2/agents/{agentId}/settings/training

Autenticazione: Chiave API Bearer con accesso a {agentId}.

Successo: 200 OK. L'oggetto delle impostazioni di addestramento viene restituito diretto; se non impostato, produce {}.

{
  "autoRetrainEnabled": true
}

Aggiorna le impostazioni di addestramento

PATCH /api/v2/agents/{agentId}/settings/training

Autenticazione: Chiave API Bearer con accesso a {agentId}.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/settings/training' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"autoRetrainEnabled":true}'

Successo: 200 OK, con l'oggetto delle impostazioni di addestramento aggiornato restituito diretto. Attivare il riaddestramento automatico senza un piano che lo consenta restituisce 403 SUBSCRIPTION_API_RESTRICTED_PLAN; corpi non validi restituiscono 400 VALIDATION_INVALID_BODY.

Riferimenti correlati

• Panoramica API v2
• Catalogo degli errori API v2
• Fonti e addestramento