# RisveglIA: operazioni di n8n e Make

Riferimento per costruire flussi con il nodo RisveglIA per n8n (https://risveglia.it/integrazioni/n8n) e l'app RisveglIA per Make (https://risveglia.it/integrazioni/make).
Nel nodo n8n scegli Risorsa e Operazione, poi compila ID e Azione (se l'operazione li chiede), «Parametri (JSON)» e «Corpo (JSON)». In Make usa il modulo dedicato se c'è, altrimenti «Esegui una chiamata API» con gli stessi valori.
Gli id negli esempi sono segnaposto (00000000-…): prendi quelli veri dalle operazioni di lettura. Ogni esempio è controllato con gli schemi dell'API a ogni rilascio.
Nelle espressioni n8n leggi sempre il dato dal nodo sorgente: {{ $('Nome Nodo').item.json.campo }}.

## Messaggi

### Invia in una chat: testo, file della libreria (foto, video, documento, vocale), sondaggio, posizione, contatto, evento, reazione, modifica o eliminazione

`invii.crea` · POST /v2/invii · permesso «Invio messaggi» · con chiave di idempotenza

Per scrivere in una chat già in archivio: testo, file della libreria, sondaggio, posizione, contatto, evento, reazione, modifica o eliminazione. Il tipo si sceglie con kind.

Corpo (JSON):

```json
{
  "kind": "testo",
  "conversationId": "00000000-0000-4000-8000-000000000001",
  "text": "Ciao, ti confermo l'appuntamento di domani.",
  "scheduledAt": "2026-12-01T09:00:00.000Z"
}
```

Limiti:

- Parte dopo 5 secondi, finché si può annullare; oltre i tetti del portale risponde 429.
- scheduledAt (testo, allegato, contenuto, evento) va da 1 minuto a 90 giorni; la partenza vera è sendAfter, con un ritardo casuale da 30 secondi a 3 minuti.
- Testo fino a 4096 caratteri, didascalia fino a 1024, sondaggio fino a 12 opzioni, menzioni fino a 10 (solo nei gruppi sincronizzati).
- Modifica entro 15 minuti, eliminazione per tutti entro 48 ore, solo dei propri messaggi.
- Un evento programmato deve iniziare almeno 5 minuti dopo l'ora di invio. Eventi, sondaggi, posizioni e contatti partono solo dai numeri collegati con QR.
- Con la chiave di idempotenza lo stesso invio parte una volta sola.
- Se il collegamento con QR è fermo o non sano, testo, vocale, immagine, video, documento, posizione e contatto partono da WhatsApp Business API, solo se il numero ce l'ha e il contatto ha scritto nelle ultime 24 ore; fuori finestra risponde qr-fermo-fuori-finestra. Il campo channel dice da dove è partito (qr o api); al titolare arriva un'email al giorno per numero.
- Sondaggio ed evento non cambiano canale: restano sul QR e aspettano il suo ritorno. Il ripiego scatta sempre prima dell'invio, mai dopo un esito incerto, quindi nessun doppio messaggio.

### Invii recenti di una chat e il loro stato

`invii.elenca` · GET /v2/invii · permesso «Invio messaggi»

Per controllare se un invio è partito o è fallito, prima che compaia nell'archivio.

Parametri (JSON):

```json
{
  "conversationId": "00000000-0000-4000-8000-000000000001"
}
```

Limiti:

- Con history=1 restituisce anche gli invii già ritrovati nell'archivio.

### Annulla un invio ancora in attesa

`invii.annulla` · POST /v2/invii/{id}/annulla · permesso «Invio messaggi»

Per fermare un invio ancora in attesa, anche un messaggio programmato prima della sua ora.

ID: `00000000-0000-4000-8000-000000000006`

Limiti:

- Dopo la partenza risponde 409.

### Segna una chat come letta fino a un messaggio (spunte blu se accese sul numero)

`chat.letta` · PUT /v2/chats/{id}/letta · permesso «Invio messaggi»

Per segnare una chat come letta fino a un messaggio, per esempio dopo che un flusso ha gestito la richiesta.

ID: `00000000-0000-4000-8000-000000000001`

Corpo (JSON):

```json
{
  "upTo": "00000000-0000-4000-8000-000000000002"
}
```

Limiti:

- upTo è l'id di un messaggio di quella chat; la lettura non torna mai indietro.
- Le spunte blu partono solo se sono accese sul numero; con il QR fermo e nessuna conferma via API la lettura aspetta il ritorno del QR.

### Tetti e fasce orarie degli invii

`invii.impostazioni` · GET /v2/invii/impostazioni · permesso «Invio messaggi»

Per sapere se «Rispondi da RisveglIA» è acceso e quali tetti valgono, prima di mandare messaggi.

Limiti:

- Solo lettura.

### Eventi mandati in una chat con le risposte (Ci sarò, Non ci sarò, Forse)

`eventi.elenca` · GET /v2/eventi-whatsapp · permesso «Chat e messaggi»

Per leggere gli eventi WhatsApp mandati e le risposte Ci sarò, Non ci sarò, Forse.

Parametri (JSON):

```json
{
  "conversationId": "00000000-0000-4000-8000-000000000001",
  "limit": 20
}
```

Limiti:

- Solo eventi mandati dai numeri collegati con QR.
- limit da 1 a 100, 20 se manca.

### Numeri mittenti con i canali collegati (QR, API) e modelli approvati

`numero.canali` · GET /v2/invii/numero/canali · permesso «Invio messaggi»

Per sapere da quale numero e su quale canale (QR o API) si può scrivere, e con quali template approvati.

Limiti:

- Dice anche se la presa d'atto per il primo messaggio via QR è stata fatta.

### Invia a un numero, anche nuovo (testo, file, sondaggio, posizione, contatto, pulsanti, lista, link o modello; QR o API)

`numero.invia` · POST /v2/invii/numero · permesso «Invio messaggi» · con chiave di idempotenza

Per scrivere a un numero di telefono, anche senza una chat in archivio: testo, file, contenuto o template approvato.

Corpo (JSON):

```json
{
  "numberId": "00000000-0000-4000-8000-000000000003",
  "phone": "+39 333 123 4567",
  "channel": "automatico",
  "text": "Ciao, grazie per averci contattato dal sito.",
  "consent": {
    "source": "Modulo contatti del sito",
    "date": "2026-11-20",
    "purpose": "utilita"
  }
}
```

Limiti:

- Uno solo fra testo, mediaId, content e templateId; canale Automatico, QR o API.
- Con canale Automatico, in una chat già aperta e senza primo contatto né modello, se un canale non è disponibile si passa all'altro (esito ripiego-api o ripiego-qr); un canale scelto esplicitamente viene sempre rispettato.
- Al primo messaggio a un numero nuovo servono il permesso «Primo messaggio», il consenso (fonte e data), il tetto giornaliero e la fascia 8-21; via QR anche la presa d'atto del titolare e il controllo che il numero sia su WhatsApp.
- Pulsanti (fino a 3), lista e link solo via API ufficiale ed entro 24 ore dall'ultimo messaggio del contatto; sondaggio e contatto solo via QR.
- Con la chiave di idempotenza lo stesso invio parte una volta sola.

### Il numero è su WhatsApp? (solo controllo, non scrive nulla)

`numero.verifica` · GET /v2/invii/numero/verifica · permesso «Invio messaggi»

Per sapere se un numero ha WhatsApp prima di scrivergli, senza aprire chat né mandare nulla.

Parametri (JSON):

```json
{
  "phone": "+39 333 123 4567",
  "numberId": "00000000-0000-4000-8000-000000000003"
}
```

Limiti:

- Usa il collegamento con QR del numero mittente; senza numberId il primo numero operativo, senza QR risponde 409.
- Al massimo 20 controlli al minuto e 300 al giorno per spazio, poi 429.

### Stato di un invio a un numero

`numero.dettaglio` · GET /v2/invii/numero/{id} · permesso «Invio messaggi»

Per sapere com'è andato un invio a un numero: canale usato, chat creata ed eventuale errore.

ID: `00000000-0000-4000-8000-000000000006`

Limiti:

- L'id è quello restituito da «Invia a un numero».

### Allegati di un messaggio o di una chat (immagini, vocali, video, documenti)

`allegati.elenca` · GET /v2/allegati · permesso «Chat e messaggi»

Per trovare gli allegati di un messaggio o gli ultimi di una chat, con la trascrizione dei vocali.

Parametri (JSON):

```json
{
  "conversationId": "00000000-0000-4000-8000-000000000001",
  "kind": "document",
  "limit": 20
}
```

Limiti:

- Serve messageId o conversationId.
- limit da 1 a 50, 20 se manca.

### Dati di un allegato, con il file in base64 (contenuto=base64)

`allegati.dettaglio` · GET /v2/allegati/{id} · permesso «Chat e messaggi»

Per i dati di un allegato e, con contenuto=base64, il file dentro il JSON.

ID: `00000000-0000-4000-8000-000000000006`

Parametri (JSON):

```json
{
  "contenuto": "base64"
}
```

Limiti:

- Il base64 arriva fino a 12 MB; oltre si usa «File di un allegato».

### Testo leggibile di un allegato (PDF, Word, Excel, PowerPoint, TXT, MD, CSV, vocali trascritti)

`allegati.testo` · GET /v2/allegati/{id}/testo · permesso «Chat e messaggi»

Per avere il testo di un documento (PDF, Word, Excel, PowerPoint, TXT, MD, CSV, JSON) o la trascrizione di un vocale.

ID: `00000000-0000-4000-8000-000000000006`

Limiti:

- Se il testo non si legge, text.state è unreadable con il motivo.

### Scarica il file di un allegato

`allegati.file` · GET /v2/allegati/{id}/file · permesso «Chat e messaggi» · restituisce un file

Per scaricare il file così com'è: in n8n arriva in un campo binario.

ID: `00000000-0000-4000-8000-000000000006`

Limiti:

- Fino a 64 MB.

### Trascrive un vocale con la chiave AI dell'account

`vocali.trascrivi` · POST /v2/trascrizioni/{id} · permesso «Chat e messaggi»

Per trascrivere un vocale che non ha ancora la trascrizione.

ID: `00000000-0000-4000-8000-000000000006`

Limiti:

- Usa la chiave AI dell'account, dentro il tetto di spesa del mese; una trascrizione già fatta non si ripaga.

## Contatti e trattative

### Elenca le etichette

`etichette.elenca` · GET /v2/etichette · permesso «Contatti»

Per avere gli id delle etichette di RisveglIA e di WhatsApp Business.

Limiti:

- Solo lettura.

### Crea un'etichetta

`etichette.crea` · POST /v2/etichette · permesso «Contatti e trattative»

Per creare un tag di RisveglIA o, con numberId, un'etichetta WhatsApp Business sul telefono.

Corpo (JSON):

```json
{
  "name": "Cliente caldo",
  "color": "#2E7D32"
}
```

Limiti:

- Nome fino a 40 caratteri; lo stesso nome restituisce il tag che c'è già.
- L'etichetta WhatsApp Business va in coda sul telefono (202).

### Imposta le etichette di una chat

`chat.etichette` · PUT /v2/chats/{id}/etichette · permesso «Contatti e trattative»

Per impostare le etichette di una chat: sostituisce quelle che ha.

ID: `00000000-0000-4000-8000-000000000001`

Corpo (JSON):

```json
{
  "labelIds": [
    "00000000-0000-4000-8000-000000000005"
  ]
}
```

Limiti:

- Fino a 20 etichette per tipo.
- Le etichette WhatsApp Business vanno sul telefono con una scrittura in coda.

### Crea un promemoria

`promemoria.crea` · POST /v2/reminders · permesso «Contatti e trattative» · con chiave di idempotenza

Per creare un promemoria, legato o no a una chat.

Corpo (JSON):

```json
{
  "title": "Richiamare per il preventivo",
  "chatId": "00000000-0000-4000-8000-000000000001",
  "dueAt": "2026-12-02T08:30:00.000Z",
  "timezone": "Europe/Rome"
}
```

Limiti:

- timezone è obbligatorio; titolo fino a 500 caratteri.
- Con la chiave di idempotenza lo stesso corpo restituisce lo stesso promemoria.

### Aggiorna o chiude un promemoria

`promemoria.aggiorna` · PATCH /v2/reminders/{id} · permesso «Contatti e trattative»

Per cambiare titolo, scadenza o stato (todo o done) di un promemoria.

ID: `00000000-0000-4000-8000-000000000006`

Corpo (JSON):

```json
{
  "status": "done",
  "version": 1
}
```

Limiti:

- version è quella letta per ultima: se nel frattempo è cambiata risponde 409.

### Elimina un promemoria

`promemoria.elimina` · DELETE /v2/reminders/{id} · permesso «Contatti e trattative»

Per eliminare un promemoria.

ID: `00000000-0000-4000-8000-000000000006`

Parametri (JSON):

```json
{
  "version": 1
}
```

Limiti:

- version è quella letta per ultima: se nel frattempo è cambiata risponde 409.

### Pipeline, fasi e card delle trattative

`trattative.board` · GET /v2/trattative · permesso «Opportunità»

Per leggere pipeline, colonne e card con segnali e prossimo passo.

Parametri (JSON):

```json
{
  "pipeline": "00000000-0000-4000-8000-000000000006"
}
```

Limiti:

- Senza pipeline legge quella predefinita.

### Mette una chat in una pipeline

`trattative.card.crea` · POST /v2/trattative/card · permesso «Contatti e trattative»

Per aggiungere una chat a una pipeline.

Corpo (JSON):

```json
{
  "chatId": "00000000-0000-4000-8000-000000000001",
  "stageId": "00000000-0000-4000-8000-000000000007",
  "value": 1500
}
```

Limiti:

- Senza pipelineId usa la pipeline predefinita; valore fino a 1.000.000.000.

### Sposta o aggiorna una card

`trattative.card.sposta` · PATCH /v2/trattative/card/{id} · permesso «Contatti e trattative»

Per spostare una card di colonna (anche in un'altra pipeline) o cambiarne valore e nota.

ID: `00000000-0000-4000-8000-000000000006`

Corpo (JSON):

```json
{
  "version": 3,
  "stageId": "00000000-0000-4000-8000-000000000007",
  "note": "Ha chiesto il preventivo"
}
```

Limiti:

- version è quella letta per ultima: se nel frattempo è cambiata risponde 409.
- Nota fino a 1000 caratteri.

### Toglie una card dalla pipeline

`trattative.card.elimina` · DELETE /v2/trattative/card/{id} · permesso «Contatti e trattative»

Per togliere una card dalla sua pipeline: la chat resta in archivio.

ID: `00000000-0000-4000-8000-000000000006`

Parametri (JSON):

```json
{
  "version": 3
}
```

Limiti:

- version è quella letta per ultima: se nel frattempo è cambiata risponde 409.

### Registra un consenso o una disiscrizione

`consensi.registra` · POST /v2/consensi · permesso «Contatti e trattative»

Per registrare un consenso o una revoca per alcune chat, per un tag o per una lista.

Corpo (JSON):

```json
{
  "conversationIds": [
    "00000000-0000-4000-8000-000000000001"
  ],
  "purpose": "marketing",
  "action": "concesso",
  "evidence": "Spunta sul modulo del sito",
  "givenAt": "2026-11-20T10:00:00.000Z",
  "declaration": true
}
```

Limiti:

- Fino a 500 chat per richiesta.
- Il registro non si modifica: una revoca è una nuova voce.

### Elenca i numeri esclusi dalle automazioni

`esclusioni.elenca` · GET /v2/esclusioni · permesso «Contatti»

Per leggere numeri, contatti ed etichette esclusi dalle automazioni.

Limiti:

- Solo lettura.

### Esclude un numero dalle automazioni

`esclusioni.crea` · POST /v2/esclusioni · permesso «Contatti e trattative»

Per escludere dalle automazioni un numero, un contatto o un'etichetta.

Corpo (JSON):

```json
{
  "kind": "numero",
  "phone": "+393331234567",
  "note": "Ha chiesto di non ricevere messaggi automatici"
}
```

Limiti:

- Il numero va nel formato internazionale con il +, senza spazi.
- Etichetta come whatsapp:<nome> o risveglia:<nome>.

### Toglie un'esclusione

`esclusioni.elimina` · DELETE /v2/esclusioni/{id} · permesso «Contatti e trattative»

Per togliere una voce dagli esclusi.

ID: `00000000-0000-4000-8000-000000000006`

Limiti:

- L'id è quello restituito da «Esclusi dalle automazioni».

## Telefonate

### Rifiuta una chiamata che sta squillando (solo entro pochi secondi)

`chiamate.rifiuta` · POST /v2/chiamate/{id}/rifiuta · permesso «Invio messaggi»

Per rifiutare una chiamata che sta ancora squillando, con l'id che arriva dall'evento «Chiamata ricevuta» (data.callId).

ID: `00000000-0000-4000-8000-000000000006`

Limiti:

- Solo nei primi secondi della chiamata.
- Serve la presa d'atto delle regole sulle chiamate nel portale, altrimenti 428.

## Gruppi e canali

### Elenca gruppi, community e canali

`spazi.elenca` · GET /v2/spazi · permesso «Gruppi e canali»

Per avere gli id di gruppi, community e canali di un numero.

Parametri (JSON):

```json
{
  "numberId": "00000000-0000-4000-8000-000000000003",
  "kind": "gruppo"
}
```

Limiti:

- Legge quello che il telefono ha restituito.

### Dettaglio di un gruppo o canale

`spazi.dettaglio` · GET /v2/spazi/{id} · permesso «Gruppi e canali»

Per partecipanti, richieste di ingresso e link di invito di un gruppo o canale.

ID: `00000000-0000-4000-8000-000000000009`

Limiti:

- Solo lettura.

### Crea un gruppo

`spazi.gruppo.crea` · POST /v2/spazi/gruppi · permesso «Gruppi e canali»

Per creare un gruppo dal numero con alcuni contatti.

Corpo (JSON):

```json
{
  "numberId": "00000000-0000-4000-8000-000000000003",
  "name": "Clienti corso di dicembre",
  "conversationIds": [
    "00000000-0000-4000-8000-000000000001"
  ],
  "settings": {
    "messagesAdminOnly": true
  }
}
```

Limiti:

- Solo contatti che hanno scritto negli ultimi 180 giorni, fino a 50.
- Al massimo 5 gruppi al giorno.
- Risponde 202 se il telefono non ha ancora restituito il gruppo.

### Crea un canale

`spazi.canale.crea` · POST /v2/spazi/canali · permesso «Gruppi e canali»

Per creare un canale dal numero.

Corpo (JSON):

```json
{
  "numberId": "00000000-0000-4000-8000-000000000003",
  "name": "Novità dello studio",
  "description": "Aggiornamenti e offerte"
}
```

Limiti:

- Risponde 202 se il telefono non ha ancora restituito il canale.

### Impostazioni, amministratori, rimozioni, richieste e link di invito

`spazi.azione` · POST /v2/spazi/{id}/azioni · permesso «Gruppi e canali»

Per cambiare nome, descrizione o impostazioni, gestire amministratori e partecipanti, richieste di ingresso, link, uscita o chiusura di un gruppo o canale.

ID: `00000000-0000-4000-8000-000000000009`

Corpo (JSON):

```json
{
  "action": "impostazione",
  "setting": "approvalRequired",
  "value": true
}
```

Limiti:

- Fino a 50 partecipanti per azione.
- esci vuole confirm: true; elimina e svuota-chiudi vogliono anche confirmName uguale al nome del gruppo.

### Contatti invitabili in un gruppo

`spazi.invitabili` · GET /v2/spazi/{id}/contatti · permesso «Gruppi e canali»

Per trovare le chat individuali da invitare in un gruppo.

ID: `00000000-0000-4000-8000-000000000009`

Parametri (JSON):

```json
{
  "q": "Rossi",
  "limit": 200
}
```

Limiti:

- Dice chi è già stato invitato negli ultimi 30 giorni.
- limit da 1 a 500.

### Mette in coda gli inviti, con i tetti giornalieri

`spazi.inviti.crea` · POST /v2/spazi/{id}/inviti · permesso «Gruppi e canali»

Per mettere in coda gli inviti a un gruppo: un messaggio col link alla volta.

ID: `00000000-0000-4000-8000-000000000009`

Corpo (JSON):

```json
{
  "conversationIds": [
    "00000000-0000-4000-8000-000000000001"
  ],
  "mode": "messaggio",
  "body": "Ti va di entrare nel gruppo dei clienti? {link}",
  "linkRiskAccepted": true,
  "dailyCap": 20
}
```

Limiti:

- Fino a 500 chat per coda.
- Con mode messaggio il testo deve contenere {link}, dove va il link del gruppo, e linkRiskAccepted: true conferma di aver letto l'avviso sul messaggio privato.
- Tetto giornaliero da 1 a 40 (20 se manca), a distanza casuale e nelle fasce consentite.

### Code degli inviti

`spazi.inviti.elenca` · GET /v2/spazi/inviti · permesso «Gruppi e canali»

Per leggere le code degli inviti con i conteggi per stato.

Parametri (JSON):

```json
{
  "spaceId": "00000000-0000-4000-8000-000000000009"
}
```

Limiti:

- Dalla più recente.

### Stato di una coda degli inviti

`spazi.inviti.dettaglio` · GET /v2/spazi/inviti/{id} · permesso «Gruppi e canali»

Per lo stato di ogni contatto di una coda degli inviti.

ID: `00000000-0000-4000-8000-000000000006`

Limiti:

- Solo lettura.

### Mette in pausa, riprende o annulla una coda degli inviti

`spazi.inviti.azione` · POST /v2/spazi/inviti/{id}/{azione} · permesso «Gruppi e canali»

Per mettere in pausa, riprendere o annullare una coda degli inviti.

ID: `00000000-0000-4000-8000-000000000006`

Azione: `pausa`

Limiti:

- Azione: pausa, riprendi o annulla.

### Elenca le pubblicazioni

`pubblicazioni.elenca` · GET /v2/pubblicazioni · permesso «Gruppi e canali»

Per leggere le pubblicazioni in gruppi, canali e stato, con gli invii scaduti da decidere.

Limiti:

- Serve la funzione Pubblicazioni attiva e la presa d'atto nel portale.

### Gruppi, canali e stato dove si può pubblicare

`pubblicazioni.destinazioni` · GET /v2/pubblicazioni/destinazioni · permesso «Gruppi e canali»

Per sapere in quali gruppi e canali di un numero si può pubblicare, e chi vede lo stato.

Parametri (JSON):

```json
{
  "numero": "00000000-0000-4000-8000-000000000003"
}
```

Limiti:

- Per le destinazioni escluse dice il motivo.

### Crea una pubblicazione in gruppi, canali o stato

`pubblicazioni.crea` · POST /v2/pubblicazioni · permesso «Gruppi e canali»

Per preparare un post in gruppi o canali, o una storia nello stato, anche ripetuta.

Corpo (JSON):

```json
{
  "numberId": "00000000-0000-4000-8000-000000000003",
  "title": "Offerta del weekend",
  "body": "Sabato e domenica sconto del 10%.",
  "mediaId": "00000000-0000-4000-8000-000000000004",
  "spaceIds": [
    "00000000-0000-4000-8000-000000000009"
  ],
  "statusEnabled": true,
  "statusAudience": "rubrica",
  "startsAt": "2026-12-05T08:00:00.000Z",
  "recurrence": "settimana",
  "repeatUntil": "2027-01-31"
}
```

Limiti:

- Nasce in bozza: per farla partire serve «Programma una pubblicazione».
- Titolo fino a 120 caratteri, testo fino a 2000, fino a 30 gruppi o canali.
- Pubblico della storia (statusAudience): «rubrica» (di partenza, contatti salvati più chat), «chat» o «lista» con statusListId.

### Dettaglio di una pubblicazione

`pubblicazioni.dettaglio` · GET /v2/pubblicazioni/{id} · permesso «Gruppi e canali»

Per l'esito di ogni destinazione di una pubblicazione, giro per giro.

ID: `00000000-0000-4000-8000-000000000006`

Limiti:

- Senza nomi né numeri delle persone.

### Programma, mette in pausa o annulla una pubblicazione

`pubblicazioni.azione` · POST /v2/pubblicazioni/{id}/{azione} · permesso «Gruppi e canali»

Per programmare, mettere in pausa, riprendere o annullare una pubblicazione.

ID: `00000000-0000-4000-8000-000000000006`

Azione: `programma`

Limiti:

- Azione: programma, pausa, riprendi o annulla.

## Agente AI

### Impostazioni dell'agente e chat in pausa

`agente.stato` · GET /v2/agente · permesso «Agente AI»

Per sapere se l'agente AI è attivo, su quali numeri, e quali chat sono in pausa.

Limiti:

- Le ultime decisioni arrivano senza il testo dei messaggi.

### Fa riprendere l'agente in una chat in pausa

`agente.riprendi` · POST /v2/agente/pause/{id}/riprendi · permesso «Agente AI»

Per far ripartire l'agente in una chat dove si era fermato.

ID: `00000000-0000-4000-8000-000000000006`

Limiti:

- L'id è quello della pausa letto da «Stato dell'agente AI».

## Fonti

### Elenca i file delle fonti con stato e versione

`fonti.elenca` · GET /v2/files · permesso «File e documenti»

Per leggere i file caricati come fonti, con stato, ambito e versione.

Parametri (JSON):

```json
{
  "chatId": "00000000-0000-4000-8000-000000000001"
}
```

Limiti:

- Senza chatId elenca tutti i file.

### Stato di un file delle fonti (in elaborazione, pronto, non leggibile)

`fonti.dettaglio` · GET /v2/files/{id} · permesso «File e documenti»

Per sapere se un file caricato è pronto.

ID: `00000000-0000-4000-8000-000000000006`

Limiti:

- Solo lettura.

### Carica o sostituisci un file nelle fonti: con lo stesso nome sostituisce il precedente quando il nuovo è pronto

`fonti.carica` · POST /v2/files/fonte · permesso «File e documenti»

Per tenere aggiornato un file delle fonti dell'agente da un flusso (per esempio i dati di una scheda Google Maps).

Corpo (JSON):

```json
{
  "name": "orari-e-servizi.md",
  "content": "# Orari\nDal lunedì al venerdì, 9-19."
}
```

Limiti:

- Nome da 5 a 200 caratteri, che finisce in .txt, .md, .pdf o .docx.
- Testo fino a 200.000 caratteri, oppure il file in contentBase64.
- Con lo stesso nome sostituisce il file precedente quando il nuovo è pronto; contenuto uguale, nessuna versione nuova.
- Serve il permesso «File e documenti», solo per titolare e amministrazione.

## Media

### Elenca la libreria media

`media.elenca` · GET /v2/media · permesso «Libreria media»

Per avere gli id dei file della libreria da mandare nei messaggi o nelle pubblicazioni.

Parametri (JSON):

```json
{
  "kind": "immagine",
  "usable": "1"
}
```

Limiti:

- Con usable=1 solo i file già controllati e pronti.

### Dettaglio e stato di una generazione

`media.dettaglio` · GET /v2/media/{id} · permesso «Libreria media»

Per sapere se un file della libreria è pronto.

ID: `00000000-0000-4000-8000-000000000004`

Limiti:

- Solo lettura.

### Scarica il file di un media

`media.file` · GET /v2/media/{id}/file · permesso «Libreria media» · restituisce un file

Per scaricare un file della libreria.

ID: `00000000-0000-4000-8000-000000000004`

Limiti:

- Mai prima del controllo antivirus.

### Stato della chiave fal.ai e budget

`media.fal` · GET /v2/media/fal · permesso «Libreria media»

Per sapere se c'è la chiave fal.ai e quali modelli si possono usare, con il prezzo.

Limiti:

- La chiave non si vede mai.

### Stima il costo di una generazione

`media.stima` · POST /v2/media/fal/stima · permesso «Libreria media»

Per conoscere il costo di una generazione prima di avviarla.

Corpo (JSON):

```json
{
  "model": "fal-ai/flux/schnell",
  "prompt": "Vetrina di un negozio di fiori al mattino, luce calda",
  "format": "quadrato"
}
```

Limiti:

- Il prezzo lo legge da fal.ai in quel momento.
- Prompt da 3 a 4000 caratteri; i video durano 5 o 10 secondi.

### Genera un'immagine o un video con fal.ai

`media.genera` · POST /v2/media/genera · permesso «Libreria media»

Per generare un'immagine o un video con fal.ai, dopo la stima.

Corpo (JSON):

```json
{
  "model": "fal-ai/flux/schnell",
  "prompt": "Vetrina di un negozio di fiori al mattino, luce calda",
  "format": "quadrato",
  "name": "Vetrina mattino",
  "confirmedCostUsd": 0.01
}
```

Limiti:

- confirmedCostUsd è il costo della stima: se nel frattempo è cambiato risponde 409.
- Usa la chiave fal.ai del cliente.

### Importa un file da un link nella libreria, per mandarlo in chat

`media.da-link` · POST /v2/media/da-link · permesso «Libreria media»

Per portare nella libreria un file da un link pubblico (Drive condiviso, sito, CDN) e poi mandarlo o pubblicarlo.

Corpo (JSON):

```json
{
  "url": "https://www.example.com/locandina.jpg",
  "name": "Locandina dicembre"
}
```

Limiti:

- Solo link https pubblici; niente reti private.
- Antivirus e conversione per WhatsApp avvengono dopo: si usa il file quando «Stato di un file della libreria» dice che è pronto.

## Campagne e automazioni

### Elenca i modelli di messaggio approvati

`template.elenca` · GET /v2/waba/template · permesso «Campagne»

Per avere gli id dei template approvati da Meta, con stato, categoria e qualità.

Parametri (JSON):

```json
{
  "connectionId": "00000000-0000-4000-8000-000000000010"
}
```

Limiti:

- Serve il numero sull'API ufficiale di WhatsApp Business.

### Elenca le liste dei destinatari

`liste.elenca` · GET /v2/liste · permesso «Campagne»

Per leggere le liste dei destinatari delle campagne con i conteggi per consenso.

Limiti:

- Serve il numero sull'API ufficiale di WhatsApp Business.

### Simula un'automazione sugli ultimi 30 giorni

`automazioni.simula` · POST /v2/automazioni/simula · permesso «Automazioni»

Per provare una sequenza o un flusso sugli ultimi 30 giorni prima di accenderlo nel portale.

Corpo (JSON):

```json
{
  "spec": {
    "schemaVersion": 1,
    "kind": "sequenza",
    "trigger": {
      "type": "parola.chiave",
      "stageId": "00000000-0000-4000-8000-000000000007",
      "keywords": [
        "listino"
      ]
    },
    "steps": [
      {
        "type": "whatsapp.testo",
        "text": "Ecco il listino aggiornato."
      }
    ],
    "channel": {
      "type": "whatsapp-business-api",
      "connectionId": "00000000-0000-4000-8000-000000000010"
    }
  }
}
```

Limiti:

- Non invia nulla: dice quanti messaggi sarebbero partiti e perché gli altri no.
- Accendere flussi e sequenze o avviare campagne si fa solo dal portale.

### Elenca le esecuzioni delle automazioni

`automazioni.esecuzioni` · GET /v2/flussi/esecuzioni · permesso «Automazioni»

Per leggere i messaggi automatici mandati per una trattativa o da un flusso, con l'esito di Meta.

Parametri (JSON):

```json
{
  "card": "00000000-0000-4000-8000-000000000006"
}
```

Limiti:

- Serve card oppure flow.

## Attivatori

### Elenca gli indirizzi iscritti

`webhook.elenca` · GET /v2/webhook · permesso «Attivatori»

Per leggere gli indirizzi iscritti alle attività dello spazio.

Limiti:

- Del segreto si vedono solo le ultime 4 cifre.

### Iscrive un indirizzo alle attività

`webhook.iscrivi` · POST /v2/webhook · permesso «Attivatori»

Per mandare le attività a un indirizzo tuo. In n8n e Make lo fa già l'attivatore RisveglIA.

Corpo (JSON):

```json
{
  "name": "CRM",
  "url": "https://crm.example.com/risveglia",
  "events": [
    "message.received",
    "message.status"
  ]
}
```

Limiti:

- Solo https.
- Il segreto della firma si vede solo nella risposta di questa operazione.

### Toglie un indirizzo iscritto

`webhook.elimina` · DELETE /v2/webhook/{id} · permesso «Attivatori»

Per togliere un indirizzo iscritto, con il suo registro delle consegne.

ID: `00000000-0000-4000-8000-000000000006`

Limiti:

- Il registro delle consegne si cancella con l'iscrizione.

### Manda un evento di prova

`webhook.prova` · POST /v2/webhook/{id}/prova · permesso «Attivatori»

Per mandare subito un evento di prova (webhook.test) e vedere se arriva.

ID: `00000000-0000-4000-8000-000000000006`

Limiti:

- Restituisce l'esito della consegna.

### Registro delle consegne

`webhook.consegne` · GET /v2/webhook/{id}/consegne · permesso «Attivatori»

Per controllare quali eventi sono arrivati e quali no.

ID: `00000000-0000-4000-8000-000000000006`

Parametri (JSON):

```json
{
  "stato": "fallito",
  "limit": 50
}
```

Limiti:

- Ultimi 30 giorni, dalla più recente.
- limit da 1 a 200.

## Account

### Numeri collegati e stato del collegamento

`numeri.elenca` · GET /v2/numeri · permesso «Chat e messaggi»

Per avere gli id dei numeri collegati (numberId) da usare nelle altre operazioni.

Limiti:

- Elenca solo i numeri che vede la persona che ha creato il token.
