> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/pt/automacao/runbooks/runbook-references/org/devices/notify-users-about-stale-devices_scheduled.md).
# Notificar utilizadores sobre dispositivos desatualizados agendado
Notificar os utilizadores principais sobre os respetivos dispositivos desatualizados por email
{% hint style="info" %}
Este é um Runbook agendado. Foi concebido para ser executado segundo um agendamento recorrente, em vez de ser acionado para um único objeto. Consulte [Agendamento](/pt/automacao/runbooks/scheduling.md) para detalhes sobre como configurar os agendamentos do Runbook.
{% endhint %}
### Descrição
Identifica dispositivos que não estiveram ativos por um número especificado de dias e envia notificações personalizadas por email aos usuários principais desses dispositivos. O email contém informações do dispositivo e etapas de ação para o usuário. Opcionalmente, filtre usuários incluindo ou excluindo grupos específicos. Três destinos de roteamento opcionais estão disponíveis: um destinatário de substituição global que redireciona TODAS as notificações (para testes e pilotos), um destinatário dedicado para usuários cujo UPN corresponda a um padrão de nome (por exemplo, contas do Device Enrollment Manager) e um destinatário dedicado que recebe um único email combinado para dispositivos desatualizados sem usuário principal.
### Configuração relativa ao envio de e-mails
O envio de um relatório por e-mail é opcional e só acontece quando um destinatário (`EmailTo`) é fornecido. O endereço do remetente é obtido da `RJReport.EmailSender` configuração do Tenant.
Este Runbook envia e-mails usando a API do Microsoft Graph. Para enviar e-mails através da API do Microsoft Graph, é necessário configurar um endereço de e-mail existente na personalização do runbook.
Consulte a [documentação de Configurações de Relatório do RealmJoin](https://docs.realmjoin.com/automation/runbooks/runbook-report-settings) para detalhes sobre todas as definições disponíveis.
#### Branding do e-mail
O e-mail do relatório respeita a configuração opcional `RJReport.Branding.*` do Tenant:
* **Imagem de cabeçalho e rodapé** – URLs públicas HTTPS, PNG/JPEG/GIF, máx. 200 KB cada
* **Ligação do rodapé** – destino da imagem de rodapé
* **Cor de acento e texto** – valores hexadecimais de 6 dígitos, por exemplo `#0052cc`
Quando estas definições não estão configuradas, são usados os gráficos e cores padrão do RealmJoin. Uma imagem que não possa ser descarregada ou validada, ou um valor de cor inválido, nunca impede o e-mail do relatório – em vez disso, é usado o padrão correspondente.
Instruções de configuração e requisitos de imagem: [Branding do e-mail](https://docs.realmjoin.com/automation/runbooks/runbook-report-settings#email-branding-optional).
### Seleção do idioma do modelo de email
Este runbook suporta três opções de modelo de email:
1. **EN (Inglês - Padrão)**: Usa o modelo inglês incorporado
2. **DE (Alemão)**: Usa o modelo alemão incorporado
3. **Personalizado**: Usa um modelo personalizado a partir das Customizações do Runbook
#### Utilizar modelos de email personalizados
Para utilizar um modelo de email personalizado (por exemplo, em neerlandês, espanhol ou qualquer outro idioma), precisa de configurar o texto do modelo nas Customizações do Runbook. Se faltar qualquer parâmetro de modelo personalizado, o runbook voltará automaticamente ao modelo inglês.
**Exemplo: Modelo Personalizado**
```json
{
"Runbooks": {
"rjgit-org_devices_notify-users-about-stale-devices_scheduled": {
"Parameters": {
"CustomMailTemplateSubject": {
"Default": "Este é um assunto personalizado - Ação necessária: Dispositivos inativos"
},
"CustomMailTemplateBeforeDeviceDetails": {
"Default": "**Isto está acima dos detalhes do dispositivo.** \n\nCaro usuário ..."
},
"CustomMailTemplateAfterDeviceDetails": {
"Default": "**Isto está abaixo dos detalhes do dispositivo.** \n\n## O que você deve fazer..."
}
}
}
}
}
```
**Notas importantes:**
* Use `\n` para quebras de linha na configuração JSON
* A formatação Markdown (##, ###, \*\*, -) é suportada no texto do modelo
* Todos os três parâmetros do modelo personalizado (Subject, BeforeDeviceDetails, AfterDeviceDetails) devem ser configurados
* Se algum parâmetro estiver em falta, o runbook recorre automaticamente ao modelo em inglês (EN)
* Ao utilizar o modelo personalizado, selecione "Custom - Use Template from Runbook Customizations" no menu suspenso Mail Template
### Roteamento de email
O runbook conhece três destinos de roteamento independentes, verificados nesta ordem de precedência:
1. **Substituição global (teste):** Um preenchido `OverrideEmailRecipient` redireciona **TODAS** emails - notificações de usuários, notificações roteadas por padrão e o email combinado para dispositivos sem usuário principal - para esse endereço. Nenhum usuário final recebe um email. Use isto para testes, piloto ou para redirecionar tudo para uma caixa de correio compartilhada ou sistema de chamados. Um aviso é registrado em cada execução enquanto a substituição estiver ativa.
2. **Usuários correspondentes ao padrão:** Quando `OverrideUserNamePattern` está definido, as notificações dos usuários cujo UPN corresponda ao padrão são enviadas para `UserNamePatternEmailRecipient` em vez do usuário. Todos os outros usuários recebem sua notificação diretamente. Uso típico: contas do Device Enrollment Manager ou de quiosque (`DEM-*`, `KIOSK-*`) cujas caixas de correio ninguém lê.
3. **Dispositivos sem usuário principal:** Quando `SendNoPrimaryUserDevicesToOverride` está habilitado, os dispositivos desatualizados sem usuário principal são reunidos em **um** email combinado para `NoPrimaryUserEmailRecipient`. Caso contrário, esses dispositivos são ignorados. Essa configuração nunca altera como as notificações do usuário são roteadas.
Configurações incompletas interrompem o runbook com um erro em vez de enviar emails silenciosamente aos usuários finais:
* `SendNoPrimaryUserDevicesToOverride` habilitado sem `NoPrimaryUserEmailRecipient` (e sem uma substituição global) - erro.
* `OverrideUserNamePattern` definido sem `UserNamePatternEmailRecipient` (e sem uma substituição global) - erro.
* Um destinatário definido sem o seu recurso (`NoPrimaryUserEmailRecipient` sem a alternância, `UserNamePatternEmailRecipient` sem um padrão) - aviso, o destinatário é ignorado.
Enquanto a substituição global estiver ativa, os destinatários dedicados não precisam ser definidos - tudo vai para o destinatário de substituição de qualquer forma.
#### Padrão de Nome de Usuário
`OverrideUserNamePattern` aceita um ou mais padrões curinga (separados por vírgula) correspondentes ao UPN do usuário principal, por exemplo `DEM-*` para contas do Device Enrollment Manager ou `DEM-*,KIOSK-*` para vários padrões. A correspondência não diferencia maiúsculas de minúsculas e usa a sintaxe curinga do PowerShell (`*`, `?`). Quando o roteamento por padrão está ativo, o runbook registra um aviso indicando qual padrão é redirecionado para qual destinatário.
**Notas importantes:**
* Todos os parâmetros de destinatário aceitam vários endereços separados por vírgula
* Dispositivos sem usuário principal ignoram a filtragem de escopo do usuário (eles não têm um usuário para comparar com grupos)
* Os usuários correspondentes ao padrão ainda estão sujeitos primeiro à filtragem de escopo do usuário; usuários excluídos pelo escopo não produzem nenhuma notificação
* O email combinado para dispositivos sem usuário principal usa uma redação administrativa (sem etapas de ação para o usuário final), independentemente de modelos personalizados
* As notificações redirecionadas indicam o usuário afetado no assunto e no corpo do email
### Localização
Organização → Dispositivos → Notificar usuários sobre dispositivos desatualizados (agendado)
**Nome completo do Runbook**
rjgit-org\_devices\_notify-users-about-stale-devices\_scheduled
### Detalhes
| Propriedade | Valor |
| ------------------- | --------------------------------------------------------------------------------------- |
| Versão | 1.7.0 |
| Módulos necessários | RealmJoin.RunbookHelper (>= 0.8.9)
Microsoft.Graph.Authentication (>= 2.39.0)
|
| Agendável | sim |
### Notas
Este runbook envia automaticamente notificações personalizadas por email aos usuários que têm dispositivos que não sincronizaram há um número especificado de dias. O email é enviado diretamente para o endereço de email do usuário principal e inclui informações detalhadas sobre cada dispositivo inativo.
Pré-requisitos:
* O parâmetro EmailFrom tem de ser configurado na personalização do runbook (definição RJReport.EmailSender)
* Opcional: as informações de contacto do Service Desk podem ser configuradas (ServiceDesk\_DisplayName, ServiceDesk\_EMail, ServiceDesk\_Phone, ServiceDesk\_PortalUrl)
Casos de uso comuns:
* Lembretes automatizados aos usuários sobre dispositivos inativos para incentivar verificações regulares dos dispositivos
* Gerenciamento proativo do ciclo de vida dos dispositivos, alertando os usuários antes que os dispositivos sejam aposentados
* Segurança e conformidade, garantindo que os usuários estejam cientes de todos os dispositivos registrados para eles
* Uso do parâmetro MaxDays para notificações em etapas (por exemplo, primeiro lembrete em 30 dias, aviso final em 60 dias)
* Filtragem do escopo do usuário para direcionar departamentos específicos ou excluir contas de serviço
* Tratamento centralizado de dispositivos sem usuário principal ou de propriedade de contas do Device Enrollment Manager (por exemplo, DEM-\*) por meio de destinatários dedicados
Opções de piloto e teste:
* Use o parâmetro OverrideEmailRecipient para enviar todas as notificações para uma caixa de correio de teste em vez dos usuários finais
* Perfeito para validar o conteúdo do email e testar filtros antes de entrar em produção
* Enviar notificações para sistemas de chamados ou caixas de correio compartilhadas para tratamento centralizado
### Permissões
#### Permissões da aplicação
* **Tipo**: Microsoft Graph
* DeviceManagementManagedDevices.Read.All
* *Lê dispositivos gerenciados pelo Intune filtrados por lastSyncDateTime para encontrar dispositivos desatualizados e seus usuários principais*
* Directory.Read.All
* *Lê o nome do Tenant para o rodapé do email e resolve IDs de usuário para a filtragem de escopo de grupos*
* Group.Read.All
* *Lista os membros dos grupos de inclusão/exclusão para filtrar quais usuários principais recebem notificações*
* Mail.Send
* *Envia os emails de notificação de dispositivos desatualizados para cada usuário principal ou para o destinatário de substituição*
### Parâmetros
#### Dias
Número de dias sem atividade para ser considerado desatualizado (limite mínimo).
| Propriedade | Valor |
| -------------------------- | -------------------------- |
| Obrigatório | falso |
| Valor predefinido | 30 |
| Tipo | Int32 |
| Nome de exibição no portal | Dias Mínimos Sem Atividade |
#### MaxDays
Número máximo opcional de dias sem atividade. Se definido, apenas serão incluídos dispositivos inativos entre Days e MaxDays.
| Propriedade | Valor |
| -------------------------- | ------------------------------------- |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Int32 |
| Nome de exibição no portal | (Opcional) Dias Máximos Sem Atividade |
#### Windows
Incluir dispositivos Windows nos resultados.
| Propriedade | Valor |
| -------------------------- | ---------------------------- |
| Obrigatório | falso |
| Valor predefinido | Verdadeiro |
| Tipo | Booleano |
| Nome de exibição no portal | Incluir dispositivos Windows |
#### macOS
Incluir dispositivos macOS nos resultados.
| Propriedade | Valor |
| -------------------------- | -------------------------- |
| Obrigatório | falso |
| Valor predefinido | Verdadeiro |
| Tipo | Booleano |
| Nome de exibição no portal | Incluir dispositivos macOS |
#### iOS
Incluir dispositivos iOS nos resultados.
| Propriedade | Valor |
| -------------------------- | ------------------------ |
| Obrigatório | falso |
| Valor predefinido | Verdadeiro |
| Tipo | Booleano |
| Nome de exibição no portal | Incluir Dispositivos iOS |
#### Android
Incluir dispositivos Android nos resultados.
| Propriedade | Valor |
| -------------------------- | ---------------------------- |
| Obrigatório | falso |
| Valor predefinido | Verdadeiro |
| Tipo | Booleano |
| Nome de exibição no portal | Incluir Dispositivos Android |
#### EmailFrom
O endereço de e-mail do remetente. Isto precisa de ser configurado na personalização do runbook.
| Propriedade | Valor |
| ----------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### BrandingHeaderImageUrl
URL HTTPS pública opcional de uma imagem de cabeçalho personalizada (PNG/JPEG/GIF, máx. 200 KB) para o e-mail do relatório. Obtida da configuração do Tenant RJReport.Branding.HeaderImageUrl. Quando vazio, é usada a imagem de cabeçalho padrão do RealmJoin.
| Propriedade | Valor |
| ----------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### BrandingFooterImageUrl
URL HTTPS pública opcional de uma imagem de rodapé personalizada (PNG/JPEG/GIF, máx. 200 KB) para o e-mail do relatório. Obtida da configuração do Tenant RJReport.Branding.FooterImageUrl. Quando vazio, é usada a imagem de rodapé padrão do RealmJoin.
| Propriedade | Valor |
| ----------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### BrandingFooterLink
URL opcional para a qual a imagem de rodapé aponta. Obtida da configuração do Tenant RJReport.Branding.FooterLink. Quando vazio, é usada a ligação padrão ().
| Propriedade | Valor |
| ----------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### BrandingAccentColor
Substituição opcional da cor de acento (hex de 6 dígitos, por exemplo '#0052cc') para o modelo de e-mail do relatório. Obtida da configuração do Tenant RJReport.Branding.AccentColor. Quando vazio ou inválido, é usada a cor de acento padrão do RealmJoin.
| Propriedade | Valor |
| ----------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### BrandingTextColor
Substituição opcional da cor do texto (hex de 6 dígitos) para o modelo de e-mail do relatório. Obtida da configuração do Tenant RJReport.Branding.TextColor. Quando vazio ou inválido, é usada a cor de texto padrão do RealmJoin.
| Propriedade | Valor |
| ----------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### ServiceDeskDisplayName
Nome a apresentar do Service Desk para informações de contacto do utilizador (opcional).
| Propriedade | Valor |
| ----------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### ServiceDeskEmail
Endereço de email do Service Desk para informações de contacto do utilizador (opcional).
| Propriedade | Valor |
| ----------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### ServiceDeskPhone
Número de telefone do Service Desk para informações de contacto do utilizador (opcional).
| Propriedade | Valor |
| ----------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### ServiceDeskPortalUrl
URL do portal do Service Desk para informações de contacto do utilizador, apresentado como uma ligação clicável (opcional).
| Propriedade | Valor |
| ----------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### ServiceDeskTicketUrl
Ligação direta para um ticket do Service Desk, apresentada como uma ligação clicável (opcional). Vazia por predefinição, por isso não é adicionado qualquer ligação para ticket.
| Propriedade | Valor |
| ----------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### UseUserScope
Ative a filtragem por âmbito do utilizador para incluir ou excluir utilizadores com base na pertença a grupos.
| Propriedade | Valor |
| -------------------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | Falso |
| Tipo | Booleano |
| Nome de exibição no portal | Utilizar filtragem por âmbito do utilizador |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### IncludeUserGroup
Enviar emails apenas para usuários que são membros deste grupo. Requer que UseUserScope esteja habilitado.
| Propriedade | Valor |
| -------------------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Nome de exibição no portal | Utilizadores a incluir (Grupo) |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### ExcludeUserGroup
Não enviar emails para usuários que são membros deste grupo. Requer que UseUserScope esteja habilitado.
| Propriedade | Valor |
| -------------------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Nome de exibição no portal | Utilizadores a excluir (Grupo) |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### OverrideEmailRecipient
Opcional: substituição global - quando definido, TODAS as notificações (notificações de usuário, notificações roteadas por padrão e o email combinado para dispositivos sem usuário principal) são enviadas para este endereço em vez dos destinatários normais. Pode ser separado por vírgula para vários destinatários. Perfeito para testes e piloto, ou para redirecionar tudo para um sistema de chamados. Se deixado em branco, aplica-se o roteamento normal.
| Propriedade | Valor |
| -------------------------- | ------------------------------------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Nome de exibição no portal | Redirecionar \* TODAS \* as mensagens de email para os destinatários de substituição |
#### OverrideUserNamePattern
Padrão(ões) curinga opcionais correspondentes ao UPN do usuário principal (separados por vírgula, por exemplo 'DEM-*,KIOSK-*', sem diferenciar maiúsculas de minúsculas). As notificações dos usuários correspondentes são redirecionadas para UserNamePatternEmailRecipient; todos os outros usuários recebem email diretamente. Não é avaliado separadamente enquanto a substituição global (OverrideEmailRecipient) estiver ativa, já que todas as notificações são redirecionadas de qualquer forma.
| Propriedade | Valor |
| -------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Nome de exibição no portal | (Opcional) Padrão de Nome do Usuário Principal - redirecionar usuários correspondentes (por exemplo, 'DEM-\*') |
#### UserNamePatternEmailRecipient
Endereço(s) de email que recebem as notificações dos usuários que correspondem a OverrideUserNamePattern. Podem ser separados por vírgula. Obrigatório quando OverrideUserNamePattern estiver definido, a menos que OverrideEmailRecipient esteja definido.
| Propriedade | Valor |
| -------------------------- | ------------------------------------------------------- |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Nome de exibição no portal | Destinatário(s) para Usuários Correspondentes ao Padrão |
#### SendNoPrimaryUserDevicesToOverride
Se habilitado, dispositivos desatualizados sem usuário principal são reunidos em um email combinado para NoPrimaryUserEmailRecipient (ou para OverrideEmailRecipient enquanto a substituição global estiver ativa). Não altera como as notificações dos usuários são roteadas. Dispositivos sem usuário principal ignoram a filtragem de escopo do usuário.
| Propriedade | Valor |
| -------------------------- | -------------------------------------------------------------- |
| Obrigatório | falso |
| Valor predefinido | Falso |
| Tipo | Booleano |
| Nome de exibição no portal | Enviar dispositivos sem usuário principal como email combinado |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### NoPrimaryUserEmailRecipient
Endereço(s) de email que recebem o email combinado para dispositivos desatualizados sem usuário principal. Podem ser separados por vírgula. Obrigatório quando SendNoPrimaryUserDevicesToOverride estiver habilitado, a menos que OverrideEmailRecipient esteja definido.
| Propriedade | Valor |
| -------------------------- | ------------------------------------------------------- |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Nome de exibição no portal | Destinatário(s) para Dispositivos sem Usuário Principal |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### MailTemplateLanguage
Selecione que modelo de email utilizar: EN (Inglês, predefinição), DE (Alemão) ou Personalizado (a partir das Customizações do Runbook).
| Propriedade | Valor |
| -------------------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | EN |
| Tipo | Texto |
| Nome de exibição no portal | Modelo de email |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### CustomMailTemplateSubject
Linha de assunto do email personalizada (usada apenas quando MailTemplateLanguage está definido como 'Custom').
| Propriedade | Valor |
| -------------------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Nome de exibição no portal | Assunto do email personalizado |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### CustomMailTemplateBeforeDeviceDetails
Texto personalizado a apresentar antes da lista de dispositivos (usado apenas quando MailTemplateLanguage está definido como 'Custom'). Suporta formatação Markdown.
| Propriedade | Valor |
| -------------------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Nome de exibição no portal | Texto personalizado antes da lista de dispositivos |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
#### CustomMailTemplateAfterDeviceDetails
Texto personalizado a ser exibido após a lista de dispositivos (usado apenas quando MailTemplateLanguage está definido como 'Custom'). Suporta formatação Markdown.
| Propriedade | Valor |
| -------------------------- | ------------------------------------------------------ |
| Obrigatório | falso |
| Valor predefinido | |
| Tipo | Texto |
| Nome de exibição no portal | Texto personalizado após a lista de dispositivos |
| Oculto no portal | sim (predefinido através da personalização do runbook) |
[Voltar à visão geral da referência do Runbook](/pt/automacao/runbooks/runbook-references.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.realmjoin.com/pt/automacao/runbooks/runbook-references/org/devices/notify-users-about-stale-devices_scheduled.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.