Skip to main content

POST /v1/whatsapp/agents

Crea un nuovo Agente AI di MyFlow, lo stesso che si crea dal pannello in MyFlow → Agenti AI. Gli dai un nome, le istruzioni su come rispondere ai clienti, gli orari e le regole di risposta. L’agente nasce spento e senza numeri: non risponde a nessuno finché non lo attivi su un numero con POST /v1/whatsapp/agents/{id}/numbers. Prima puoi dargli la conoscenza, cioè testi e domande frequenti.
Il modello di intelligenza artificiale non si sceglie: è lo stesso per tutti gli agenti. Un campo provider o model nel body viene rifiutato con unknown_fields.

Request Body

Solo name è obbligatorio. Ogni campo assente prende il valore di partenza del pannello. Tipi stretti: i numeri sono interi JSON (5, non "5") e enabled è true o false. Un campo che non è in tabella viene rifiutato con unknown_fields, così un errore di battitura non passa per salvato.

Orari

schedule ha la stessa forma che restituisce l’elenco degli agenti:
  • Gli orari sono in ora italiana e a 24 ore con due cifre: 09:00, non 9:00. L’inizio è compreso, la fine esclusa.
  • Con mode: "slots" serve almeno una fascia.
  • Con mode: "always" le fasce mandate vengono salvate ma non usate. Restano pronte per quando passerai a slots.

Richiesta

Risposta

201 Created con l’agente appena creato, nella stessa forma del dettaglio.
I campi sono spiegati nel dettaglio dell’agente.

Dopo la creazione

  1. Aggiungi la conoscenza con POST /v1/whatsapp/agents/{id}/knowledge: orari, servizi, domande frequenti.
  2. Attivalo su un numero con POST /v1/whatsapp/agents/{id}/numbers, che lo accende anche.
  3. Per provarlo prima di attivarlo, apri l’agente nel pannello, in MyFlow → Agenti AI, e usa la card Prova.
Ogni creazione lascia una riga nel Log attività del pannello, con il nome dell’agente. Il testo delle istruzioni non viene scritto.

Errori

422 - invalid_name

Manca name, oppure è vuoto, oltre gli 80 caratteri o su più righe.

422 - invalid_instructions / invalid_handoff_message

Testo non valido o troppo lungo: istruzioni fino a 16.000 caratteri, frase di passaggio da 1 a 500.

422 - invalid_schedule

schedule non ha la forma giusta. Il messaggio dice cosa correggere: un giorno sconosciuto, un orario non HH:MM, una fascia che finisce prima di cominciare, più di 10 fasce in un giorno, mode: "slots" senza fasce.

422 - invalid_max_replies / invalid_reply_delay_seconds / invalid_human_pause_minutes

Numero fuori dall’intervallo o non intero. L’errore porta min e max.

422 - invalid_enabled

enabled non è true o false.

422 - unknown_fields

Un campo che non esiste, provider e model compresi. L’errore elenca i campi sbagliati in fields e quelli ammessi in allowed.

409 - agent_limit

L’account ha già il numero massimo di agenti (10). Per crearne uno nuovo eliminane uno dal pannello. Gli errori comuni a tutte le rotte sono nell’introduzione.