Chatbot para agendamento online

Informações Gerais

Um chatbot para agendamento online é um conjunto de funções de construtor de funil que permite automatizar o processo de agendamento de serviços para a sua empresa.

O fluxo de trabalho do bot é baseado na execução sequencial de funções: recebendo dados para exibir ao cliente e, em seguida, passando esses dados adiante para acionar novas funções e obter novos resultados.

À medida que o cliente avança pelo funil, você deve passar para cada bloco subsequente apenas os dados que correspondem à escolha do cliente — use esses dados para configurar as próximas chamadas de função.

Graças à capacidade de recuperar dados intermediários (por exemplo, cargos de funcionários e categorias de serviços) e passá-los adiante para filtrar funcionários e serviços, você pode configurar seu funil de forma flexível e dar ao cliente controle sobre as etapas de sua progressão.

Todos os métodos descritos neste artigo retornam um array de dicionários.

Para trabalhar com eles de forma conveniente, recomendamos revisar as seções Arrays e Dicionários.

Além disso, para usar a função de geração de ações do usuário (seleção de serviço, data, agendamento), sugerimos considerar o método tools_make_button_str_checker.

Abaixo está um diagrama do fluxo de trabalho do bot, em que cada bloco do diagrama representa uma chamada de função específica, e as setas indicam o fluxo de dados passados de um bloco para outro. As informações transmitidas nesses fluxos permitem filtrar os dados solicitados, bem como criar, cancelar ou modificar um horário de agendamento.

Para ver um diagrama detalhado de configuração do chatbot de agendamento online com as funções em uso, consulte a seção Exemplo de Implementação do Bot deste artigo.

Obtendo Informações da Filial

Para criar um funil de agendamento online e obter informações sobre as filiais do projeto, use a função get_companies_for_booking.

A função retorna uma lista contendo dados de cada filial (funil) que tem “Agendamento Online” ativado em suas configurações.

Os dados são fornecidos em pares chave-valor e incluem o identificador da filial (id), nome (name) e endereço (address).

A função não recebe nenhum parâmetro.

Exemplo de uso:

Chamada da função dentro de um bloco:

Exemplo dos dados retornados:

Obtendo informações sobre cargos ou categorias de serviços

A função get_categories_for_booking(company_id) permite recuperar uma lista de todos os tipos de especialistas ou categorias de serviços de uma filial.

Cada item na lista retornada contém um identificador (id), um nome (name) e uma descrição (description) do cargo ou categoria de serviço. Os dados são representados como pares “chave-valor”:

Parâmetros:

Parâmetro

Descrição

company_id (obrigatório)

Identificador da filial, formato esperado — inteiro.

Exemplo de uso:

Exemplo de chamada da função em um bloco de código:

Obtendo informações sobre funcionários

Se você precisar fornecer informações sobre os funcionários da filial, use a função get_employees_for_booking.

A chamada retornará uma lista de dados contendo o identificador do funcionário (id), nome (name), informações (information) e cargo (job_title).

Você também pode filtrar funcionários por lista de serviços, cargo ou categoria de serviço. Para isso, passe um parâmetro adicional na chamada da função: service_ids, job_title_id ou service_category_id.

Ordem dos parâmetros:

company_id -> service_ids -> job_title_id -> service_category_id

Parâmetros:

company_id (obrigatório)

Identificador da filial, formato esperado — inteiro;

service_ids (opcional)

ID do serviço ou uma lista de IDs de serviços, formato esperado — um inteiro ou uma lista de inteiros entre colchetes separados por vírgulas, por exemplo, [844, 845]

job_title_id (opcional)

ID do cargo, formato esperado — inteiro;

service_category_id (opcional)

Identificador da categoria de serviço, formato esperado — inteiro;

Observação:

Se você quiser recuperar todos os funcionários de uma filial, deixe os valores de service_ids, job_title_id e service_category_id em branco.

Exemplo de chamada: get_employees_for_booking(14275391)

Para filtrar funcionários por uma lista de IDs de serviços, passe a lista como o segundo parâmetro e deixe job_title_id e service_category_id em branco.

Exemplo de chamada: get_employees_for_booking(14275391, [844, 845])

Para filtrar funcionários por cargo, passe o ID para o parâmetro job_title_id e deixe service_ids e service_category_id em branco.

Exemplo de chamada: get_employees_for_booking(14275391, “”, 1021)

Para obter funcionários que prestam serviços de uma categoria específica, deixe service_ids e job_title_id como strings vazias e passe o ID da categoria selecionada para service_category_id.

Exemplo de chamada: get_employees_for_booking(14275391, “”, “”, 1019)

Exemplo de uso:

Chamada da função em um bloco de código:

Exemplo dos dados retornados:

Obtendo informações sobre serviços

Para obter informações sobre os serviços prestados pela filial, use a get_services_for_booking função.

Como resultado da chamada, o bot retornará uma lista contendo dados dos serviços. Cada entrada de serviço inclui um identificador (id), um nome (title), uma descrição (description), um preço (price), e a duração do serviço em minutos (duration).

Você pode filtrar a lista resultante por categoria de serviço, por funcionário ou por ambos simultaneamente. Para isso, passe os parâmetros adicionais service_category_id e/ou employee_id ao chamar a função.

Ordem dos parâmetros:

company_id -> service_category_id -> employee_id

Parâmetros:

company_id (obrigatório)

Identificador da filial, formato esperado – inteiro;

service_category_id (opcional)

Identificador da categoria de serviço, formato esperado – inteiro;

employee_id (opcional)

Identificador do funcionário, formato esperado – inteiro;

Observação na seção “Parâmetros”:

Se você quiser recuperar todos os serviços de uma filial, deixe os service_category_id e employee_id valores em branco.

Exemplo de chamada: get_services_for_booking(14275391)

Se você quiser filtrar serviços por categoria e/ou funcionário, passe os identificadores correspondentes nos service_category_id e employee_id parâmetros. Para filtrar por apenas um parâmetro, forneça uma string vazia para o outro.

Exemplos de chamadas:

get_services_for_booking(14275391, 1018) - filtro por categoria de serviço;
get_services_for_booking(14275391, “”, 512978) - filtro por funcionário;
get_services_for_booking(14275391, 1018, 463665) - filtragem por ambos os parâmetros;

Exemplo de uso:

Chamando a função dentro de um bloco:

Exemplo dos dados retornados:

Obtendo datas disponíveis para agendamento

Depois que o cliente selecionar os serviços para agendamento, ele precisa obter uma lista de datas disponíveis.

Para gerar essa lista, use a get_dates_for_booking função.

A função verificará os horários disponíveis e retornará uma lista de datas adequadas no formato “dia.mês.ano”.

A ordem dos parâmetros é a seguinte:

company_id -> service_ids -> employee_id -> days_limit

Parâmetros:

company_id (obrigatório)

identificador da filial, formato esperado – inteiro;

service_ids (opcional)

lista de identificadores de serviços para agendamento, formato esperado – inteiro ou uma lista de inteiros entre colchetes separados por vírgulas (por exemplo, 842 ou [842, 843]);

employee_id (opcional)

identificador do funcionário, formato esperado – inteiro. Se o valor do parâmetro for deixado em branco ou passado como uma string vazia “”, a função buscará datas disponíveis entre todos os funcionários que fornecem o conjunto completo de serviços da lista service_ids;

days_limit (opcional)

número de dias a partir da data atual dentro dos quais a busca por datas disponíveis é realizada, formato esperado – inteiro, valor padrão – 14 (dias);

Exemplo de uso:

Chamando a função dentro de um bloco:

Exemplo dos dados retornados:

Obtendo horários disponíveis para agendamento

Para obter uma lista de horários disponíveis para agendamento, use a get_slots_for_booking função.

A função verificará o horário disponível na data selecionada e retornará uma lista de horários livres no formato “horas:minutos”, por exemplo [“09:00”, “11:00”, “14:30”, “16:00”].

A ordem dos parâmetros é a seguinte:

company_id -> service_ids -> employee_id -> slot_interval

Parâmetros:

company_id (obrigatório)

identificador da filial, formato esperado – inteiro;

service_ids (opcional) -

lista de identificadores de serviços para agendamento, formato esperado – inteiro ou uma lista de inteiros (por exemplo, 842 ou [842, 843]);

date (opcional) -

data para verificação de horários, formato esperado – string no formato “dia.mês.ano”, por exemplo “01.01.2024”;

employee_id (opcional)

identificador do funcionário, formato esperado – inteiro. Se o valor do parâmetro for deixado em branco ou passado como uma string vazia, a função buscará horários livres nas agendas de todos os funcionários que trabalham na data selecionada e fornecem o conjunto completo de serviços da lista service_ids;

slot_interval (opcional)

intervalo em minutos entre os horários disponíveis, formato esperado – inteiro, valor padrão – 30 (minutos);

Exemplo de uso:

Chamada da função no bloco:

Exemplo dos dados retornados:

Criando um agendamento

Para criar um agendamento online, use a create_booking função.

Se o agendamento for bem-sucedido, a função retornará informações sobre o status da operação (status) com o valor True e os detalhes do agendamento (booking) no formato “chave: valor”.

Os dados do novo agendamento incluem:

identificador (id),
data (booking_date),
horário (booking_time),
nomes dos serviços (services),
duração do agendamento (service_duration),
custo total (total_cost),
nome do funcionário designado (employee_name) e seu cargo (job_title),
nome da filial (company_name) e endereço da filial (company_address)

no formato “chave: valor”.

Ordem dos parâmetros:

company_id -> service_ids -> booking_date -> booking_time -> employee_id

Parâmetros:

company_id (obrigatório)

identificador da filial, formato esperado – inteiro;

service_ids (obrigatório)

lista de identificadores de serviços para agendamento, formato esperado – inteiro ou uma lista de inteiros (por exemplo, 5 ou [5, 10, 15]);

booking_date (obrigatório)

data do agendamento, formato esperado – string no formato “dia.mês.ano”, por exemplo “15.01.2024”;

booking_time (obrigatório)

horário do agendamento, formato esperado – string no formato “horas:minutos”, por exemplo “12:30”;

employee_id (opcional)

identificador do funcionário, formato esperado – inteiro. Se o valor do parâmetro for deixado em branco ou passado como uma string vazia “”, a função fará o agendamento com um funcionário aleatório que forneça o conjunto completo de serviços da lista service_ids, se eles estiverem disponíveis na data e hora especificadas;

Exemplo de uso:

Chamada da função no bloco:

Exemplo de resposta de agendamento bem-sucedido:

Ao criar agendamentos e, posteriormente, solicitar novamente os horários disponíveis, você notará que as listas ficaram menores. Por exemplo, em 05.02.2024, o horário de 18:00 não está mais disponível (ele estava livre apenas na agenda de Victoria) e, para Paul Thompson, os agendamentos para corte de cabelo masculino e modelagem de barba agora podem ser feitos das 9:00 às 14:00, já que a duração total dos serviços é de 1 hora e 45 minutos, e Pavel já tem outro agendamento às 16:00.

Obtendo informações sobre os próximos agendamentos de um cliente

Você pode visualizar os agendamentos atuais de um cliente chamando a get_bookings_info função.

A resposta retornará uma lista de agendamentos ativos, juntamente com informações detalhadas de cada agendamento.

As informações do agendamento são fornecidas no formato “chave: valor” e incluem:

identificador do agendamento (booking_id),
data (booking_date),
horário (booking_time),
identificadores (service_ids) e nomes (service_names) dos serviços selecionados,
duração do agendamento (booking_duration),
custo total dos serviços (total_cost),
identificador (employee_id) e nome (employee_name) do funcionário designado, e seu cargo (job_title),
identificador da filial (company_id)
nome da filial (company_name) e endereço (company_address).

Parâmetros:

client_id (opcional)

ID do cliente, req – Este parâmetro é obrigatório se você quiser recuperar agendamentos de um cliente específico; por padrão, usa o ID do cliente da conversa com o bot.

Exemplo de uso:

Chamada da função no bloco:

Exemplo dos dados retornados:

Alterando a data e a hora do agendamento

Um cliente pode alterar independentemente a data e a hora do agendamento. Para isso, ele precisa acessar o bloco do funil onde a modify_booking_time função é chamada.

Se a operação for bem-sucedida, a função retornará o status da operação (status) com o valor True e uma mensagem (message) “Horário do agendamento modificado” no formato “chave: valor”.

Ordem dos parâmetros:

order_id -> new_date -> new_time

Parâmetros:

order_id (obrigatório)

identificador do agendamento, valor esperado – inteiro;

new_date (obrigatório)

nova data do agendamento, formato esperado – string no formato “dia.mês.ano”, por exemplo “16.01.2024”;

new_time (obrigatório)

novo horário do agendamento, formato esperado – string no formato “horas:minutos”, por exemplo “14:30”;

Exemplo de uso:

Chamada da função no bloco:

Resposta do bot para uma operação bem-sucedida:

O horário de 16:00 anteriormente ocupado agora está disponível para agendamento, e a criação de um novo agendamento para os mesmos serviços agora só pode ser feita a partir de 11:00

Nas informações de agendamento do cliente, você também verá o horário do agendamento atualizado:

Cancelando um agendamento

Um cliente pode cancelar independentemente um agendamento existente. Para isso, ele precisa acessar o bloco onde a cancel_booking função é chamada.

Um cancelamento bem-sucedido retornará o status da operação (status) com o valor True e uma mensagem (message) “Agendamento excluído” no formato “chave: valor”.

Ordem dos parâmetros:

pipeline_id -> order_id

Parâmetros:

pipeline_id (obrigatório)

identificador da filial, valor esperado – inteiro;

order_id (obrigatório)

identificador do agendamento, valor esperado – inteiro;

Exemplo de uso:

Chamada da função no bloco:

Resposta do bot para um cancelamento bem-sucedido:

Após o cancelamento, os horários “09:00” e “10:00” ficam disponíveis novamente para agendamento:

Exemplo de implementação do bot

Configurações do chatbot

Bloco nº 1. Início. Nenhuma ação especial é necessária

Bloco nº 2. Neste bloco, recuperamos os dados que serão fornecidos ao cliente.

Descrição do conteúdo da calculadora:

comp_id - identificador do bloco de serviço, que pode ser encontrado na seção “Serviços”;
data - informações sobre os serviços prestados
res - dicionário com dados necessários para gerar botões e definir condições
numbered_list - pode ser útil se a lista de serviços precisar ser duplicada em formato de texto
buttons - array de botões gerados a partir dos dados do serviço
checker - array de nomes de serviços, usado para definir condições de passagem para o próximo bloco

Bloco nº 3. Recupere e exiba os dados sobre o serviço selecionado.

title - no array de dicionários data, encontre o dicionário onde a chave title é igual a question. Desse dicionário, obtenha o valor para a mesma chave title

description - da mesma forma, obtenha o valor para a chave description

price - da mesma forma, obtenha o valor para a chave price

serv_id - da mesma forma, obtenha o valor para a chave id

b - crie um array de strings que será exibido como botões abaixo da mensagem

res - a partir do array b, crie um array de dicionários como no bloco anterior

buttons - obtenha o array para exibir os botões

Agora temos variáveis contendo o nome, a descrição e o preço do serviço selecionado pelo cliente

Bloco nº 4. Exibir datas de agendamento disponíveis

print_dates - use a função para obter as datas de agendamento disponíveis para o serviço selecionado

print_dates - adicione a string “Voltar para a lista de serviços” ao array de datas se quiser que esse botão apareça junto com as datas.

Para a seta que retorna à etapa anterior, defina uma prioridade maior do que a seta com #{checker}, porque #{checker} também contém a condição “Voltar para a lista de serviços”.

Bloco nº 5. No bloco nº 5 salvamos a data escolhida pelo cliente. Isso deve ser feito em um bloco separado porque, nas etapas seguintes, ao retornar ao Bloco 6, a variável question já não conterá a data escolhida pelo cliente.

Bloco nº 6. Seleção e exibição de horários disponíveis para agendamento.

data - obtemos os horários disponíveis.

A lógica é a mesma do Bloco nº 4 com a exibição das datas disponíveis. Também é importante não esquecer de configurar uma prioridade maior para a seta “Voltar para a seleção de data”

Bloco nº 7. Salvamento do horário escolhido em uma variável e tentativa de agendar o cliente.

choosed_time - salvamos o horário

a - tentativa de agendar o cliente

booking_result - obtemos o resultado da execução da função.

É necessário obter o resultado, pois várias pessoas podem tentar agendar para o mesmo horário ao mesmo tempo.

Bloco nº 7.1. Não foi possível agendar o cliente.

Este bloco é necessário apenas para exibir a mensagem de erro. Após o envio da mensagem, retornamos o cliente para a seleção do horário de agendamento

Bloco nº 8. Agendamento realizado com sucesso.

Informamos ao cliente que ele foi agendado para o serviço e exibimos o botão para pagamento.

Exemplo de configuração dos botões.

Para a configuração, usamos as variáveis que obtivemos no bloco nº 3:

Bloco nº 8.1.

Neste bloco, confirmamos o pagamento bem-sucedido. Configuramos a transição para o bloco de acordo com o sistema de pagamento utilizado

Bloco nº 8.2. O cliente não pagou pelo serviço. Cancelamento do agendamento

Se o cliente não pagar pelo serviço a tempo, podemos cancelar o agendamento, se necessário.

or_id - obtemos o id do pedido

cancel_status - após a execução da função, obtemos a resposta sobre se o cancelamento foi concluído com sucesso.

Neste exemplo, o cliente entrará no bloco de cancelamento 5 segundos após receber o link de pagamento; na situação real, você pode definir o tempo necessário, apenas não se esqueça de ativar a opção “Cancelar se sair do bloco”.