> 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
        template: {
            id: "",   // ID do template utilizado
            name: "", // nome do template
            slug: "", // slug do template
        }
    }
}
```

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://file+.vscode-resource.vscode-cdn.net/Users/gian/Documents/voa/voa-integrations/docs/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.ehr.document.minimized",
}
```

* Plugin maximizado

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

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

## 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](/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.

<pre class="language-javascript"><code class="lang-javascript">const backgroundHistory = `
## Última<a data-footnote-ref href="#user-content-fn-1"> </a>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.
`;

// DEPRECATED: await VoaPlugin.instance.addEhrContext(backgroundHistory); 
await VoaPlugin.instance.addBackgroundHistory(backgroundHistory);

</code></pre>

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

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

{% hint style="warning" %}
Anteriormente, essa mesma funcionalidade tinha a assinatura de função `addEhrContext` . Esse método foi descontinuado e será removido em versões futuras. É recomendado substituí-lo pelo `setBackgroundHistory` .
{% endhint %}

[^1]:


---

# 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.voa.health/integracao/plugin/mensagens.md?ask=<question>&goal=<endgoal>
```

`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.