SDK - Chatbot

Funções do SDK

Esta seção reúne as principais funcionalidades disponíveis para integração com o Tatodesk, incluindo recursos do SDK, envio de mensagens via WhatsApp e SMS, além de operações relacionadas a notificações, CRM e metadados de sessão. Abaixo, você encontrará um menu interativo que facilita a navegação entre os tópicos, permitindo acesso rápido às descrições e exemplos de uso de cada funcionalidade.

Clique nos tópicos abaixo para navegar rapidamente entre os assuntos:

• Envio de textos e multimídias;

• Envio de multimídia passando Headers - Criação de URL;

• Construção dinâmica de botões;

• Registrando e capturando variáveis na sessão;

• Canais;

• Registrando Informações Adicionais;

• CRM;

• Ticket;

• Contact Center;

• ChatBot;

• Marketing.

Envio de textos e multimídias

Essas funções são utilizadas para interagir com o SDK e enviar mensagens formatadas de diferentes tipos, como texto, imagem, arquivo, vídeo, áudio e link.

sdk.send.text("seu texto")

sdk.send.image(url)

sdk.send.file(url)

sdk.send.video(url)

sdk.send.audio(url)

sdk.send.link("Texto","Url")

Envio de multimídia passando Headers - Criação de URL

sdk.chatbot.externalMedia(method, url, options, body)

Aqui é feito uma chamada à uma api externa e utiliza-se dos parâmetros (method, url, options e body) para requisitar os dados dessa api.

Exemplo de caso de uso:

  const method = 'GET'
  
  const url = `https://www.backendcliente.xx.gov.br/certidao/pdf idProfissional=${idProfissional}`
  
  const options = {
    headers: {
      'Authorization': token,
      'Application': 4
    }
  }
  
  const res = await sdk.chatbot.externalMedia(method, url, options, body)
  { chatbotExternalMedia, error } = res

  chatbotExternalMedia: String | null  (Link de acesso à mídia      externa) 
 error: Error | null

Neste exemplo, por meio do método GET (solicitação de dados), é feita uma requisição de um link externo passando um parâmetro pela URL, e através das 'options' são incluídos os cabeçalhos (headers) com informações de autorização.

A constante 'res' faz a chamada à API, que possui o link externo solicitado.

O resultado da chamada à API pode ter duas propriedades: 'chatbotExternalMedia', que pode ser uma string ou nulo. Se a resposta for bem-sucedida, será retornado o link. Caso contrário, a propriedade 'error', que é um objeto de erro ou nulo, conterá informações sobre o erro ocorrido.

Construção dinâmica de botões

const mensagemDoBotao = `Titulo acima dos botões`

const botoes = [
  {
    title: "Primeiro botão",
    payload: "Primeiro botão",
    without_bold: true
  },
  {
    title: "Segundo botão",
    payload: "Segundo botão",
    without_bold: true
  }
]

sdk.send.buttons(mensagemDoBotao, botoes)

A função buttons é chamada a partir do objeto send do SDK e recebe dois argumentos. O primeiro é uma string, que define o título exibido acima dos botões. O segundo é um array de objetos, onde cada objeto representa um botão.

Cada objeto pode conter as seguintes propriedades:

• title: texto exibido no botão;

• payload: valor que identifica o botão quando ele é clicado;

• without_bold: valor booleano (true ou false) que define se o texto será exibido sem negrito;

Registrando e capturando variáveis na sessão

await sdk.session.setAttribute(key,value)

let minhaVariavel = await sdk.session.getAttribute(key)

await sdk.session.deleteAttribute(key)

Em sdk.session.setAttribute(key, value), a função setAttribute é chamada no objeto session do SDK para definir um atributo na sessão, onde key representa a chave do atributo e value o valor associado a essa chave.

Já em sdk.session.getAttribute(key), é chamada a função getAttribute no mesmo objeto para recuperar o valor armazenado na chave informada. O resultado retornado é armazenado na variável minhaVariavel.

Por fim, em sdk.session.deleteAttribute(key), a função deleteAttribute é usada para remover um atributo da sessão, identificado pela chave key.

Assim, uma expressão define, outra recupera e outra exclui informações específicas do usuário durante a sessão.

Request Get

const config = {
  headers: {
    'Convenio':convenio,
    'Origem':origem,
    'Authorization': authorization
  }
}
const res = await sdk.net.get(`https://seudominio.com`,config)

No exemplo, o objeto config contém a propriedade headers, que reúne três cabeçalhos compostos por pares de chave e valor:

• Convenio: chave 'Convenio' e valor da variável convenio;

• Origem: chave 'Origem' e valor da variável origem;

• Authorization: chave 'Authorization' e valor da variável authorization.

A constante res armazena o resultado da requisição, e o uso do await faz com que o código aguarde a conclusão da chamada get antes de prosseguir com a execução.

Dessa forma, o programa só continua após o término da requisição e o recebimento da resposta do servidor.

Request Post

const config = {
  headers: {
    'Convenio':convenio,
    'Origem':origem,
    'Authorization': authorization
  }
}

O objeto config possui a propriedade headers, que contém três cabeçalhos definidos em pares de chave e valor:

• Convenio: chave 'Convenio' e valor da variável convenio;

• Origem: chave 'Origem' e valor da variável origem;

• Authorization: chave 'Authorization' e valor da variável authorization.

Response

const req = {
  nome_campo: valor_compo,
  nome_campo_2: valor_campo_2
}

Aqui é criado um objeto que possui as propriedades nome_campo e nome_campo_2, cada uma recebendo um valor correspondente de mesmo nome.

Request

const res = await sdk.net.post(`https://seudominio.com`, req, config);

Em sdk.net.post(https://seudominio.com`, req, config) esta sendo utilizada a função post do objeto net do sdk para realizar uma requisição HTTP POST para a url.

Canais

sdk.channel.isWebchat()
sdk.channel.isWhatsapp()
sdk.channel.isInstagram()
sdk.channel.isTelegram()
sdk.channel.isFacebookMessenger()

As funções do SDK são utilizadas para identificar o canal em uso. Cada uma delas retorna um valor booleano (true ou false), informando se o canal específico está ativo.

Registrando Informações Adicionais

Info Chatbot:

await sdk.chatbot.addInfo(key, value)

Info Atendimento Digital:

await sdk.contactCenter.setDataItem(key, value)

const objZap = sdk.session.getMetadataWhatsapp()

await sdk.chatbot.addInfo('NUMERO_WHATSAPP', objZap['phone'])

A função getMetadataWhatsapp é chamada no objeto session do SDK para capturar informações da sessão atual do WhatsApp e armazenar o resultado na variável objZap.

Em seguida, a função addInfo é chamada no objeto chatbot do SDK, passando dois argumentos: a chave 'NUMERO_WHATSAPP' e o valor correspondente objZap['phone'].

CRM

const person = await sdk.crm.getPersonByText("81900000000")
{
  person: {
    ID: string
  },
  customFields: [
    {
      key: string,
      value: string
    }
  ],
  tags: [
    {
      name: string
    }
  ]
}

Executa uma consulta por número de telefone via get e retorna um objeto com as propriedades:

• person — dados básicos da pessoa (ex.: ID);

• customFields — array de campos personalizados { key, value };

• tags — array de etiquetas { name }.

const person = {
  firstName:"nome da pessoa",
  emails:["[email protected]"],
  phones:["81900000000"],
  tags:["WHATSAPP-OPT-IN"]
}

const p = await sdk.crm.createPerson(person)

O objeto person é criado com as propriedades firstName, emails, phones e tags, que armazenam as informações da pessoa a ser cadastrada. Em seguida, o método createPerson recebe esse objeto como argumento, utilizando seus dados para criar um novo registro de pessoa no CRM.

Adicionando Etiqueta no CRM

await sdk.crm.addTag(PERSON_ID,"TAG_NAME")

O método addTag é chamado no objeto crm do sdk, recebendo como parâmetros PERSON_ID e TAG_NAME. Ele utiliza essas informações para adicionar a tag especificada ao registro da pessoa correspondente no CRM.

Adicionando Campos Customizados no CRM

const persons = await sdk.crm.listCRMPersonsByCustomField("KEY",value)

Na constante persons, é chamado o objeto sdk, que retorna uma lista de pessoas armazenadas no crm. Os parâmetros "KEY" e value são utilizados na busca para filtrar os registros de acordo com o campo personalizado informado.

Exemplo Estrutura Completa do Objeto

[
  {
    "person": {
      "ID"
    },
    "customFields": [
      {
        "key": "string",
        "value": "string"
      }
    ],
    "tags": [
      {
        "name": "string"
      }
    ]
  }
]

Essa estrutura contém o objeto person, que possui a propriedade ID do tipo string. O customFields é um array que armazena objetos com as propriedades key e value, representando os campos personalizados do person. Por fim, o array tags contém objetos com a propriedade name, que indica as tags associadas à pessoa.

Ticket

Create Ticket

Possibilidades de se criar tickets através da SDK do builder, como alternativa aos formulários mágicos.

Estrutura do Componente - Exemplo:

const forms = []

forms.push({ key: "EMAIL", value: email })
forms.push({ key: "MATRICULA", value: matricula })
forms.push({ key: "CPF/CNPJ", value: documento })
forms.push({ key: "NOME", value: nomeCompleto })
forms.push({ key: "ENDEREÇO_DO_IMOVEL", value: endereco })
forms.push({ key: "TELEFONE", value: telefone })

if (comprovante) {
  forms.push({ key: "DOCUMENTO_DO_IMOVEL", value: comprovante })
}

forms.push({ key: "IDENTIDADE", value: imagemDocumento })
forms.push({ key: "SELFIE", value: imagemCliente })
forms.push({ key: "CONTA_DE_AGUA_DO_IMOVEL", value: imagemConta })

if (imagemContaPaga) {
  forms.push({ key: "COMPROVANTE_DE_PAGAMENTO_RECENTE", value: imagemContaPaga })
}

forms.push({ key: "INFORME_SUA_RELAÇAO_COM_O_IMOVEL", value: relacao })

const res = await sdk.ticket.create(
  organizationID,
  projectID,
  departmentID,
  description,
  attendanceTypeIDs,
  forms,
  formID,
  2
)

No código, a constante forms é um array que começa vazio e vai recebendo objetos por meio do método push. Cada objeto possui as propriedades key e value, por exemplo, { key: "EMAIL", value: email }, adicionando o campo "EMAIL" com seu respectivo valor. O if é usado para incluir campos opcionais, como { key: "DOCUMENTO_DO_IMOVEL", value: comprovante }, apenas quando a variável comprovante estiver definida.

A constante res armazena o retorno da função create do objeto ticket do sdk, que recebe diversos parâmetros (organizationID, projectID, departmentID, description, attendanceTypeIDs, forms, formID, 2) e cria um novo ticket no sistema com os dados fornecidos.

Contact Center

Pulando o formulário mágico ao ser direcionado ao atendente humano:

await sdk.contactCenter.skipForm()

Pulando o grupo, subgrupo, especialidade, subespecialidade, área e subárea:

await sdk.contactCenter.skipQuestion()

Pulando o horário de atendimento personalizado:

await sdk.contactCenter.skipAttendanceGroupOpeningHour()

O await indica que cada uma dessas chamadas é assíncrona, ou seja, o código aguarda sua execução antes de prosseguir. Cada método é responsável por ignorar uma etapa específica do fluxo:

• skipForm() → pula o formulário mágico, enviando o atendimento diretamente ao humano.

• skipQuestion() → ignora as perguntas de categorização (grupo, subgrupo, especialidade, área, etc.).

• skipAttendanceGroupOpeningHour() → pula a verificação do horário de atendimento personalizado.

Dessa forma, o fluxo segue automaticamente para a próxima etapa, tornando o processo mais ágil e evitando que o usuário precise preencher ou selecionar informações já conhecidas pelo sistema.

Atribuindo informação no atendimento ao ser direcionado ao atendente humano:

Chave - Valor Chaves disponíveis para uso:

• CPF_CNPJ

• NOME

await sdk.contactCenter.setFormItem("CPF_CNPJ", cpf)

A função setFormItem("CPF_CNPJ", cpf) é utilizada para definir um item do formulário durante o atendimento. O comando await indica que a chamada é assíncrona, ou seja, o código aguardará a conclusão da operação antes de prosseguir.

O objeto sdk contém o objeto contactCenter, responsável pelas operações relacionadas ao atendimento humano. No exemplo acima, o campo "CPF_CNPJ" é definido com o valor armazenado na variável cpf, exibindo essa informação na fila do atendente.

Obtendo variáveis da sessão:

await sdk.session.getMetadataWebchat()

A função getMetadataWebchat() é utilizada para obter os metadados da sessão atual do canal Webchat. O comando await indica que a chamada é assíncrona, ou seja, o código aguardará o retorno dos dados antes de continuar a execução.

O objeto sdk contém o objeto session, responsável por armazenar e fornecer informações relacionadas à sessão ativa. Como resultado, são retornadas as informações de contexto do atendimento em andamento no Webchat.

Exemplo de caso de uso:

const metadataWebchat = sdk.session.getMetadataWebchat();

telefoneParam = metadataWebchat.browser.queryParams["telefone"];

Na primeira linha, a função getMetadataWebchat() é utilizada para capturar os metadados da sessão do Webchat, armazenando o resultado na constante metadataWebchat. Na segunda linha, o valor associado à chave "telefone" é acessado a partir de metadataWebchat.browser.queryParams e armazenado na constante telefoneParam.

Obtendo informações pelo nome:

As funções abaixo realizam chamadas assíncronas para buscar informações específicas dentro do objeto contactCenter, presente no objeto principal sdk.

Em todos os casos, o parâmetro passado é uma string que representa o nome da entidade que se deseja localizar.

• Obtém o Departamento pelo nome:

await sdk.contactCenter.getDepartmentByName(nomeDepartamento)

• Obtém o Grupo de Atendimento pelo nome:

await sdk.contactCenter.getAttendanceGroupByName(nomeGrupo)

• Obtém o Grupo de Especialização pelo nome:

await sdk.contactCenter.getGroupSpecializationByName(nomeEspecialidade)

• Obtém a Subespecialização pelo nome:

await sdk.contactCenter.getSubSpecializationByName(nomeSubEspecialidade)

• Obtém a Área pelo nome:

await sdk.contactCenter.getAreaByName(nomeArea)

• Obtém a Subárea pelo nome:

await sdk.contactCenter.getSubAreaByName(nomeSubArea)

Em todos os métodos, o await indica que a execução do código aguardará o retorno da chamada assíncrona antes de prosseguir. O retorno esperado é um objeto contendo as informações da entidade localizada.

Definindo Informações do Atendimento

As funções abaixo são utilizadas para definir os identificadores (ID) das entidades relacionadas a um atendimento dentro do objeto contactCenter, presente no objeto principal sdk. Cada função recebe um parâmetro que representa o ID da entidade que será associada ao atendimento.

• Define o departamento do atendimento:

await sdk.contactCenter.setDepartmentID(departmentoID)

• Define o grupo de atendimento:

await sdk.contactCenter.setAttendanceGroupID(grupoAtendimentoID)

• Define a especialização do grupo de atendimento:

await sdk.contactCenter.setAttendanceGroupSpecializationID(grupoEspecializacaoID)

• Define a subespecialização do atendimento:

await sdk.contactCenter.setSubspecializationID(subEspecialidadeID)

• Define a área do atendimento:

await sdk.contactCenter.setAreaID(areaID)

• Define a subárea do atendimento:

await sdk.contactCenter.setSubareaID(subAreaID)

Todas as funções utilizam o await para aguardar a execução assíncrona da chamada. Essas definições são usadas para categorizar e direcionar corretamente o atendimento dentro da estrutura do Contact Center.;

ChatBot

Adicionando Informações Adicionais:

await sdk.chatbot.addInfo(key, value)

A função addInfo(key, value) adiciona informações personalizadas à sessão do chatbot. O parâmetro key representa a chave identificadora da informação, e value o valor associado a essa chave. A chamada é feita de forma assíncrona, aguardando a execução com o uso de await.

Marketing

Obtendo informações (metadatas) das notificações avulsas e campanhas do WhatsApp:

As funções abaixo são utilizadas para recuperar dados adicionais (metadados) relacionados a campanhas e notificações do WhatsApp, acessando o objeto mkt dentro do sdk. Ambas executam chamadas assíncronas, aguardando o retorno com o uso de await.

await sdk.mkt.getWhatsappNotificationMetadatas()

Retorna os metadados das notificações avulsas enviadas pelo WhatsApp.

wait sdk.mkt.getWhatsappMktCampaignTargetAudienceMetadatas()

Retorna os metadados do público-alvo de uma campanha de marketing no WhatsApp.

Essas funções permitem acessar informações adicionais da sessão ou campanha ativa, úteis para monitoramento e análise de desempenho das comunicações via WhatsApp.