Skip to main content

POST /v1/whatsapp/agents/{id}/numbers

Attiva un Agente AI su un numero WhatsApp:
  1. aggiunge il numero a quelli dell’agente, e i numeri che aveva già restano;
  2. se l’agente era spento, lo accende.
Da quel momento l’agente risponde ai clienti che scrivono a quel numero, nei suoi orari e con le sue regole. Serve, per esempio, al gestionale che vuole passare un numero all’agente la sera o durante le ferie, e riprenderlo con DELETE /v1/whatsapp/agents/{id}/numbers/{phone}.
Se l’agente era spento e aveva già altri numeri, accendendolo torna a rispondere anche su quelli. Controlla numbers con GET /v1/whatsapp/agents prima di attivarlo.
Un numero ha al massimo un agente. Se il numero è già servito da un altro agente dell’account, la richiesta viene rifiutata con number_taken, a meno che tu non chieda di spostarlo con "move": true.

Parametri

Request Body

Che cosa succede

La richiesta si può ripetere senza effetti doppi: se l’agente è già attivo su quel numero risponde changed: false. Il metodo di pagamento su Meta si controlla solo quando il numero si aggiunge all’agente, anche quando lo sposti da un altro agente con move. Se il numero era già suo, non serve. Ogni attivazione che cambia qualcosa lascia una riga nel Log attività del pannello.

Richiesta

Risposta

200 OK, con l’agente com’è dopo la modifica.

Campi della risposta

I campi dell’agente sono descritti in Elenco Agenti AI. In più: active_now può essere false anche subito dopo un’attivazione riuscita: succede quando l’agente ha delle fasce orarie e in questo momento è fuori orario. Comincerà a rispondere alla prossima fascia.

Errori

400 - invalid_number

number manca, non è una stringa o non è un numero di telefono riconoscibile. Esempio valido: +390612345678.

404 - agent_not_found

Non esiste un agente con questo id su questo account.

404 - number_not_found

Il numero non è tra quelli WhatsApp collegati a MyFlow su questo account. L’elenco è in GET /v1/whatsapp/numbers.

409 - number_taken

Il numero è già servito da un altro agente dell’account. Il messaggio ne dice il nome e error.agent lo identifica. Per spostarlo su questo agente, ripeti la richiesta con "move": true.

409 - number_unavailable

Il numero è condiviso con un altro account MyCentralino, che ci ha già messo un suo agente. Da questo account non si può usare finché lì non viene tolto.

409 - agent_update_failed

Il numero è cambiato mentre la richiesta era in corso, per esempio perché qualcuno lo stava assegnando dal pannello nello stesso momento. Rileggi con GET /v1/whatsapp/agents e riprova.

422 - payment_method_required

Sull’account WhatsApp Business del numero manca il metodo di pagamento su Meta: va aggiunto da Meta prima di attivare l’agente. Lo stesso codice, con un messaggio diverso, arriva quando Meta non ha confermato il metodo di pagamento perché in quel momento non risponde: riprova fra qualche minuto. Dopo aver aggiunto il metodo di pagamento su Meta, può servire una decina di minuti prima che l’attivazione passi.

403 - agents_not_enabled

Gli Agenti AI non sono disponibili su questo account. Gli errori comuni a tutte le rotte sono nell’introduzione.