Lembretes de consulta com o Zoho Bookings
Com estes passos, a Atendia liga a cada pessoa a lembrar a consulta que ela marcou no Zoho Bookings. Colas dois textos no Zoho e crias três fluxos de trabalho. O resto faz-se sozinho. A Atendia não lê a tua agenda: é o Zoho que pede cada chamada.
Antes de começar
- Um plano do Zoho Bookings que deixe correr funções personalizadas. A ajuda do Zoho diz que os fluxos personalizados são do plano Premium. O período de teste do Zoho deixa usá-las.
- Um agente da Atendia com número, para fazer as chamadas de lembrete.
- Uma chave «Leitura e chamadas» só para isto, com o nome «Zoho Bookings». Cria-a na consola, em «Definições» → «Chaves API» → «Nova chave API». Copia a chave quando a consola a mostra: só aparece uma vez.
- O id do agente. Abre a página do agente na consola: o id é a parte do endereço depois de
/agents/.
O texto para colar
Há dois textos. Os dois têm os mesmos dois espaços a preencher, entre parênteses retos. Troca cada um pelo teu valor: apaga também os parênteses retos e mantém as aspas.
[cola aqui a chave]: a chave «Zoho Bookings», copiada quando a consola a mostrou. Só aparece uma vez. Se a perdeste, cria uma chave nova e revoga a antiga.[cola aqui o id do agente]: a parte do endereço da página do agente depois de/agents/.- Cola a chave só em
[cola aqui a chave], nos dois textos.
Se o botão «Copiar» não copiar, seleciona o texto todo e copia-o à mão.
Texto 1: pedir o lembrete
Para o fluxo do lembrete, o que corre antes da consulta («Início da marcação», «Antes»).
// Atendia: pede a chamada de lembrete desta marcação.
chaveAtendia = "[cola aqui a chave]";
agente = "[cola aqui o id do agente]";
telefone = ifnull(bookingInfo.get("customer_contact_no"),"").trim();
if(telefone == "")
{
info "Atendia: marcação sem telefone, não pede chamada.";
}
else
{
marcacao = bookingInfo.get("booking_id").replaceAll("#","");
inicio = bookingInfo.get("iso_start_time");
nome = ifnull(bookingInfo.get("customer_name"),"").replaceAll("[^\p{L} '-]","").trim();
if(nome.length() > 60)
{
nome = nome.subString(0,60);
}
variaveis = Map();
variaveis.put("nome",nome);
variaveis.put("data_consulta",bookingInfo.get("start_time"));
corpo = Map();
corpo.put("agentId",agente);
corpo.put("phoneNumber",telefone);
corpo.put("reference","zoho-" + marcacao);
corpo.put("notAfter",inicio);
corpo.put("dynamicVariables",variaveis);
cabecalhos = Map();
cabecalhos.put("Content-Type","application/json");
cabecalhos.put("x-api-key",chaveAtendia);
cabecalhos.put("Idempotency-Key","zoho-" + marcacao + "-" + inicio);
resposta = invokeurl
[
url :"https://api.atendia.pt/api/v1/outbound-calls"
type :POST
parameters:corpo.toString()
headers:cabecalhos
detailed:true
];
codigo = resposta.get("responseCode");
if(codigo == 200 || codigo == 201)
{
info "Atendia: chamada pedida (" + codigo + ").";
}
else
{
info "Atendia: ERRO " + codigo + " " + resposta.get("responseText");
}
}Texto 2: cancelar
Para os fluxos «Cancelado» e «Reagendado». É o mesmo texto nos dois.
// Atendia: cancela as chamadas desta marcação que ainda não acabaram.
chaveAtendia = "[cola aqui a chave]";
agente = "[cola aqui o id do agente]";
marcacao = bookingInfo.get("booking_id").replaceAll("#","");
cabecalhos = Map();
cabecalhos.put("x-api-key",chaveAtendia);
procura = invokeurl
[
url :"https://api.atendia.pt/api/v1/outbound-calls?limit=100&agentId=" + agente + "&reference=" + encodeUrl("zoho-" + marcacao)
type :GET
headers:cabecalhos
detailed:true
];
if(procura.get("responseCode") != 200)
{
info "Atendia: ERRO na procura " + procura.get("responseCode") + " " + procura.get("responseText");
}
else
{
chamadas = procura.get("responseText").toString().toMap().get("data").get("items");
for each chamada in chamadas
{
estado = chamada.get("status");
if(estado == "SCHEDULED" || estado == "IN_PROGRESS")
{
id = chamada.get("outboundId");
resposta = invokeurl
[
url :"https://api.atendia.pt/api/v1/outbound-calls/" + id + "/cancel"
type :POST
headers:cabecalhos
detailed:true
];
codigo = resposta.get("responseCode");
emCurso = false;
if(codigo == 400)
{
detalhes = ifnull(resposta.get("responseText").toString().toMap().get("details"),Map());
if(detalhes.get("furtherAttempts") == false)
{
emCurso = true;
}
}
if(codigo == 200)
{
info "Atendia: cancelada " + id + ".";
}
else if(codigo == 404)
{
info "Atendia: não encontrada " + id + ".";
}
else if(emCurso)
{
info "Atendia: em curso, acaba sem mais tentativas: " + id + ".";
}
else
{
info "Atendia: ERRO " + id + " " + codigo + " " + resposta.get("responseText");
}
}
}
}Os passos no Zoho
Os nomes dos menus são os que o Zoho Bookings mostra em português. Crias três fluxos: o lembrete, «Cancelado» e «Reagendado».
- No Zoho Bookings, troca para a tua área de trabalho: «COMUTAR ÁREAS DE TRABALHO» → a tua área de trabalho. Os fluxos não aparecem em «O meu espaço».
- Abre «Fluxos de trabalho», na barra lateral, e o separador «Fluxos de trabalho personalizados». Aí, carrega em «Criar fluxo de trabalho» e, no ecrã dos modelos, em «Criar novo fluxo de trabalho».
- Fluxo do lembrete: em «Aciona quando», escolhe «Início da marcação». Em «Ocorrência», escolhe «Antes», um número e «Minutos» ou horas. É a antecedência do lembrete.
- Em «Executar ação», escolhe «Executar funções personalizadas».
- Carrega em «Personalizar modelo», cola o texto 1 com os teus dois valores e carrega em «Guardar».
- Carrega em «Criar fluxo de trabalho». Sem personalizar o modelo, o Zoho recusa criar o fluxo.
- Cria um segundo fluxo: em «Aciona quando», «Cancelado»; em «Ocorrência», «Imediatamente»; a mesma ação, com o texto 2.
- Cria um terceiro fluxo igual ao segundo, com «Reagendado» em «Aciona quando».
- Para mudar um texto mais tarde, recarrega a página e abre o fluxo a partir da lista. O editor que o Zoho reabre sozinho depois de «Criar fluxo de trabalho» não guarda as mudanças.
O texto de cancelar é sempre preciso. Quando uma consulta é cancelada ou remarcada, a chamada pode já existir: à espera de uma nova tentativa, uma chamada de volta marcada, ou em curso. Sem este fluxo, ela sai na mesma. Numa remarcação, o fluxo do lembrete corre só na hora nova e pede uma chamada nova.
Testar
- Faz uma marcação de teste para o teu telemóvel, com a consulta perto, para o lembrete ser daí a poucos minutos. A marcação tem de ser feita antes da hora do lembrete.
- Atenção: o «Executar» faz o que o texto faz, a sério. No texto 1, pede uma chamada real. No texto 2, o «Executar» cancela as chamadas reais dessa marcação que ainda não acabaram. Usa só a marcação de teste. Para não esperar, abre a função do texto 1 e carrega em «Executar». O Zoho pede o Booking ID: é o código da marcação sem o «#», por exemplo
AT-00007. Com o «#», o Zoho responde «Forneça uma id de marcação válida». As linhasinfoaparecem em «Mensagens de registo». - O «Executar» corre a versão guardada da função, não o texto aberto no editor. Guarda sempre antes de testar.
- Na consola, procura a referência
zoho-e o código da marcação no histórico das chamadas. Deve haver uma linha. - Remarca a consulta. O fluxo do lembrete não corre na hora antiga: corre só na hora nova, e aparece uma linha nova.
- Cancela a consulta. Se havia uma chamada por sair, fica cancelada. Se o lembrete ainda não tinha corrido, não há chamada nenhuma, e está certo.
O que os textos fazem e as opções do agente
O que os textos fazem
- Ligam para o telefone como o Zoho o guarda:
+351e o número, sem espaços. O Zoho guarda-o assim, mesmo que o escrevas com espaços. - Põem «não ligar depois de» (
notAfter) na hora da consulta. A chamada nunca sai depois de a consulta começar. - Dão à chamada a referência
zoho-e o código da marcação, sem o «#». O Zoho escreve o código como#AT-00007; a referência ficazoho-AT-00007. É por ela que procuras a chamada no histórico. - Mandam uma marca de pedido repetido (
Idempotency-Key) feita com o código da marcação e a hora da consulta. O mesmo aviso do Zoho, repetido, não cria duas chamadas. Uma consulta remarcada tem outra hora, por isso não se confunde com a anterior. - Mandam duas variáveis:
nome, o nome da pessoa, edata_consulta, a data e a hora da consulta, como o Zoho as escreve. Usa-as nas instruções do agente. O texto não manda o nome do serviço: pode dizer o motivo da consulta, que é um dado de saúde. - Uma marcação sem telefone não pede chamada.
- Uma marcação feita depois da hora do lembrete também não: o Zoho não corre o fluxo. A pessoa acabou de marcar.
- O texto de cancelar procura as chamadas pela referência exata e pelo agente. Cancela só as que ainda não acabaram: as «Agendadas» e a que está em curso. Uma chamada que já não existe (
404) conta como feita. A que está em curso acaba normalmente, sem mais tentativas nem chamada de volta, e também conta como feita. - Cada resposta da Atendia fica numa linha
info. Só o «Executar» do editor do Zoho mostra essas linhas (ver «Como é uma falha»).
Como se cancela uma chamada pela API
Opções do agente que ajudam nos lembretes
Não são precisas, mas ajudam. A segunda já vem no texto. As outras estão na consola, em «Regras de saída», na página do agente.
- O horário do agente: um lembrete pedido fora do horário espera pela abertura seguinte. Saber mais
- «Não ligar depois de»: o texto põe-no na hora da consulta. A chamada à espera nunca sai depois dessa hora; se ela passar, fica «Falhada». Saber mais
- «Nova tentativa»: se ninguém atender, a Atendia volta a ligar mais tarde, sempre antes do limite. Saber mais
- A caixa de correio: o agente pode deixar uma mensagem. Não ponhas nela o motivo da consulta nem outros dados de saúde. Saber mais
- «Ligue-me mais tarde»: a pessoa pede para lhe ligarem depois, e a chamada de volta fica marcada, sempre antes do limite. Saber mais
O Construtor ajuda-te a escrever as instruções de um agente de lembretes. Não ponhas nelas o motivo da consulta nem outros dados de saúde.
Como é uma falha
O registo de auditoria do Zoho diz que o fluxo foi «executado» mesmo quando a Atendia recusa o pedido (401, 403). O Zoho não mostra a falha. Vês a falha em dois sítios:
- No «Executar» do editor da função: as «Mensagens de registo» mostram o código, por exemplo
Atendia: ERRO 401. - No histórico das chamadas da Atendia: sem nenhuma linha com a referência da marcação, o Zoho não chegou à Atendia.
Erros comuns
- Chave errada ou revogada:
401UNAUTHORIZED. - Chave «Só leitura»:
403API_KEY_CANNOT_CALL. Cria uma chave «Leitura e chamadas». - Agente errado: o id não é de um agente desta conta. Copia-o outra vez do endereço da página do agente.
- Telefone sem indicativo: escreve o telefone no Zoho com o país escolhido.
- Texto mudado para a mesma marcação: o pedido repetido com dados diferentes dá
409IDEMPOTENCY_KEY_REUSED.
- Uma linha «Falhada» no histórico mostra o motivo.
- Uma chamada cancelada aparece como «Cancelada» (
FAILED, motivocancelled). - Se a hora da consulta passar com a chamada à espera, ela já não sai: aparece como «Falhada», com o motivo «Fora do prazo» (
FAILED, motivodeadline_passed).
Todos os códigos de recusa · Todos os motivos de falha
Desfazer
- No Zoho, desliga (ou apaga) os três fluxos: o lembrete, «Cancelado» e «Reagendado».
- Na consola, revoga a chave «Zoho Bookings» em «Chaves API». Se houver chamadas por sair, a consola pergunta se as cancela ou se as mantém.
Avisos
- A chave fica escrita no Zoho. Quem administra o Zoho consegue vê-la.
- Uma chave «Leitura e chamadas» pede chamadas, pagas pelo saldo da conta. Também lê os dados da conta: o histórico e as transcrições das chamadas, a configuração dos agentes e a faturação. Por isso usas uma chave só para o Zoho.
- Quando sai da empresa alguém que administrava o Zoho, troca a chave: cria uma nova, cola-a nos três fluxos e revoga a antiga.
- Revogar a chave faz parar os lembretes, sem aviso. Vê o histórico das chamadas de vez em quando.
- Duas marcações para o mesmo telefone dão duas chamadas.
- Uma chave de chamadas da conta pode cancelar qualquer chamada pedida por uma chave dessa conta. É o texto que filtra pelo agente e pela referência: não lhe tires esse filtro.
- Uma consulta remarcada de volta para a hora antiga, até 24 horas depois de a chamada antiga acabar, reaproveita o pedido antigo: não sai chamada nova. Uma consulta remarcada para dentro da antecedência do lembrete fica sem lembrete: o Zoho não corre o fluxo.
- O nome (
nome) é escrito por quem marca, na página pública do Zoho. Por isso o texto 1 limpa-o: deixa só letras, espaços, hífenes e apóstrofos, até 60 caracteres.