Integração Wide Chat com Minha Agenda Virtual API V3

Este artigo orienta a configuração da integração entre o Wide Chat e o Minha Agenda Virtual utilizando os endpoints validados da API V3. O objetivo é padronizar o fluxo de consulta de datas e horários, criação, confirmação e cancelamento de compromissos.

Orientações de uso

• Crie uma cópia do fluxo antes de qualquer alteração em cliente.
• Substitua somente os parâmetros do novo cliente, mantendo os nomes das variáveis e a ordem dos blocos.
• Não registre o TOKEN em documentos enviados externamente ou capturas públicas.
• Teste consulta de dias, consulta de horários, criação e cancelamento antes da publicação.
• Atualize a revisão deste conteúdo quando houver alteração na API ou no Wide Chat.

1. Identificação e controle

2. Objetivo e escopo validado

O fluxo permite que o cliente consulte datas e horários disponíveis, escolha uma opção, informe seus dados, crie um compromisso e solicite o cancelamento pela chave recebida.

2.1 Localização da API

Documentação oficial: API V3 do Minha Agenda Virtual.
URL base utilizada: https://minhaagendavirtual.com.br

2.2 Ordem geral da jornada

3. Visão do fluxo no Wide Chat

A configuração inicia com os parâmetros fixos e direciona o usuário ao menu principal. O bloco Criar Agendamento reúne as quatro chamadas REST e os scripts de tratamento.

4. Parâmetros e variáveis

Crie os parâmetros antes de configurar os componentes REST e RPA. Os nomes devem ser mantidos de forma consistente em todo o fluxo.

Atenção: o fluxo geral exibe EMAIL_KEY entre os parâmetros, mas o payload validado utiliza {{EMAIL}}. Para evitar falha de substituição, padronize o parâmetro e o corpo da requisição com o mesmo nome.

4.1 Obter TOKEN, CALENDAR_KEY e SERVICE_KEY

Antes de configurar as requisições no Wide Chat, obtenha o token de autenticação e identifique a agenda e o serviço que serão utilizados. Não reutilize chaves do ambiente de demonstração em clientes.

4.1.1 Obter o TOKEN na Minha Agenda Virtual

1. Acesse o painel administrativo da Minha Agenda Virtual com um usuário autorizado.
2. No menu lateral, selecione Integrações.
3. Na página Integrações e Apps, localize API & Webhooks e selecione Gerenciar.
4. Na guia Chave da API, crie um token quando ainda não houver uma chave ativa. Se já existir um token ativo, utilize o ícone de cópia ao lado da chave.
5. No Wide Chat, grave somente o valor da chave na variável TOKEN. O prefixo Bearer será acrescentado no header da requisição.

 Figura 2A Acesso ao menu Integrações

Figura 2B Acesso à integração API e Webhooks

Figura 2C Criação e cópia do token de autenticação

Segurança: trate o TOKEN como credencial. Não o envie em documentos externos, não o exponha em capturas de tela e não utilize a opção Revogar durante uma implantação, salvo quando houver necessidade de invalidar a chave atual.

4.1.2 Obter o CALENDAR_KEY pelo Postman

1. Crie uma requisição GET no Postman.
2. Informe a URL {{API_SERVER}}/api/v3/calendars/?page_size=100.
3. Na guia Authorization, selecione No Auth, pois o token será enviado manualmente no header.
4. Adicione os headers accept: application/json e Authorization: Bearer {{TOKEN}}.
5. Mantenha o corpo da requisição vazio e selecione Send.
6. Confirme o retorno HTTP 200 e, dentro de results, localize a agenda desejada pelo campo calendar_name.
7. Copie o valor de calendar_key e grave-o na variável CALENDAR_KEY do Wide Chat.

GET {{API_SERVER}}/api/v3/calendars/?page_size=100
accept: application/json
Authorization: Bearer {{TOKEN}}

4.1.3 Obter o SERVICE_KEY pelo Postman

1. Depois de preencher CALENDAR_KEY, crie outra requisição GET no Postman.
2. Informe a URL {{API_SERVER}}/api/v3/services/?calendar_key={{CALENDAR_KEY}}&page_size=100.
3. Mantenha Authorization como No Auth e reutilize os headers accept: application/json e Authorization: Bearer {{TOKEN}}.
4. Mantenha o corpo vazio e selecione Send.
5. Confirme o retorno HTTP 200 e, dentro de results, localize o serviço desejado pelo campo service_name.
6. Copie o valor de service_key e grave-o na variável SERVICE_KEY do Wide Chat.

GET {{API_SERVER}}/api/v3/services/?calendar_key={{CALENDAR_KEY}}&page_size=100
accept: application/json
Authorization: Bearer {{TOKEN}}

Contas com subcontas: adicione account_slug={{ACCOUNT_SLUG}} como parâmetro de consulta nos endpoints de agendas e serviços para consultar o contexto correto.

4.2 Configuração comum dos componentes REST

1. Marque Verificar certificado SSL.
2. Marque Fixar IP de origem.
3. Mantenha Esta integração gera o protocolo do atendimento desmarcada.
4. Selecione o método de autenticação Nenhum.
5. Informe os headers manualmente no editor JSON.
6. Mantenha Parâmetros vazio.
7. Nos métodos GET e DELETE, mantenha o corpo sem dados; nas telas validadas o editor permanece com o valor vazio [].

vazio [].
{
  "accept": "application/json",
  "Authorization": "Bearer {{TOKEN}}"
}

5. Endpoint Listar dias disponíveis

Figura 3 REST Listar Dias

Figura 4 RPA e mapeamento das datas

5.1 Montar o menu de datas

1. Adicione o script MENU DATAS DISPONIVEIS depois do RPA.
2. Crie o parâmetro local datas_disponiveis com o valor {{DATAS_DISPONIVEIS}}.
3. Selecione o tipo de função Customizável.
4. Grave o retorno em LISTA_DATAS.
5. Adicione uma Entrada de dados com variável OPCAO, limite de 5 minutos e mensagem {{LISTA_DATAS}}.

Figura 5 Parâmetro do script de datas

Figura 6 Entrada da opção de data

O código completo está no Apêndice A.1.

5.2 Associar a opção a DATA_DESEJADA

1. Na condição OPCAO DATA ESCOLHIDA, crie um caminho para cada opção exibida.
2. Em cada caminho, execute uma cópia do script DATA DESEJADA.
3. Configure data_desejada com {{DATAS_DISPONIVEIS}}.
4. Na opção 1, retorne datasFuturas[0]; na opção 2, datasFuturas[1]; continue a sequência até a última opção.
5. Grave todos os retornos na mesma variável DATA_DESEJADA.

Figura 7 Configuração do script DATA DESEJADA

Figura 8 Retorno do script em DATA_DESEJADA

O código completo está no Apêndice A.2.

6. Endpoint Listar horários disponíveis

Figura 9 REST Listar Horários

Figura 10 RPA e mapeamento dos horários

6.1 Montar o menu de horários

1. Adicione o script Horarios Livres depois do RPA.
2. Crie o parâmetro horarios_disponiveis com o valor {{HORARIOS_DISPONIVEIS}}.
3. Selecione o tipo Customizável.
4. Grave o retorno em LISTA_HORARIOS.
5. Adicione uma Entrada de dados para apresentar LISTA_HORARIOS e reutilize OPCAO para armazenar a escolha.

Figura 10A Configuração da entrada OPCAO para seleção de horário

Figura 11 Parâmetro e início do script de horários

Figura 12 Retorno do menu em LISTA_HORARIOS

O código completo está no Apêndice A.3.

6.2 Associar a opção a DATA_HORA_DESEJADA

1. Depois da entrada do horário, execute HORARIO SELECIONADO CLIENTE.
2. Configure horarios_disponiveis com {{HORARIOS_DISPONIVEIS}}.
3. Configure opcao com {{OPCAO}}.
4. Grave o retorno em DATA_HORA_DESEJADA.
5. Mantenha a normalização que transforma o final Z em .000Z quando necessário.

Figura 13 Parâmetros do horário selecionado

Figura 14 Normalização e retorno da data e hora

7. Endpoint Criar compromisso

Payload validado:

{
  "status": "PENDING",
  "calendar_key": "{{CALENDAR_KEY}}",
  "service_list": [
    {
      "service_key": "{{SERVICE_KEY}}"
    }
  ],
  "owner_user": {
    "email": "{{EMAIL}}"
  },
  "attendees": [
    {
      "name": "{{NAME}}"
    }
  ],
  "start": {
    "dateTime": "{{DATA_HORA_DESEJADA}}"
  },
  "verify_limits": false,
  "send_email": false,
  "include_flows": false,
  "account_slug": "{{ACCOUNT_SLUG}}"
}

Mantenha os valores booleanos exatamente como foram validados. Qualquer alteração em verify_limits, send_email ou include_flows exige novo teste ponta a ponta.

Embora PHONE seja coletada no fluxo, ela não integra o payload atual. O campo enviado para attendees é somente NAME; o e-mail é enviado em owner_user.email.

7.1 Mapear a resposta no RPA

Para sustentar a condição de sucesso e o cancelamento posterior, associe os campos retornados às variáveis do fluxo:

{
  "appointment_key": "{{KEY_AGENDA}}",
  "status": "{{STATUS}}"
}

A condição Agenda Criada deve seguir pelo caminho de sucesso quando STATUS for igual a PENDING.

Figura 15 REST de criação do compromisso

Figura 16 Condição de criação e confirmação

7.2 Formatar data e hora da confirmação

1. Execute Ajusta Data para mensagem com data_hora igual a {{DATA_HORA_DESEJADA}} e retorne DATA_AGENDAMENTO.
2. Execute Ajusta Hora para mensagem com data_hora igual a {{DATA_HORA_DESEJADA}} e retorne HORA_DESEJADA.
3. Na mensagem final, apresente DATA_AGENDAMENTO, HORA_DESEJADA e KEY_AGENDA.
4. Oriente o usuário a guardar KEY_AGENDA, pois ela será solicitada no cancelamento.

Figura 17 Script de formatação da data

Figura 18 Script de formatação da hora

Os códigos completos estão nos Apêndices A.5 e A.6.

8. Endpoint Excluir agendamento

O fluxo de cancelamento começa solicitando a chave do compromisso recebida na criação. A entrada é armazenada em KEY_AGENDA e utilizada diretamente no caminho do endpoint DELETE.

1. Adicione uma Entrada de dados com limite de 10 minutos.
2. Selecione KEY_AGENDA como variável de retorno.
3. Apresente a mensagem: Digite a chave do compromisso recebida no agendamento do horário que deseja cancelar.
4. Direcione a resposta para o RPA Excluir Agenda.

Figura 19 Entrada da chave para cancelamento

8.1 Configurar o componente REST

Figura 20 REST de exclusão do agendamento

Figura 21 RPA de cancelamento

Figura 22 Condição de cancelamento concluído

9. Teste e homologação

9.1 Teste dos componentes isolados

• [ ] Executar Listar Dias e confirmar que DATAS_DISPONIVEIS foi preenchida pelo campo results.
• [ ] Confirmar que LISTA_DATAS apresenta até cinco datas futuras em ordem cronológica.
• [ ] Selecionar cada opção e confirmar que DATA_DESEJADA corresponde à opção exibida.
• [ ] Executar Listar Horários e confirmar HORARIOS_DISPONIVEIS.
• [ ] Confirmar que a opção digitada retorna o start_date correto em DATA_HORA_DESEJADA.
• [ ] Criar um compromisso e confirmar STATUS igual a PENDING e KEY_AGENDA preenchida.
• [ ] Conferir o compromisso no painel do Minha Agenda Virtual.
• [ ] Cancelar usando KEY_AGENDA e confirmar STATUS igual a CANCELED.
• [ ] Conferir o cancelamento e o envio de e-mail previsto por send_email=true.

9.2 Critérios de aceite

9.3 Pontos que não devem ser alterados sem nova homologação

• Nomes das variáveis referenciadas nos scripts e payloads.
• Ausência de SERVICE_KEY nos dois endpoints GET.
• status PENDING no POST.
• verify_limits=false, send_email=false e include_flows=false no POST.
• send_email=true no DELETE.
• Comparações de STATUS com PENDING e CANCELED.
• Normalização de start_date para o formato com .000Z.

10. Segurança e replicação para novos clientes

• Crie TOKEN exclusivo para o ambiente do cliente e armazene-o como segredo.
• Substitua CALENDAR_KEY, SERVICE_KEY, ACCOUNT_SLUG e EMAIL pelos dados do cliente.
• Não reutilize chaves do ambiente de demonstração em produção.
• Não publique capturas contendo token ou dados reais de pacientes, clientes ou usuários.
• Valide a política de envio de e-mail antes de manter send_email=true no cancelamento.
• Registre a evidência do teste e a aprovação do responsável antes da publicação.

11. Controle de versão

Apêndice A – Scripts validados

Os scripts abaixo reproduzem os arquivos de texto enviados com o fluxo. Os nomes dos parâmetros locais devem ser configurados exatamente como indicado.

A.1 Menu Datas Disponíveis

() => {
var dados = datas_disponiveis;
 
// O Wide Chat pode entregar o valor como string JSON
if (typeof dados === "string") {
try {
dados = JSON.parse(dados);
} catch (e) {
return "Não foi possível interpretar as datas disponíveis.";
}
}
 
if (!Array.isArray(dados) || dados.length === 0) {
return "Não há datas disponíveis para agendamento.";
}
 
var datas = [];
 
// Considera somente dias realmente disponíveis
for (var i = 0; i < dados.length; i++) {
 
if (
dados[i] &&
dados[i].day &&
dados[i].is_active !== false &&
dados[i].is_blocked !== true &&
dados[i].is_holiday !== true &&
(
dados[i].available_slots === undefined ||
dados[i].available_slots > 0
)
) {
datas.push(dados[i].day);
}
}
 
if (datas.length === 0) {
return "Não há datas disponíveis para agendamento.";
}
 
// A API retornou as datas do maior para o menor.
// Coloca em ordem cronológica.
datas.sort();
 
// Remove o dia atual.
// Assim mantém o comportamento que você tinha:
// 02/10, 05/10, 06/10...
var hoje = new Date();
var anoHoje = hoje.getFullYear();
var mesHoje = String(hoje.getMonth() + 1).padStart(2, "0");
var diaHoje = String(hoje.getDate()).padStart(2, "0");
 
var dataHoje =
anoHoje + "-" +
mesHoje + "-" +
diaHoje;
 
var datasFuturas = [];
 
for (var j = 0; j < datas.length; j++) {
if (datas[j] > dataHoje) {
datasFuturas.push(datas[j]);
}
}
 
if (datasFuturas.length === 0) {
return "Não há datas futuras disponíveis para agendamento.";}
 
// Exibe no máximo 5 opções
var limite = datasFuturas.length > 5 ? 5 : datasFuturas.length;
var mensagens = [];
 
for (var k = 0; k < limite; k++) {
 
var partes = datasFuturas[k].split("-");
 
var dataFormatada =
partes[2] + "/" +
partes[1] + "/" +
partes[0];
 
var finalMensagem =
k === limite - 1 ? "." : ",";
 
mensagens.push(
"Digite " +
(k + 1) +
", para ver horários disponíveis do dia " +
dataFormatada +
finalMensagem
);
}
 
return mensagens.join("\n");
};

A.2 Data Desejada por opção

() => {
var dados = data_desejada;
 
if (typeof dados === "string") {
try {
dados = JSON.parse(dados);
} catch (e) {
return "";
}
}
 
if (!Array.isArray(dados) || dados.length === 0) {
return "";
}
 
var datas = [];
 
// Mesmas regras utilizadas no menu
for (var i = 0; i < dados.length; i++) {
if (
dados[i] &&
dados[i].day &&
dados[i].is_active !== false &&
dados[i].is_blocked !== true &&
dados[i].is_holiday !== true &&
(
dados[i].available_slots === undefined ||
dados[i].available_slots > 0
)
) {
datas.push(dados[i].day);
}
}
 
// Coloca em ordem crescente
datas.sort();
 
// Data atual no formato YYYY-MM-DD
var hoje = new Date();
var ano = hoje.getFullYear();
var mes = String(hoje.getMonth() + 1).padStart(2, "0");var dia = String(hoje.getDate()).padStart(2, "0");
 
var dataHoje = ano + "-" + mes + "-" + dia;
 
// Mantém somente datas futuras
var datasFuturas = [];
 
for (var j = 0; j < datas.length; j++) {
if (datas[j] > dataHoje) {
datasFuturas.push(datas[j]);
}
}
 
if (datasFuturas.length === 0) {
return "";
}
 
// Opção 1
// Para opções 2, 3, 4... Alterar datasFuturas[1,2,3...]
return datasFuturas[0];
};

A.3 Horários Livres

() => {
var dados = horarios_disponiveis;
 
if (typeof dados === "string") {
try {
dados = JSON.parse(dados);
} catch (e) {
return "Não foi possível interpretar os horários disponíveis.";
}
}
 
if (!Array.isArray(dados) || dados.length === 0) {
return "Não há horários disponíveis para a data selecionada.";
}
 
// Ordena do horário mais cedo para o mais tarde
dados.sort(function(a, b) {
return a.start_date.localeCompare(b.start_date);
});
 
var mensagens = [];
 
for (var i = 0; i < dados.length; i++) {
 
if (!dados[i] || !dados[i].start_date) {
continue;
}
 
var horario = dados[i].start_date.substring(11, 16);
 
var finalMensagem =
i === dados.length - 1 ? "." : ",";
 
mensagens.push(
"Digite " +
(i + 1) +
", para reservar o horário das " +
horario +
finalMensagem
);
}
 
if (mensagens.length === 0) {
return "Não foram encontrados horários disponíveis.";
}
 
return mensagens.join("\n");
};

A.4 Horário Selecionado Cliente

) => {
var dados = horarios_disponiveis;
var indice = parseInt(opcao, 10) - 1;
 
if (typeof dados === "string") {
try {
dados = JSON.parse(dados);
} catch (e) {
return "";
}
}
 
if (!Array.isArray(dados) || dados.length === 0) {
return "";
}
 
// Mantém a mesma ordem exibida ao cliente: mais cedo -> mais tarde
dados.sort(function(a, b) {
return a.start_date.localeCompare(b.start_date);
});
 
if (
isNaN(indice) ||
indice < 0 ||
indice >= dados.length ||
!dados[indice] ||
!dados[indice].start_date
) {
return "";
}
 
var dataHora = dados[indice].start_date;
 
// Se vier como:
// 2026-10-02T09:00:00Z
// transforma em:
// 2026-10-02T09:00:00.000Z
if (
typeof dataHora === "string" &&
dataHora.length === 20 &&
dataHora.substring(19) === "Z"
) {
dataHora = dataHora.substring(0, 19) + ".000Z";
}
 
return dataHora;
};

A.5 Ajusta Data para mensagem

() => {
  if (!data_hora || data_hora.length < 10) {
    return "";
  }
 
  var data = data_hora.substring(0, 10);
  var partes = data.split("-");
 
  if (partes.length !== 3) {
    return "";
  }
 
  return partes[2] + "/" + partes[1] + "/" + partes[0];
};

A.6 Ajusta Hora para mensagem

() => {
  if (!data_hora || data_hora.length < 16) {
    return "";
  }
 
  return data_hora.substring(11, 16);
};

Referência técnica

https://minhaagendavirtual.com.br/api/v3/documents/?version=3