# Boas-vindas da comunidade

> Os ecrãs que a pessoa nova vê no primeiro acesso (texto, vídeo, regras para aceitar e campos do perfil), o modo obrigatório ou opcional, quem passa por eles, e os Primeiros passos, com até 6 missões, pontos, badges e parabéns no fim.

As **boas-vindas** são os ecrãs que a pessoa nova vê no primeiro acesso, antes da comunidade: um texto de apresentação, o vídeo de boas-vindas, as regras para ler e aceitar, os campos do perfil que a comunidade quer conhecer. Depois delas vêm os **Primeiros passos**, um cartão com até 6 missões (completar o perfil, fazer a primeira publicação, ir ao primeiro evento) que se cumprem sozinhas com a utilização e podem dar pontos e badges.

**Onde fica:** em **Definições › Boas-vindas**, para o proprietário e o administrador.

## Para que serve

| Comunidade | Como usa |
|---|---|
| Comunidade com código de conduta | O primeiro ecrã traz as regras com **Li e aceito**; ninguém entra sem aceitar, e a aceitação fica registada com a data e o texto |
| Escola online | Um vídeo de boas-vindas que tem de ser visto até ao fim, e uma missão "Conclua a aula inaugural" |
| Comunidade profissional | Um ecrã pede cargo, empresa e interesses (campos personalizados); as missões levam à primeira apresentação no Feed e ao primeiro evento |
| Comunidade aberta | Boas-vindas opcionais: quem tem pressa entra diretamente, e o cartão dos Primeiros passos fica no Feed |

## Quem pode

| Papel | O que faz |
|---|---|
| Proprietário e administrador | Configuram os ecrãs, o modo e os Primeiros passos, e veem quantos concluíram, ignoraram ou estão pendentes |
| Moderador e financeiro | Filtram a lista de membros pelo estado das boas-vindas; não mudam a configuração |
| Membro | Passa pelas boas-vindas e vê o próprio cartão dos Primeiros passos |

A equipa (proprietário, administrador, moderador e financeiro) **nunca** passa pelas boas-vindas nem vê o cartão dos Primeiros passos.

## Como funciona

### Os ecrãs

De **1 a 5 ecrãs**, pela ordem em que a pessoa os vai ver. Cada ecrã tem:

- **Título** (até 120 caracteres) e **texto**, com formatação.
- **Vídeo**, opcional: **Sem vídeo**, **Enviar vídeo** (até 2 GB) ou **Link do YouTube ou Vimeo**. Só o vídeo carregado pode ter **Continuar só depois de ver até ao fim**; com ligação externa, não é possível exigir.
- **Regras**, opcional: em **Pedir o aceite das regras**, o texto das regras, uma por linha. A pessoa só continua se marcar **Li e aceito as regras**. A aceitação fica guardada com a data e o texto aceite naquele momento, mesmo que as regras mudem depois.
- **Campos do perfil**, opcional: até 20 [campos customizados](/membros/campos-customizados) por ecrã, com as mesmas validações do perfil. Um campo obrigatório tem de ser preenchido para avançar.

A pessoa vê os ecrãs por ordem (*Passo 1 de 3*), com **Continuar** e, no último, **Entrar na comunidade**; se sair a meio, volta onde parou. **Ver como membro** mostra os ecrãs tal como um membro novo os vê, sem registar nada.

### O modo

| Modo | O que acontece |
|---|---|
| **Obrigatória** (o padrão) | A comunidade fica bloqueada até a pessoa concluir o último ecrã |
| **Pode saltar** | A pessoa vê **Saltar as boas-vindas**; quem salta entra e não volta a ser chamado |

As boas-vindas aparecem **antes** de *Complete seu registo* (ver [Registo e entrada](/membros/cadastro-e-entrada#o-registo)): se ainda faltar um campo obrigatório depois delas, a janela de registo vem a seguir.

### Quem passa

Ao ligar as boas-vindas, escolhe se valem também para quem já é membro:

- **Desmarcado** (o padrão): passam só os membros que entrarem **a partir de agora**.
- **Aplicar também a quem já é membro**: todos os membros passam no próximo acesso.

Desligar liberta de imediato quem estava pendente. **Voltar a ligar não abrange quem entrou enquanto as boas-vindas estavam desligadas**: a contagem recomeça no momento em que volta a ligar, a menos que **Aplicar também a quem já é membro** esteja marcado. Quem já concluiu ou ignorou nunca volta a ser chamado.

### Primeiros passos

No mesmo ecrã, abaixo dos ecrãs das boas-vindas, os **Primeiros passos**: de 1 a **6 missões**, cada uma com o texto que aparece no cartão (**Como aparece no cartão**, até 80 caracteres) e, em **Quando a pessoa**, uma ação que a plataforma já acompanha:

| Quando a pessoa | Cumpre-se quando ela… |
|---|---|
| **Completa o perfil** | tem fotografia e todos os campos obrigatórios preenchidos |
| **Publica pela primeira vez num espaço** | publica no espaço escolhido |
| **Responde um formulário** | responde ao [formulário](/espacos/formularios) escolhido |
| **Se inscreve num evento** | se inscreve num evento (**Qualquer evento**, ou o escolhido) |
| **Conclui um curso** | conclui o curso escolhido |

- Cada missão pode dar **pontos** (de 0 a 10.000, com a [gamificação](/membros/gamificacao) ligada) e um **badge** (ver [Badges](/membros/engajamento#badges)). Concluir todas pode dar um **badge final** (**Badge ao concluir todas**).
- A missão é marcada **em cerca de 1 minuto, no máximo**, depois da ação, sem a pessoa fazer nada. A do perfil também é verificada quando o cartão abre.
- **O que foi feito antes de a missão existir não conta.** Trocar a ação ou o item de uma missão também recomeça a contagem dela; mudar só o título, os pontos ou o badge mantém quem já a cumpriu.
- Valem para os membros que entrarem depois de ligar os Primeiros passos, ou para todos com **Mostrar a quem já é membro**.

**O cartão.** A pessoa vê o cartão **Primeiros passos**, com o progresso (*2 de 4*) e os pontos de cada missão, no topo da coluna do Feed (mesmo com os widgets desligados) e na sua própria página de membro, depois das boas-vindas. Ao concluir todas, vê os **parabéns uma única vez**, recebe o badge final e o cartão desaparece. **Dispensar** esconde o cartão para sempre, e a partir daí nenhuma missão conta.

### Acompanhar

A configuração mostra quantos membros **concluíram**, **ignoraram** e estão **pendentes** nas boas-vindas e, nos Primeiros passos, quantos **começaram** (cumpriram pelo menos uma missão), **concluíram** e **dispensaram**, com quantos cumpriram cada missão.

Na [lista de membros](/membros/gerenciar-membros), a equipa usa o filtro **Boas-vindas** (**Pendente**, **Concluída** ou **Saltada**). A página de cada membro mostra à equipa o bloco **Boas-vindas e primeiros passos**, com o estado das boas-vindas e o progresso nas missões.

### Automatizar com workflows

Dois gatilhos de [workflow](/notificacoes/workflows) no bloco **Membros**:

- **Concluiu as boas-vindas**: a pessoa concluiu o último ecrã. Ignorar não dispara.
- **Concluiu os primeiros passos**: a pessoa cumpriu todas as missões, uma vez por pessoa.

Os dois chegam também aos [webhooks](/api/eventos-de-webhook).

## Passo a passo

### Boas-vindas com regras e vídeo

*Papel: proprietário ou administrador.*

1. Abra **Definições › Boas-vindas**.
2. Na **Tela 1**, dê o título *Bem-vinda à comunidade*, um texto curto e, em **Vídeo**, **Enviar vídeo**, com **Continuar só depois de ver até ao fim**.
3. **Adicionar tela**: na **Tela 2**, marque **Pedir o aceite das regras**, escreva as regras e escolha os campos *Cargo* e *Empresa* em **Campos do perfil**.
4. Em **Para o membro**, deixe **Obrigatória**. Ligue **Boas-vindas ativas** e decida se marca **Aplicar também a quem já é membro**.
5. Confira em **Ver como membro** e guarde.

### Primeiros passos com badge final

1. No mesmo ecrã, ligue os **Primeiros passos** e use **Adicionar missão**: *Complete o seu perfil* (**Completa o perfil**, 50 pontos), *Apresente-se no Feed* (**Publica pela primeira vez num espaço**, espaço *Apresentações*, 50 pontos) e *Inscreva-se no próximo encontro* (**Se inscreve num evento**, **Qualquer evento**).
2. Em **Badge ao concluir todas**, escolha *Pioneiro*, decida sobre **Mostrar a quem já é membro** e guarde.

## Exemplo

A Maria entra na comunidade. Antes de ver qualquer espaço, vê o vídeo até ao fim, aceita as regras e preenche *Cargo*. No Feed, encontra o cartão *Primeiros passos · 0 de 3*. Completa o perfil e publica a apresentação: em cerca de 1 minuto o cartão mostra *2 de 3* e ela tem 100 pontos. Na semana seguinte, inscreve-se num encontro, vê os parabéns, ganha o badge *Pioneiro*, e o workflow com **Concluiu os primeiros passos** coloca-a no grupo *Membros ativos*.

## Erros comuns e como resolver

| Situação | O que fazer |
|---|---|
| Liguei as boas-vindas e quem já era membro não passou por elas | É o padrão. Marque **Aplicar também a quem já é membro** |
| Não consigo exigir que o vídeo seja visto até ao fim | Só o vídeo carregado o permite; com ligação do YouTube ou do Vimeo, não |
| Voltei a ligar e quem entrou com elas desligadas não passou | Voltar a ligar só vale para quem entra a partir daí; marque **Aplicar também a quem já é membro** |
| A missão não foi marcada | Espere cerca de 1 minuto. Confirme se a ação foi no espaço, formulário ou curso escolhido e se foi depois de a missão existir |
| A missão do perfil não é marcada | Falta a fotografia ou algum campo obrigatório do perfil |
| A missão não deu pontos | A [gamificação](/membros/gamificacao) tem de estar ligada |
| Não consigo ligar sem nenhum ecrã (ou missão) | É preciso pelo menos um ecrã para ligar as boas-vindas, e uma missão para ligar os Primeiros passos |

## Perguntas frequentes

**A equipa passa pelas boas-vindas?**
Não. Proprietário, administrador, moderador e financeiro entram diretamente e não veem o cartão dos Primeiros passos.

**A pessoa pode voltar a ver as boas-vindas?**
Não: depois de concluir ou ignorar, não volta a ser chamada, mesmo que mude os ecrãs.

**Tenho de marcar as missões à mão?**
Não. Cada missão cumpre-se com a utilização, em cerca de 1 minuto.

**O membro pode ignorar o cartão?**
Pode dispensá-lo. Desaparece para sempre, e as missões deixam de contar para essa pessoa.

## Na API

`GET` e `PUT /api/welcome/settings` (proprietário e administrador; os outros papéis recebem 403): os ecrãs (`screens`, de 1 a 5, com `title`, `body`, `video` com `mediaId` e `requireFinish` ou `url`, `rules.text` e `fieldIds`), `mode` (`REQUIRED`, o padrão, ou `SKIPPABLE`), `enabled` e `applyToExisting`, com `stats` (`completed`, `skipped`, `pending`). Os Primeiros passos vão na mesma rota: `missionsEnabled`, `missionsShowExisting`, `finalBadgeId` e `missions` (de 1 a 6, com `kind` `profile_completed`, `first_post` com `spaceId`, `form_submitted` com `formId`, `event_registered` com `eventId` opcional ou `course_completed` com `courseId`, `title`, `points` de 0 a 10.000 e `badgeId` opcional), com `missionStats`. Um erro de validação volta com 422 no campo (`screens[0].title`, `missions[1].spaceId`).

Para a própria pessoa (qualquer papel): `GET /api/welcome` (o estado, `off`, `exempt`, `pending`, `completed` ou `skipped`, o ecrã atual e os ecrãs), `POST /api/welcome/progress` (conclui o ecrã atual: `step`, `rulesAccepted`, `videoFinished` e `fields`; um ecrã fora de ordem volta 409) e `POST /api/welcome/skip` (só no modo opcional; caso contrário, 409). O cartão: `GET /api/welcome/missions` (`status` `off`, `exempt`, `active`, `completed` ou `dismissed`, `visible`, `celebrate`, `done` de `total` e as missões), `POST /api/welcome/missions/dismiss` e `POST /api/welcome/missions/celebrated` (os parabéns foram mostrados).

`GET /auth/me` traz `welcomePending`. `GET /api/members` filtra com `welcome=pending|completed|skipped`, e `GET /api/members/{id}` traz `welcome`, com `missions`. Os eventos `member.welcome_completed` (`member`, `completedAt`) e `member.onboarding_completed` (`member`, `completedAt` e `missions`, o número de missões) chegam aos workflows e aos webhooks. Ver a [Referência da API](/api/referencia).

## Pelo assistente (MCP)

Peça para ver ou mudar as boas-vindas e as missões (*"ative as boas-vindas obrigatórias com uma tela de regras"*): [`get_welcome_settings`](/mcp/ferramentas-membros#get-welcome-settings) e [`update_welcome_settings`](/mcp/ferramentas-membros#update-welcome-settings), que sempre pede confirmação. Quem está pendente: [`list_members`](/mcp/ferramentas-membros#list-members) com `welcome: pending`; o progresso de alguém: [`get_member`](/mcp/ferramentas-membros#get-member).

## Relacionados

- [Registo e entrada](/membros/cadastro-e-entrada)
- [Campos customizados](/membros/campos-customizados)
- [Gamificação](/membros/gamificacao)
- [Envolvimento e badges](/membros/engajamento#badges)
- [Workflows](/notificacoes/workflows)