Introdução

A API Remota do Bot foi desenvolvida para que o cliente possa configurar a árvore de decisões do Bot conforme desejar, para que o Bot dê informações para o usuário através de perguntas e respostas e realizar encaminhamentos de mensagens.

Implementação

A API remota se comporta como descrito abaixo:

Cliente entra em contato por qualquer canal que esteja integrado a loja; (Cliente envia mensagem);
Bot recebe a mensagem, entra no primeiro estado e envia a mensagem com a estrutura de escolhas para o cliente;
Cliente responde com uma resposta válida;
Bot avalia a resposta, sendo da opção REMOTE_API_HANDLER, este efetuará uma chamada para uma API externa aguardando os formatos descritos neste documento;
Bot avalia a resposta da API, se estiver correta efetua:

a. Caso o handlerType retornado seja do tipo "SEND_TO_TEAM", o Bot irá executar a função de redirecionar o atendimento para o time;
b. Caso o handlerType retornado seja do tipo "BOT_STATE_CHANGE_HANDLER", será enviada nova estrutura decisória para o cliente escolher.
c. Caso ocorra algum problema na integração (código de erro HTTP, formato da mensagem inválida, timeout, etc), o atendimento será direcionado para o time configurado na opção "fallbackTeam".

1 - Estrutura que será enviada para a API externa

// Model (typescript format)
interface Chat {
  objectId: string; //id do canal (chat)
  customerId?: string //IDENTIFICADOR_UNICO_DO_CLIENTE
  phone?: string //NUMERO_DO_TELEFONE
  name?: string //"NOME_DO_CLIENTE(SE HOUVER)
  email?: string //"EMAIL_DO_CLIENTE(SE HOUVER),
  platform: string; //WHATSAPP, FBMESSENGER, WEBCHAT or WAB
  platformId?: string //No caso do WAB/WHATSAPP é o número chamado
}

interface BotRequest {
  chat: Chat
  handlerId: string //"NAME_OF_STATE
  customerSupportRequestId: string //"IDENTIFICADOR_ÚNICO_DO_ATENDIMENTO"
}

//Example
{
  "chat": {
    "objectId": "IDENTIFICADOR_DA_CONVERSA",
    "customerId": "IDENTIFICADOR_UNICO_DO_CLIENTE(SE JÁ EXISTIR)",
    "phone": "NUMERO_DO_TELEFONE(SE HOUVER)",
    "name": "NOME_DO_CLIENTE(SE HOUVER)",
    "email": "EMAIL_DO_CLIENTE(SE HOUVER)",
    "platform": "WHATSAPP",
    "platformId": "5541999999999"
  },
  "handlerId": "ID_ESTADO_SELECIONADO",
  "botStateId": "ID_ESTADO_ATUAL",
  "objectId": "IDENTIFICADOR_ÚNICO_DO_ATENDIMENTO"
}

2 - Estrutra retornada da API externa com estado SEND_TO_TEAM

interface BotState {
  title?: string;
  index?: number;
  toState?: ToBotState;
  handlerType: 'BOT_STATE_CHANGE_HANDLER' |'SEND_TO_TEAM';
  handlerConfig?: {
    teamId: string;
    routingMessage: string;
  }
}
//Example
{
  "handlerType": "SEND_TO_TEAM",
  "handlerConfig": {
    "teamId": "ID_DO_TIME",
    "routingMessage": "Você está sendo redirecionado para o time XYZ"
  }
}

3 - Estrutra retornada da API externa com estado BOT_STATE_CHANGE_HANDLER

interface BotState {
  handlerType: 'BOT_STATE_CHANGE_HANDLER' |'SEND_TO_TEAM' |'REMOTE_API_HANDLER';
  title?: string; // descritivo da opção apresentada para o cliente
  index?: number;// índice da opção apresentada para o cliente
  toState?: {//utilizado caso seja um agregador de opções
    title: string; // titulo do estado
    to: BotState[]; // opções do estado
  },
  handlerConfig?: { // para as opções SEND_TO_TEAM e REMOTE_API_HANDLER
    teamId?: string; // id do time de destino
    routingMessage?: string; // mensagem de roteamento
    handlerId?: string; // opção selecionada pelo cliente
    botStateId?: string; //estado atual do bot
    url?: string; //URL de destino
    fallbackTeam?: string;//id do time caso ocorra algum problema na integração
  }
}
//Example
{
  "handlerType": "BOT_STATE_CHANGE_HANDLER",
  "toState": {
    "title": "Para melhor atendê-lo, digite o número do setor em que deseja falar:",
    "to": [
      {
        "title": "Cursos",
        "handlerType": "SEND_TO_TEAM",
        "index": 1,
        "handlerConfig": {
          "teamId": "ID_DO_TIME",
          "routingMessage": "ROTEAMENTO DE NOVAS MENSAGENS\n\nVocê está sendo redirecionado para o setor Cursos.\n\n⏰ O nosso horário de atendimento neste canal é de segunda a sexta-feira das *08h00 às 17h00* horas ⏰"
        }
      },
      {
        "title": "Cursos Online",
        "handlerType": "REMOTE_API_HANDLER",
        "index": 2,
        "handlerConfig": {
          "botStateId": "QUESTAO_INICIAL",
          "handlerId": "ONLINE_COURSES",
          "url": "https://my.domain.com/url/to/service",
          "fallbackTeam": "ID_DO_TIME" //caso ocorra erro na integração
        }
      }
    ]
  }
}

Integração do BOT

API criada para testes (apenas para referência):

1 - Configuração inicial do Bot:

{
  //configurações internas omitidas
  "greetingsMessage": "Bem-vindo a Loja",
  "defaultErrorMessage": "Ops, não entendi sua mensagem",
  "initialState": {
    "title": "nivel default",
    "handlerType": "REMOTE_API_HANDLER",
    "handlerConfig": {
      "botStateId": "FIRST_LEVEL",
      "url": "http://localhost:5000/myapi",
      "handlerId": "QUESTION_TREE",
      "fallbackTeam": "DJY9z2fXQl"
    }
  }
}

2 - Mensagem enviada para a API Remota:

{
  customerSupportRequestId: "RTas5Ht7D",
  handlerId: "QUESTION_TREE",
  botStateId: "FIRST_LEVEL",
  chat: {
      objectId: "Tg0G6dfG",
      name: "Marcelo",
      phone: "5541999999999",
      customerId: "Hk5g4cAq5",
      email: "email@email.com",
      platform: "WAB",
      platformId: "5541988888888",
  }
}

3 - Retorno da primeira chamada do Bot:

{
  botStateId: "QUESTION_TREE",
  handlerType: "BOT_STATE_CHANGE_HANDLER",
  index: 0,
  toState: {
    title: "Aqui estão as opções",
    to: [
      {
        handlerType: "REMOTE_API_HANDLER",
        title: "First",
        index: 1,
        handlerConfig: {
          botStateId: "QUESTION_TREE",
          handlerId: "MY_FIRST_OPTION",
          url: "http://localhost:5000/myapi",
          fallbackTeam: "DJY9z2fXQl"
        }
      },
      {
        handlerType: "REMOTE_API_HANDLER",
        title: "Second",
        index: 2,
        handlerConfig: {
          botStateId: "QUESTION_TREE",
          handlerId: "MY_SECOND_OPTION",
          url: "http://localhost:5000/myapi",
          fallbackTeam: "DJY9z2fXQl"
        }
      }
    ]
  }
}

Julgando que o cliente tenha digitado "1" como opção:
4 - Retorno da API remota caso seja selecionada a primeira opção no Bot:

{
  handlerType: "SEND_TO_TEAM",
  botStateId: "first",
  handlerConfig: {
    teamId: "4sOTCjq5HF",
    routingMessage: "Você está sendo redirecionado para o time CRM"
  }
}

Integrando com a API OmniChat e Webhooks

Além de criar seu próprio bot customizado, integrado aos seus sistemas internos, é possível carregar informações da OmnChat utilizando a API OmniChat e nossos Webhooks.

API OmniChat

É possível carregar várias informações da OmniChat para seus sistemas internos, como dados de ordens, times, usuários, chats, etc. Para verificar o que é possível fazer com nossa API, entre na documentação https://api-docs.omni.chat/.

Webhooks

Com nossos webhooks é possível receber notificações de alterações de objetos da OmniChat em seu sistema para efetuar rotinas diversas. Para mais detalhes sobre a utilização de Webhooks, veja a documentação http://help.omni.chat/pt-BR/articles/3102792-webhooks-omnichat