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.

Métodos API​

POST /setWebhook​

POST /sendText​

POST /sendFile​

POST /closeChat​

POST /selectDestination​

GET /getDestinations​

Transferindo eventos para Tovie DialogStudio​

Tipos de evento​

Parâmetros de solicitação​

Conectar o canal​

Transferência para o agente​

Métodos API

POST /setWebhook

POST /sendText

POST /sendFile

POST /closeChat

POST /selectDestination

GET /getDestinations

Transferindo eventos para Tovie DialogStudio

Tipos de evento

Parâmetros de solicitação

Conectar o canal

Transferência para o agente