Operator API

dica

A Operator API é uma API REST que pode ser usada para integrar a plataforma de engajamento do cliente com o Tovie DialogStudio.

Você pode usar a Operator API para conectar qualquer plataforma de engajamento do cliente ao chatbot criado no Tovie DialogStudio. Quando a plataforma de engajamento do cliente estiver integrada com o Tovie DialogStudio, os dados recebidos pelo chatbot durante a conversa com o cliente são enviados para o aplicativo.

Você pode usar métodos API para:

• enviar uma mensagem ou um link de arquivo ao agente;
• escolher um grupo de agentes para processar solicitações;
• transmitir informações adicionais do cliente ao agente;
• inscrever-se em notificações sobre:
  • novas mensagens;
  • entrega de mensagens do cliente;
  • mensagens fechadas pelo agente.

Métodos API

Para a integração da Operator API, você precisará criar um servidor web que seja compatível com os seguintes métodos:

• POST {apiUrl}/setWebhook
• POST {apiUrl}/sendText
• POST {apiUrl}/sendFile
• POST {apiUrl}/closeChat
• POST {apiUrl}/selectDestination
• GET {apiUrl}/getDestinations

cuidado

Todas as solicitações da Operator API incluem {apiUrl} — o URL completo do servidor web para o qual você vai enviar solicitações.

POST /setWebhook

O método define o webhook para o qual os eventos serão encaminhados para serem processados por Tovie DialogStudio. Por exemplo, o envio de uma mensagem processada pelo agente ou o fechamento da chat.

Solicitação

POST {apiUrl}/setWebhook

Corpo da solicitação

{
  "url": "http://{host_name}/chatadapter/chatapi/webhook/operatorapi/{apiKey}",
}

Parâmetros de solicitação

Parâmetro	Tipo	Descrição
apiUrl	string	URL da API para o qual as solicitações da Operator API serão encaminhadas.
url	string	O webhook definido pelo método setWebhook. Ele será utilizado para aceitar eventos encaminhados para o Tovie DialogStudio.
apiKey	string	ID do canal.

POST /sendText

O cliente enviou uma mensagem para o chat com o agente.

Solicitação

POST {apiUrl}/sendText

Corpo da solicitação

{
   "userId": "<userId>",
   "text": "texto"
}

Parâmetros de solicitação

Parâmetro	Tipo	Obrigatório	Descrição
userId	string	Sim	ID do cliente.
text	string	Sim	Mensagem de texto enviada pelo cliente.

POST /sendFile

O cliente enviou um arquivo para o chat com o agente.

Solicitação

POST {apiUrl}/sendFile

Corpo da solicitação

{
  "userId": "<userId>",
  "url": "http://someUrl",
  "fileName": "example",
  "size": 1
}

Parâmetros de solicitação

Parâmetro	Tipo	Obrigatório	Descrição
userId	string	Sim	ID do cliente.
url	string	Sim	Link de download do arquivo.
fileName	string	Não	Nome do arquivo a ser baixado.
size	integer	Não	Tamanho do arquivo em bytes.

POST /closeChat

O cliente fechou o chat com o agente.

Solicitação

POST {apiUrl}/closeChat

Corpo da solicitação

{
  "userId": "<userId>",
  "text": "O usuário fechou o diálogo"
}

Parâmetros de solicitação

Parâmetro	Tipo	Obrigatório	Descrição
userId	string	Sim	ID do cliente.
text	string	Sim	Mensagem de texto enviada quando o chat foi fechado.

POST /selectDestination

O método cria uma sessão entre o cliente do chatbot e o agente selecionado.

Solicitação

POST {apiUrl}/selectDestination

Corpo da solicitação

{
  "userId": "<userId>",
  "destinationId": "54321",
  "userName": "firstName lastName",
  "attributes": {
    "key1": "value1",
    "key2": "value2"
  },
  "hiddenAttributes": {
    "key1": "value1",
    "key2": "value2"
  },
   "customData": {}
}

Parâmetros de solicitação

Parâmetro	Tipo	Obrigatório	Descrição
userId	string	Sim	ID de cliente atribuído na plataforma do Tovie DialogStudio.
destinationId	string	Sim	ID de agente atribuído pelo aplicativo do agente.
userName	string	Não	O nome do cliente. Se nenhum valor for transferido, o agente verá {channel} {userId} como o nome.
attributes	string	Não	Campo de pré-chat. Aceita JSON no formulário {"key": "value"}. Os parâmetros serão transferidos para o agente como informações adicionais do cliente.
hiddenAttributes	string	Não	Campo de pré-chat que não será enviado ao agente. O formato é similar a attributes.
customData	string	Não	Dados adicionais a serem alterados para o agente.

GET /getDestinations

O método disponibiliza grupos de agentes para os quais encaminhar eventos.

Solicitação

GET {apiUrl}/getDestinations

Resposta

{
  "destinations": [
    {
      "destinationId": "1",
      "name": "Grupo de agentes 1",
      "hasOnline": true
    },
    {
      "destinationId": "2",
      "name": "Grupo de agentes 2",
      "hasOnline": false
    }
  ]
}

Formato de resposta

Parâmetro	Tipo	Descrição
destinationId	string	ID do grupo de agentes.
name	string	Nome do grupo de agentes.
hasOnline	boolean	Disponibilidade do grupo de agentes para encaminhamento de eventos.

Transferindo eventos para Tovie DialogStudio

dica

Um webhook é definido para uma solicitação POST {apiUrl}/setWebhook para onde os eventos de agentes devem ser encaminhados.

Formato do webhook

http://{host_name}/chatadapter/chatapi/webhook/operatorapi/{apiKey}

Solicitação

POST ​/chatapi​/webhook​/operatorapi​/{apiKey}

Corpo da solicitação

O corpo da solicitação contém os dados necessários para criar ou modificar um objeto. Os dados devem estar no formato JSON.

Você pode ver os eventos que podem ser enviados, sua estrutura e os campos abaixo.

Mostrar os detalhes

TextMessage: {
    "id": "id",
    "userId": "54321",
    "type": "TextMessage",
    "text": "text",
    "employee": {
        "employeeId": "id",
        "firstName": "first name",
        "lastName": "last name",
        "avatarUrl": "http://someUrl",
    },
},

FileMessage {
    "id": "id",
    "userId": "54321",
    "type": "FileMessage",
    "url": "http://someUrl",
    "employee": {
        "employeeId": "id",
        "firstName": "first name",
        "lastName": "last name",
        "avatarUrl": "http://someUrl",
    },
    "name": "example",
    "size": "2",
    "comment": "file",
},

Closed {
    "id": "id",
    "userId": "54321",
    "type": "Closed",
    "employee": {
        "employeeId": "id",
        "firstName": "first name",
        "lastName": "last name",
        "avatarUrl": "http://someUrl",
    },
},

SelectDestination {
    "id": "id",
    "userId": "54321",
    "type": "SelectDestination",
    "destination": {
        "destinationId": "id",
        "name": "name",
        "hasOnline": "true",
    },
}

Tipos de evento

Evento	Descrição
TextMessage	Mensagem de texto do agente.
FileMessage	Arquivo anexado do agente.
Closed	Mensagem fechada pelo agente.
SelectDestination	Destino de encaminhamento selecionado.

Parâmetros de solicitação

Parâmetro	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador da mensagem.
userId	string	Sim	ID do cliente.
type	string	Sim	Tipo de evento.
Funcionário
employeeId	string	Sim	ID do cliente.
firstName	string	Sim	Nome do agente.
lastName	string	Sim	Sobrenome do agente.
avatarUrl	string	Sim	Link para o avatar do agente.
TextMessage
text	string	Sim	Mensagem de texto enviada pelo agente.
FileMessage
url	string	Sim	Link de download do arquivo.
name	string	Sim	Nome do arquivo a ser baixado.
size	integer	Sim	Tamanho do arquivo em bytes.
comment	string	Sim	Comentar no arquivo que está sendo enviado.
SelectDestination
destinationId	string	Sim	ID do grupo de agentes.
name	string	Sim	Nome do grupo de agentes.
hasOnline	boolean	Sim	Disponibilidade do grupo de agentes para encaminhamento de eventos.

Conectar o canal

Entre no Tovie DialogStudio e acesse seu projeto. Clique em Canais > Transferência para o agente no painel de controle. Selecione o canal para a conexão da Operator API.

Preencha os seguintes campos:

• Nome do canal — especifique o nome do canal.
• API URL — o URL para o qual as solicitações da Operator API serão encaminhadas.

Quando você usar o canal da Operator API, pode transferir o diálogo não apenas para um agente em particular, mas, também para o grupo de agentes. Nesse caso, o diálogo será atribuído a um dos agentes do grupo especificado.

Para adicionar o grupo de agentes, pressione o botão Adicionar grupo e preencha os seguintes campos:

• Nome do canal — especifique o nome do grupo de agentes.
• Descrição — adicione a descrição do grupo de agentes.
• IDs — na lista suspensa, escolha o identificador do grupo de agentes que existe na plataforma de chat on-line que você usa.

Você pode adicionar mais grupos de agentes da mesma maneira.

Para excluir o grupo de agentes, use o botão no canto superior direito do grupo adicionado.

Clique em Conectar.

Transferência para o agente

Para mudar o diálogo do bot para o agente, é necessário adicionar o bloco Transferência para o agente ao script. Os casos em que o bot não sabe a resposta certa ainda podem levar a esse bloco.

Para que você possa adicionar apenas uma plataforma de engajamento do cliente, quando adicionar o bloco Transferência para o agente, o canal da Operator API será automaticamente adicionado a esse bloco. Você só precisará especificar algumas opções de bloco.