Como configurar uma conexão WebSocket?

Os WebSockets estabelecem uma conexão contínua entre o cliente e o servidor, permitindo a comunicação bidirecional. O PortoMicro utiliza essa conexão para fornecer atualizações em tempo real sobre eventos da plataforma. Para se conectar ao WebSocket do PortoMicro, basta fornecer um token e seguir as instruções de configuração descritas neste guia.

Observação : Este recurso é experimental e a documentação pode ser alterada a cada versão. Além disso, a compatibilidade com versões anteriores não pode ser garantida, portanto, é importante certificar-se de que está usando a versão mais recente da implementação.

Por que devo usar uma conexão WebSocket?

Uma conexão WebSocket permite atualizações de dados em tempo real, sendo ideal para clientes como o SDK do PortoMicro para Android ou iOS. Isso ajuda a atualizar o painel sem a necessidade de recarregar a página. Consequentemente, pode melhorar a experiência do usuário e aumentar a produtividade do agente.

Como configurar uma conexão WebSocket com o PortoMicro?

Para configurar uma conexão WebSocket com o PortoMicro, você precisa iniciar uma conexão com o token de autenticação PubSub fornecido pelo PortoMicro. A URL para a conexão é wss://<your-installation-url>/cable. Se você estiver usando o PortoMicro Cloud, pode usar **wss://app.chatwoot.com/cable**como URL.

Um token PubSub é um token usado para autenticar um cliente ao se conectar a um serviço PubSub (publicação e assinatura). O cliente deve apresentar esse token ao serviço para estabelecer uma conexão e começar a publicar ou assinar mensagens.

Existem dois tipos de tokens PubSub disponíveis no PortoMicro, conforme listado abaixo.

Token PubSub do usuário : Este token possui os privilégios de um agente/administrador e receberá todos os eventos listados posteriormente nesta página. Você pode obter o token PubSub chamando a API de Perfil .
Token PubSub de Contato : O PortoMicro gera um token PubSub exclusivo para cada sessão de um contato. Esse token pode ser usado para conectar-se ao WebSocket e receber atualizações em tempo real para a mesma sessão. Quando um contato é criado por meio das APIs públicas, o token **pubsub_token**é incluído na resposta. Esse token concede acesso apenas a eventos relacionados à sessão atual, como conversation.createdupdate conversation.status_changed, message.createdupdate, message.updatedupdate, **conversation_typing_on**update e **conversation_typing_off** update presence.update.

Consulte as APIs do cliente para criar integrações em tempo real voltadas para o cliente usando o PortoMicro.

Observação : Este token pode ser alterado periodicamente dependendo do seu tipo de instalação. Certifique-se de estar usando o token mais recente.

Como conectar-se ao WebSocket do PortoMicro?

Para se conectar ao WebSocket do PortoMicro, use o comando **subscribe**e inclua seu pubSubToken, **accountId**e userId(se estiver usando um token de usuário) na solicitação de conexão. Aqui está um exemplo de como você pode se conectar ao PortoMicro.

// Add a helper method to convert JSON to a string
const stringify = (payload = {}) => JSON.stringify(payload);

const pubSubToken = "<contact/user-pub-sub-token>";
const accountId = "<your-account-id-in-integer>";
const userId = "<user-id-in-integer-if-using-user-token>";
const connection = new WebSocket(
  "wss://app.chatwoot.com/cable"
);

connection.send(
  stringify({
    command: "subscribe",
    identifier: stringify({
      channel: "RoomChannel",
      pubsub_token: pubSubToken,
      account_id: accountId,
      user_id: userId,
    }),
  })
);

// The expected string in connection.send is of the format:
// {"command":"subscribe","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\",\\"account_id\\": account_id_integer,\\"user_id\\":user_id_integer }"}

Publicando presença no servidor WebSocket

Para manter o status dos seus usuários online no PortoMicro, você pode enviar um evento de atualização de presença para o PortoMicro a cada 30 segundos. Essa ação manterá o status do agente/contato online.

Como atualizar a presença de um agente/administrador?

Para atualizar a presença de um agente ou administrador, envie a seguinte carga útil para o servidor:

const userPayload = stringify({
  command: "message",
  identifier: stringify({
    channel: "RoomChannel",
    pubsub_token: "<user-pubsub-token>",
    account_id: accountId,
    user_id: userId,
  }),
  data: stringify({ action: "update_presence" }),
});

connection.send(userPayload);
// The expected string in connection.send is of the format:
// {"command":"message","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\",\\"account_id\\": account_id_integer,\\"user_id\\":user_id_integer ","data":"{\\"action\\":\\"update_presence\\"}"}

Como atualizar a presença de um contato?

Para atualizar a presença de um contato, envie a seguinte carga útil para o servidor:

const agentPayload = stringify({
  command: "message",
  identifier: stringify({
    channel: "RoomChannel",
    pubsub_token: "<user-pubsub-token>",
  }),
  data: stringify({ action: "update_presence" }),
});

connection.send(agentPayload);
// The expected string in connection.send is of the format:
// {"command":"message","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\","data":"{\\"action\\":\\"update_presence\\"}"}

Carga útil do WebSocket

Objetos

Um evento pode conter qualquer um dos seguintes objetos como carga útil. Os diferentes tipos de objetos suportados no PortoMicro são os seguintes.

Conversa

A seguinte carga útil será retornada para uma conversa.

{
  "additional_attributes": {
    "browser": {
      "device_name": "string",
      "browser_name": "string",
      "platform_name": "string",
      "browser_version": "string",
      "platform_version": "string"
    },
    "referer": "string",
    "initiated_at": {
      "timestamp": "iso-datetime"
    }
  },
  "can_reply": "boolean",
  "channel": "string",
  "id": "integer",
  "inbox_id": "integer",
  "contact_inbox": {
    "id": "integer",
    "contact_id": "integer",
    "inbox_id": "integer",
    "source_id": "string",
    "created_at": "datetime",
    "updated_at": "datetime",
    "hmac_verified": "boolean"
  },
  "messages": ["Array of message objects"],
  "meta": {
    "sender": {
      // Contact Object
    },
    "assignee": {
      // User Object
    }
  },
  "status": "string",
  "unread_count": "integer",
  "agent_last_seen_at": "unix-timestamp",
  "contact_last_seen_at": "unix-timestamp",
  "timestamp": "unix-timestamp",
  "account_id": "integer"
}

Contato

A seguinte carga útil será retornada para um contato.

{
  "additional_attributes": "object",
  "custom_attributes": "object",
  "email": "string",
  "id": "integer",
  "identifier": "string or null",
  "name": "string",
  "phone_number": "string or null",
  "thumbnail": "string"
}

Usuário

A seguinte carga útil será retornada para um agente/administrador.

{
  "id": "integer",
  "name": "string",
  "available_name": "string",
  "avatar_url": "string",
  "availability_status": "string",
  "thumbnail": "string"
}

Mensagem

A seguinte carga útil será retornada para uma mensagem.

{
  "id": "integer",
  "content": "string",
  "account_id": "integer",
  "inbox_id": "integer",
  "message_type": "integer",
  "created_at": "unix-timestamp",
  "updated_at": "datetime",
  "private": "boolean",
  "status": "string",
  "source_id": "string / null",
  "content_type": "string",
  "content_attributes": "object",
  "sender_type": "string",
  "sender_id": "integer",
  "external_source_ids": "object",
  "sender": {
    "type": "string - contact/user"
    // User or Contact Object
  }
}

Notificação

A seguinte carga útil será retornada para uma notificação.

{
  "id": "integer",
  "notification_type": "string",
  "primary_actor_type": "string",
  "primary_actor_id": "integer",
  "primary_actor": {
    "can_reply": "boolean",
    "channel": "string",
    "id": "integer",
    "inbox_id": "integer",
    "meta": {
      "assignee": {
        "id": "integer",
        "name": "string",
        "available_name": "string",
        "avatar_url": "string",
        "type": "user",
        "availability_status": "string",
        "thumbnail": "string"
      },
      "hmac_verified": "boolean"
    },
    "agent_last_seen_at": "unix-timestamp",
    "contact_last_seen_at": "unix-timestamp",
    "timestamp": "unix-timestamp",
  },
  "read_at": "unix-timestamp",
  "secondary_actor": "object/null",
  "created_at":"unix-timestamp",
  "account_id": "integer",
  "push_message_title": "string"
}

Identificador

Cada evento terá um identifier atributo no seguinte formato.

{
  "identifier": "{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"token\\",\\"account_id\\":id,\\"user_id\\":user_id}"
}

Mensagem

Cada evento incluirá um message atributo que retornará o nome do evento, bem como os dados associados a ele. Para ver a lista de eventos, consulte a documentação abaixo.

Tipos de Eventos

conversa.criada

Este evento é acionado quando uma nova conversa é iniciada. Se você estiver inscrito no token PubSub do contato, este evento incluirá apenas dados relacionados à sessão específica associada ao token PubSub.

Disponível para : agente/administrador, contato

{
  "message": {
    "event": "conversation.created",
    "data": {
      // Conversation object will be available here
    }
  }
}

conversa.ler

Este evento é acionado e enviado aos agentes/administradores que têm acesso à caixa de entrada quando um contato lê uma mensagem.

Disponível para : agente/administrador

{
  "message": {
    "event": "conversation.read",
    "data": {
      // Conversation object will be available here
    }
  }
}

mensagem.criada

Este evento é acionado e enviado aos agentes, administradores e contatos quando uma nova mensagem é criada em uma conversa à qual eles têm acesso.

Disponível para : agente/administrador, contato

{
  "message": {
    "event": "message.created",
    "data": {
      // Message object will be available here
    }
  }
}

mensagem.atualizada

Este evento é acionado e enviado aos agentes, administradores e contatos quando uma mensagem é atualizada em uma conversa à qual eles têm acesso.

Disponível para : agente/administrador, contato

{
  "message": {
    "event": "message.updated",
    "data": {
      // Message object will be available here
    }
  }
}

conversa.status_alterado

Este evento é enviado aos agentes, administradores e contatos quando o status de uma conversa é atualizado.

Disponível para : agente/administrador, contato

{
  "message": {
    "event": "conversation.status_changed",
    "data": {
      // Conversation object will be available here
    }
  }
}

conversa.digitando_ligado

Este evento é enviado aos agentes, administradores e contatos quando um contato ou um agente começa a digitar uma resposta.

Disponível para : agente/administrador, contato

{
  "message": {
    "event": "conversation.typing_on",
    "data": {
      "conversation": {
        // Conversation object will be available here
      },
      "user": {
        // Contact / Agent,Admin User object will be available here.
      },
      "is_private": "boolean", // Shows whether the agent is typing a private note or not.
      "account_id": "integer"
    }
  }
}

conversa.digitando_desligado

Este evento é enviado aos agentes, administradores e contatos quando um contato ou um agente termina de digitar uma resposta.

Disponível para : agente/administrador, contato

{
  "message": {
    "event": "conversation.typing_off",
    "data": {
      "conversation": {
        // Conversation object will be available here
      },
      "user": {
        // Contact / User object will be available here.
      },
      "account_id": "integer"
    }
  }
}

atribuído.alterado

Este evento é enviado aos agentes/administradores com acesso a uma caixa de entrada quando o agente atribuído é alterado.

Disponível para : agente/administrador

{
  "message": {
    "event": "assignee.changed",
    "data": {
      // Conversation object will be available here
    }
  }
}

equipe.mudou

Este evento é enviado aos agentes/administradores com acesso a uma caixa de entrada quando a equipe atribuída é alterada.

Disponível para : agente/administrador

{
  "message": {
    "event": "team.changed",
    "data": {
      // Conversation object will be available here
    }
  }
}

conversa.contato_alterado

Este evento é enviado aos agentes/administradores quando dois contatos são mesclados e todas as suas conversas são consolidadas em um único contato.

Disponível para : agente/administrador

{
  "message": {
    "event": "conversation.contact_changed",
    "data": {
      // Conversation object will be available here
    }
  }
}

contato.criado

Este evento é enviado aos agentes/administradores quando um contato é criado.

Disponível para : agente/administrador

{
  "message": {
    "event": "contact.created",
    "data": {
      // Contact object will be available here
    }
  }
}

contato.atualizado

Este evento é enviado aos agentes/administradores quando um contato é atualizado.

Disponível para : agente/administrador

{
  "message": {
    "event": "contact.updated",
    "data": {
      // Contact object will be available here
    }
  }
}

atualização de presença

Disponível tanto para o agente quanto para o contato, este evento fornece atualizações em tempo real sobre o status de disponibilidade dos usuários no sistema. O evento enviado aos contatos não incluirá informações sobre o status de disponibilidade de outros contatos.

Disponível para : agente/administrador

{
  "message": {
    "event": "presence.update",
    "data": {
      "account_id": "integer",
      "users": {
        "user-id": "string"
      },
      "contacts": {
        "contact-id": "string"
      }
    }
  }
}

notificação_criada

Este evento é enviado aos agentes/administradores quando uma notificação é criada.

Disponível para : agente/administrador