> For the complete documentation index, see [llms.txt](https://docs.voa.health/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voa.health/integracao/plugin/mensagens.md).

# Comunicação com a página

### Recebimento de Mensagens

A comunicação do Plugin com a página e feita por meio de mensagens utilizando o padrão *publish-subscribe*. Execute a função abaixo para inscrever um *callback* e receber as mensagens do Plugin.

```javascript
const messageHandler = (message) => {
    // Adicione aqui seu tratamento para a mensagem
}

VoaPlugin.instance.addMessageListener(messageHandler);
```

Observe que a cada vez que o método *addMessageListener* é executado, uma nova função de *listener* é adicionado, portanto, é possível ter múltiplos *listeners* simultaneamente. Caso queira remover um *callback* adicionado, basta executar *removeMessageListener*;

```javascript
VoaPlugin.instance.removeMessageListener(messageHandler);
```

As mensagens enviadas pelo Plugin via callback tem o seguinte formato:

```javascript
{ 
    eventName: string, // String com o nome do evento
    eventData: {} // Caso o evento tenha algum dado associado, será enviado nesse campo em formato de objeto. Caso contrário, será undefined
}
```

#### Tipos de mensagens

* Erro de autenticação

Evento disparado quando a autenticação falha durante o `init()`, por exemplo, ao fornecer um token inválido. Caso queira exibir algum tratamento personalizado para esse cenário, trate esse evento antes de chamar o `mount()` do plugin. Caso contrário, será exibido uma tela de erro indicando falha de autenticação e instruindo o usuário a verificar seu token e a procurar nosso suporte.

{% hint style="info" %}
Para receber este evento, registre o *listener* **antes** de chamar `init()`.
{% endhint %}

```javascript
VoaPlugin.instance.addMessageListener((message) => {
    if (message.eventName === "voa.plugin.error.auth") {
        // Exiba uma mensagem adequada ao usuário
    }
});

await VoaPlugin.instance.init({ token });
```

```javascript
{
    eventName: "voa.plugin.error.auth",
    eventData: {
        message: "Authentication failed! Please, check your token."
    }
}
```

* Plugin aberto

Evento disparado assim que o Plugin é exibido para o usuário.

```javascript
{
    eventName: "voa.plugin.opened",
}
```

* Plugin fechado

Evento disparado assim que o Plugin é fechado.

```javascript
{
    eventName: "voa.plugin.closed",
}
```

* Plugin pronto

Ao abrir, o plugin exibe um loading e carrega alguns dados do servidor. Esse evento é disparado quando está tudo pronto para interação do usuário

```javascript
{
    eventName: "voa.plugin.ready",
}
```

* Consulta criada

Ao abrir o plugin, caso uma consulta não exista com os identificadores fornecidos, ela será criada na Voa e esse evento será disparado.

```javascript
{
    eventName: "voa.plugin.ehr.created",
    eventData: {
        id: "", // uuid da consulta na Voa,
        type: "" // TELEMEDICINE ou IN_PERSON
    }
}
```

* Gravação iniciada

```javascript
{
    eventName: "voa.plugin.recorder.started",
}
```

* Gravação pausada

```javascript
{
    eventName: "voa.plugin.recorder.paused",
}
```

* Transcrição disponível

```javascript
{
    eventName: "voa.plugin.ehr.transcriptions",
    eventData: {
        transcriptions: [
            {
                start_time: "00m 00s", 
                text: "Hello"
            },
            {
                start_time: "00m 02s", 
                text: "World!"
            },
        ]
    }
}
```

* Documento gerado

```javascript
{
    eventName: "voa.plugin.ehr.document.created",
    eventData: {
        id: "", // uuid do documento na Voa,
        created_at: "" // timestamp de criação do documento
    }
}
```

* Documento copiado

```javascript
{
    eventName: "voa.plugin.ehr.document.copied",
}
```

* Preencher prontuário

Este evento é disparado se a opção `enableFillEhr` estiver habilitada e o usuário clicar em *"Preencher prontuário".*

```javascript
{
    eventName: "voa.plugin.ehr.fill",
    eventData: {
        document: "" // representação markdown do documento
    }
}
```

Quando o usuário aciona "Preencher prontuário" e foi informado `structuredOutputSchema` na inicialização; é disparado `voa.plugin.ehr.structured_output` (output estruturado) após o plugin obter com sucesso os dados estruturados da API. O payload contém `eventData.output` (dados no formato do schema) e `eventData.from_cache` (indica se o resultado veio de cache). Esta mensagem pode chegar depois de `voa.plugin.ehr.fill`; integradores que usam output estruturado devem inscrever-se em ambas. Veja [Output estruturado](https://docs.voa.health/integracao/plugin/output-estruturado.md) para o schema.

```javascript
{
    eventName: "voa.plugin.ehr.structured_output",
    eventData: {
        output: {},   // dados clínicos no formato do structuredOutputSchema
        from_cache: false
    }
}
```

* Plugin minimizado

Evento disparado quando usuário clica em minimizar o Plugin para reduzir o tamanho da janela.

```javascript
{
    eventName: "voa.plugin.minimized",
}
```

* Plugin maximizado

Evento disparado quando usuário clica em maximizar o Plugin para expandir a janela.

```javascript
{
    eventName: "voa.plugin.maximized",
}
```

* Voltar ao início

Evento disparado quando o usuário clica em "Início" no cabeçalho do Plugin.

```javascript
{
    eventName: "voa.plugin.go_home",
}
```

* Sair da conta

Evento disparado quando o usuário sai da conta pelo Plugin.

```javascript
{
    eventName: "voa.plugin.logout",
}
```

* Upload de arquivos

Os eventos `voa.plugin.file.upload.started`, `voa.plugin.file.upload.progress`, `voa.plugin.file.upload.success` e `voa.plugin.file.upload.error` estão em [Upload de Arquivos](https://docs.voa.health/integracao/plugin/upload-de-arquivos.md#eventos-de-status-de-upload).

## Funções de controle

É possível controlar o plugin programaticamente sem a necessidade de interações do usuário com a interface.

#### Adicionar media stream de áudio

Permite injetar streams de áudio diretamente no plugin para captura durante as gravações de telemedicina.

Quando usar

* **Experiência simplificada**: Se já possui acesso à `MediaStream` da consulta de telemedicina do seu sistema e deseja eliminar etapas manuais de compartilhamento do áudio da tela por parte do usuário.

Também é possível ocultar os botões de compartilhamento de áudio da tela do plugin pelo parâmetro de configuração [allowScreenSharing](https://docs.voa.health/integracao/plugin/fluxo-de-uso.md#parametros-de-configuracao).

```javascript
const mediaStream = await navigator.mediaDevices.getDisplayMedia({
  audio: true,
  systemAudio: "include",
  monitorTypeSurfaces: "include",
  surfaceSwitching: "include",
  selfBrowserSurface: "include",
});

await VoaPlugin.instance.setScreenMediaStream(mediaStream);
```

O método *setScreenMediaStream* também aceita *<mark style="color:blue;">null</mark>* como parâmetro, representando a remoção da stream utilizada, caso exista.

Por se tratar de uma MediaStream externa e que pode estar sendo utilizada em outras features da página, o Plugin **não executa nenhuma ação que interfira no ciclo de vida**, como suspensão ou pause das tracks de áudio ou vídeo. Portanto, é necessário cuidar disso manualmente.

#### Adicionar texto ao contexto do paciente programaticamente

Toda consulta tem um campo de texto "contexto do paciente" que o médico pode preencher com informações adicionais que não foram verbalizadas na transcrição. Caso queira adicionar programaticamente algo nesse campo, chame o método abaixo. Leve em consideração que o conteúdo markdown será adicionado sempre ao final do campo e não sobrescreve nada que já foi digitado.

```javascript
const context = `
*Sexo*: Masculino
*Idade*: 35 anos
`;

await VoaPlugin.instance.appendContext(context);
```

#### Adicionar dados pregressos do paciente programaticamente

Caso queira enriquecer o contexto do paciente com dados de consultas anteriores ou dados históricos, é possível inserir um componente customizado de "História pregressa" no campo "Contexto do Paciente" programaticamente. O conteúdo desse campo será considerado como anterior ao atendimento.

```javascript
const backgroundHistory = `
## Última consulta: 20/12/2022
Refere melhora parcial do humor e do sono após 6 semanas de uso de sertralina 50mg/dia.
Ainda relata episódios de desânimo pela manhã e dificuldade de concentração no trabalho.
`;

await VoaPlugin.instance.addBackgroundHistory(backgroundHistory);

```

Caso uma chamada do método seja realizada em uma consulta que já tem dados pregressos, nada acontecerá. Caso opte por sobrescrever o conteúdo existente, adicione o seguinte parâmetro:

```javascript
await VoaPlugin.instance.addBackgroundHistory(backgroundHistory, true); // replaceIfExists = true
```
