# Sondaggi

> Come fare una domanda alla community in uno spazio Feed o Contenuti: creare il sondaggio (opzioni, scelta multipla, scadenza), votare, cambiare e ritirare il voto, chi vede il risultato e quando, modificare, vedere chi ha votato, chiudere, e le stesse azioni tramite l'API e l'assistente.

Il **sondaggio** è un post con una domanda e da 2 a 10 opzioni su cui la community vota. Nasce in uno spazio [Feed](/espacos/feed) (come uno status, dove la domanda è il testo) o [Contenuti](/espacos/conteudo) (come un post, dove la domanda è il titolo), e per il resto è un post come gli altri: compare nel Feed, riceve reazioni e commenti, si può fissare e notifica come un post nuovo.

Il sondaggio esiste solo negli spazi Feed o Contenuti; in un altro tipo di spazio, l'API lo rifiuta.

## A cosa serve

| Community | Sondaggio |
|---|---|
| Evento | *"Qual è il mese migliore per l'APICON Rio?"*, con marzo, aprile e maggio |
| Scuola online | *"Che tema vuoi nella prossima lezione dal vivo?"*, con scelta multipla |
| Coworking | *"Quale orario delle pulizie disturba meno?"*, con scadenza venerdì |
| Associazione | Una consultazione rapida prima dell'assemblea, con il risultato chiuso alla scadenza |

## Come funziona

### Chi può fare cosa

| Azione | Chi |
|---|---|
| Creare un sondaggio | Proprietario, admin e moderatore |
| Votare, cambiare e ritirare il voto | Qualsiasi membro che vede il post |
| Vedere il risultato | Lo staff, sempre; gli altri membri, dopo aver votato o quando il sondaggio è chiuso |
| Modificare, vedere chi ha votato e chiudere | Proprietario, admin e moderatore |

Il ruolo finanza vota come qualsiasi membro, ma non crea né gestisce sondaggi. Chi vede il post senza aver effettuato l'accesso trova **Accedi per votare**; chi ha effettuato l'accesso ma non è membro della community vede *Votano solo i membri della community*.

### Scelta singola o multipla

La scheda mostra il badge **Sondaggio** e, sotto la domanda, **Scegli un'opzione** o **Scegli una o più opzioni**:

- **Un'opzione**: cliccare sull'opzione vota subito.
- **Scelta multipla** (quando il sondaggio è stato creato con **Consenti più scelte**): la persona seleziona le opzioni e clicca su **Vota**.

Dopo il voto, l'opzione scelta resta segnata come **Il tuo voto**, e compaiono **Cambia voto** e **Ritira voto**. Finché il sondaggio è aperto, si può cambiare o ritirare il voto tutte le volte che si vuole.

### Chi vede il risultato

- **I membri** vedono le barre con la percentuale e il totale **dopo aver votato**, o quando il sondaggio **è chiuso**. Prima, la scheda mostra **Vota per vedere il risultato**.
- **Lo staff** (proprietario, admin e moderatore) vede sempre il risultato, che abbia votato o no.

La percentuale di ogni opzione è calcolata su **chi ha votato**, non sul totale dei voti. In un sondaggio a scelta multipla la somma supera il 100%: se hanno votato 10 persone e 7 hanno scelto marzo, marzo ha il 70%, anche se hanno scelto anche altre opzioni. In fondo compare *"N persone hanno votato"* (o *Nessuno ha ancora votato*).

### Scadenza e chiusura

Con una **Scadenza**, il sondaggio si chiude da solo alla data e all'ora scelte, nel fuso orario della community, e la scheda mostra **Chiude il …** fino ad allora. Senza scadenza, resta aperto finché qualcuno dello staff non clicca su **Chiudi sondaggio**.

Chiuso, riceve il badge **Chiuso** e la riga **Chiuso il …**: nessuno vota, cambia o ritira più il voto, e tutti vedono il risultato finale. I voti restano salvati. **Un sondaggio chiuso non si può riaprire.**

### Voti anonimi per i membri

I membri vedono solo i numeri. Chi ha votato cosa lo vede solo lo staff, in **Vedi chi ha votato**.

### Notifica

Il sondaggio segue il percorso di un post nuovo nello spazio: le stesse notifiche ed e-mail di uno status nel Feed o di un post in Contenuti, secondo le preferenze di ciascuno. Votare non notifica nessuno.

## Passo dopo passo

### Creare un sondaggio

*Ruolo: proprietario, admin o moderatore.*

1. Apri lo spazio Feed o Contenuti.
2. Nell'intestazione, clicca sulla freccia accanto a **Nuovo Status** (in Contenuti, **Nuovo Contenuto**) e scegli **Nuovo sondaggio**. Nello stesso menu c'è **Importa contenuti**, che vedono solo il proprietario e l'admin.
3. Compila:
   - **Domanda**: nel Feed è il testo dello status (fino a 500 caratteri); in Contenuti è il titolo del post (fino a 255).
   - **Opzioni**: da 2 a 10, fino a 100 caratteri ciascuna, senza ripetizioni. **Aggiungi opzione** ne aggiunge una; la **×** la toglie.
   - **Consenti più scelte**: ogni persona può selezionare più di un'opzione.
   - **Chi lo vede**, solo nel Feed: **Pubblico** (predefinito), **Membri** o **Abbonati**, come in **Nuovo Status**. In Contenuti non c'è scelta: il sondaggio esce pubblico, come **Nuovo Contenuto**.
   - **Scadenza (facoltativa)**: data e ora nel fuso orario della community, che la schermata mostra. **Senza scadenza** la toglie.
4. Clicca su **Pubblica sondaggio**.

In Contenuti, il post nasce solo con la domanda come titolo. Per aggiungere un testo sotto, modifica il post dopo.

### Votare

1. Nella scheda del sondaggio, clicca sull'opzione (in un sondaggio a scelta singola, questo vota già).
2. In un sondaggio a scelta multipla, seleziona le opzioni e clicca su **Vota**.
3. Per cambiare, **Cambia voto**; per rinunciare, **Ritira voto**.

### Modificare un sondaggio

*Ruolo: proprietario, admin o moderatore.*

Nel menu **⋮** della scheda, **Modifica sondaggio**.

- **Prima del primo voto**, si può cambiare tutto: le opzioni (testo, ordine, aggiungere e togliere), **Consenti più scelte** e la scadenza.
- **Dopo il primo voto**, le opzioni non cambiano più, né il testo né l'ordine: i campi compaiono disabilitati (*"Ci sono già voti: le opzioni non cambiano più, per non alterare ciò che le persone hanno scelto."*), e **Consenti più scelte** resta bloccato. La domanda resta modificabile dal post, e la scadenza si può ancora mettere, spostare o togliere.
- **Chiuso senza voti**, solo il testo delle opzioni.

La domanda è il testo (o il titolo) del post: per cambiarla, modifica il post.

### Vedere chi ha votato

*Ruolo: proprietario, admin o moderatore.*

Nel menu **⋮** della scheda, **Vedi chi ha votato**. La finestra **Chi ha votato** elenca le persone, dal voto più recente al più vecchio, con le opzioni di ciascuna. **Filtra per opzione** mostra solo chi ne ha scelta una.

### Chiudere

*Ruolo: proprietario, admin o moderatore.*

1. Nel menu **⋮** della scheda, **Chiudi sondaggio**.
2. Conferma con **Chiudi**. Non si torna indietro: il sondaggio non si può riaprire.

## Esempi

**Data dell'evento.** Nel Feed della Home: *"Qual è il mese migliore per l'APICON Rio?"*, con marzo, aprile e maggio, scelta singola e scadenza a fine mese. Fissalo in alto perché tutti lo vedano.

**Tema della prossima lezione.** In uno spazio Contenuti della classe: *"Che tema vuoi nella prossima lezione dal vivo?"*, con cinque temi e **Consenti più scelte**. Lo staff segue il risultato dal primo voto e lo chiude quando decide.

## Errori comuni e come risolverli

| Situazione | Cosa fare |
|---|---|
| **Nuovo sondaggio** non compare nel menu | Solo il proprietario, l'admin e il moderatore creano sondaggi |
| *Il sondaggio richiede almeno 2 opzioni.* o *Il sondaggio può avere fino a 10 opzioni.* | Regola il numero di opzioni |
| *Ci sono opzioni ripetute.* | Due opzioni hanno lo stesso testo (maiuscole e minuscole non contano): cambiane una |
| *Scegli una scadenza nel futuro.* | La scadenza è già passata; scegli un'altra data o lascia senza scadenza |
| Le opzioni non si possono modificare | Il sondaggio ha già voti: le opzioni restano come sono state votate. Per un'altra domanda, crea un altro sondaggio |
| Il membro non vede il risultato | Non ha ancora votato e il sondaggio è aperto |
| Non si riesce a votare | Il sondaggio è chiuso |

## Domande frequenti

**Si può riaprire un sondaggio chiuso?**
No. Per chiedere di nuovo, creane un altro.

**Si può trasformare un post esistente in sondaggio?**
No. Il sondaggio nasce con il post, in **Nuovo sondaggio**.

**Eliminare il post elimina il sondaggio?**
Sì, il sondaggio se ne va con il post.

**I membri sanno cosa ho votato?**
No. Solo lo staff vede chi ha votato cosa.

## Tramite l'assistente

L'assistente crea, vota e segue i sondaggi con le stesse regole:

- `create_poll`: lo crea nel Feed (la domanda è il testo) o in Contenuti (la domanda è il titolo). Proprietario, admin e moderatore, senza conferma.
- `get_poll`: il risultato. Qualsiasi ruolo; per chi non ha votato, i numeri restano nascosti finché il sondaggio non si chiude.
- `vote_poll` (per opzione o per il suo testo) e `retract_poll_vote`: a nome di chi ha collegato l'assistente, senza conferma.
- `update_poll`: modifica, e chiede conferma quando cambiano le opzioni. `close_poll`: chiude, sempre con conferma. `list_poll_votes`: chi ha votato. Questi tre sono dello staff.

Chiedi così: *"Crea un sondaggio nel Feed chiedendo qual è il mese migliore per l'APICON Rio, con marzo, aprile e maggio."* In Claude, la ricetta **Chiedi alla community (sondaggio)** prepara la richiesta. Vedi [Strumenti · Contenuti](/mcp/ferramentas-conteudo#sondaggi).

## Nell'API

Il sondaggio va nel campo `poll` di `POST /api/status` (Feed) e di `POST /api/content` (Contenuti): `options` (da 2 a 10 testi), `allowMultiple` e `closesAt` (facoltativo, nel futuro). Solo proprietario, admin e moderatore; un altro ruolo riceve `403` con `param: "poll"`, e non viene salvato nulla. `poll` arriva negli elementi di `GET /api/feed`, negli status, nei contenuti e nei suggerimenti.

| Rotta | Cosa fa | Chi |
|---|---|---|
| `GET /api/polls/{id}` | Il risultato, come la persona può vederlo | Chi vede il post |
| `POST /api/polls/{id}/vote` | Vota (`optionIds`); votare di nuovo cambia il voto | Membro che vede il post |
| `DELETE /api/polls/{id}/vote` | Ritira il voto | Membro che vede il post |
| `PUT /api/polls/{id}` | Modifica opzioni, `allowMultiple` e `closesAt` | Proprietario, admin e moderatore |
| `POST /api/polls/{id}/close` | Chiude, senza ritorno | Proprietario, admin e moderatore |
| `GET /api/polls/{id}/votes` | Chi ha votato, con filtro `optionId` | Proprietario, admin e moderatore |

Per chi non può vedere il risultato, `resultsVisible` è `false`, e `votes`, `percentage` e `totalVoters` sono `null` (nascosti, non zero).

| Errore | Quando |
|---|---|
| `400` | Spazio che non è Feed né Contenuti, meno di 2 o più di 10 opzioni, opzione vuota o oltre 100 caratteri, opzione ripetuta, scadenza nel passato o non valida, più di un'opzione in un voto a scelta singola |
| `403` | Il ruolo non crea né gestisce sondaggi, o la persona non è membro della community |
| `404` | Il sondaggio non esiste o è di un'altra community |
| `409` | `closed` (il sondaggio è chiuso) o `optionsLocked` (cambiare le opzioni, testo o ordine compresi, dopo il primo voto); anche quando si prova a cambiare `allowMultiple` con voti |

Vedi [Polls](/api/referencia/polls).

## Correlati

- [Feed](/espacos/feed)
- [Contenuti](/espacos/conteudo)
- [Ruoli e permessi](/conceitos/papeis-e-permissoes)
- [Strumenti · Contenuti](/mcp/ferramentas-conteudo#sondaggi)