Pular para o conteúdo principal

3 postagens marcadas com "RocketChat"

Ver todas os Marcadores

· Leitura de 3 minutos
Anderson Marlon

Este guia aborda o processo detalhado de instalação e configuração do Rocketchat em uma máquina virtual Ubuntu na plataforma Microsoft Azure - pode funcionar em outras plataformas, mas não foi testado como Google Cloud Plataform, Heroku e outros - com foco em habilitar funcionalidades avançadas como integração com um frame externo e configurações de omnichannel.

Instalação da Máquina Virtual no Azure

  1. Acesse o portal Azure: https://portal.azure.com/
  2. Crie uma nova máquina virtual Ubuntu
  3. Utilize uma senha para acessar a máquina via SSH
  4. Configure o DNS padrão para a máquina virtual

Instalação e Configuração do Rocketchat

  1. Instale o Rocketchat através do seguinte comando:
sudo snap install rocketchat-server --channel=5.x/stable
  1. Configure o portal com o endereço da sua máquina virtual:
sudo snap set rocketchat-server siteurl=https://SEU_ENDERECO.azure.com
  1. Reinicie o serviço do Rocketchat:
sudo systemctl enable --now snap.rocketchat-server.rocketchat-caddy
sudo snap restart rocketchat-server
  1. Acesse o portal configurado e realize as configurações iniciais.

Configuração do Omnichannel

  1. Acesse as configurações do Rocketchat no painel de administração.
  2. Em "Admin / Config / Omnichannel", habilite o "External Frame" e configure a URL do frame externo.
  3. Configure as opções de "Livechat":
  • Título do Livechat: Defina um nome descritivo.
  • Roteamento: Atribua novas conversas para um agente bot.
  1. Em "Admin / Config / Accounts", desative a autenticação de dois fatores (TOTP).
  2. Em "Admin / Permissões", desabilite o fechamento de salas omnichannel para os respectivos cargos.
  3. Opcional: Em "Users", adicione um usuário bot com email verificado e defina o cargo dele.

Integração com Frame Externo

  1. Em "Omnichannel / Webhooks", configure a URL do webhook para receber informações do frame externo.
  2. Defina um token secreto para o webhook.
  3. Selecione todas as opções para enviar solicitações ao webhook.

Configuração de Agentes e Departamentos

  1. Em "Omnichannel / Agents", adicione um usuário local (admin) e o usuário bot.
  2. Defina o status do bot como disponível.
  3. Em "Omnichannel / Managers", adicione um usuário local (admin).
  4. Em "Omnichannel / Departments", crie os departamentos desejados (por exemplo: HUMAN_DEPARTMENT e BOT_DEPARTMENT).

Configurações Adicionais

  1. Personalize o CSS customizado conforme necessário, por exemplo:
.rcx-sidebar-footer footer {
height: 6rem !important;
text-align: center;
}

Considerações Finais

Este guia abordou passo a passo a instalação e configuração do Rocketchat no Azure, mas tem possibilidade de funcionar em outros ambientes como Google Cloud Plataform, Heroku e outros. Assim habilitando recursos avançados como integração com um frame externo e configurações de omnichannel. Certifique-se de verificar a documentação oficial do Rocketchat para obter informações atualizadas e detalhadas sobre cada configuração, lembrando que estamos usando a versão 5.x que evita certas limitações de recursos como o funcionamento do Frame Externo, por exemplo.

· Leitura de 3 minutos
Anderson Marlon

Ao contrário da publicação anterior, hehe, essa é uma publicação original e é de minha autorial.

O Rocketchat é uma plataforma de comunicação poderosa que oferece uma variedade de recursos e funcionalidades para facilitar a comunicação e colaboração entre equipes. Se você está começando ou precisa de ajuda para se orientar nas funcionalidades, este guia detalhado irá ajudá-lo a dominar os comandos essenciais.

Lembrando que todos eles são comandos via curl, que podem ser utilizados através do terminal, Postman ou Insomnia. Se você deseja usar através do Node.js, PHP ou qualquer outro tipo de maneira fora desse convencional, consulte a documentação oficial.

Vamos explorar além do básico e ver como tirar o máximo proveito do Rocketchat via API, vale lembrar também que esses são comandos que achei essenciais e já cheguei a utilizar no dia a dia.

Fazendo Login via API

Se você precisa fazer login no Rocketchat via API, o seguinte comando pode ser usado:

curl http://localhost:3000/api/v1/login \
-d "user=SEU_USUÁRIO&password=SUA_SENHA"
Substitua SEU_USUÁRIO pelo seu nome de usuário e SUA_SENHA pela sua senha.

Criando um Visitante via API

Crie um visitante usando a API para interagir com os usuários. Execute o seguinte comando curl:

curl -X POST \
-H "Content-type:application/json" \
http://localhost:3000/api/v1/livechat/visitor \
-d '{
"visitor": {
"name": "Nome do Visitante",
"email": "email@exemplo.com",
"department": "DEPARTAMENTO",
"phone": "55 344433322",
"token": "TOKEN_DO_VISITANTE",
"customFields": []
}
}'

Certifique-se de substituir as informações corretas, como nome, email, departamento e token do visitante.

Criando uma Sala para o Visitante

Crie uma sala para o visitante usando o comando curl:

curl -H "X-Auth-Token: SEU_TOKEN" \
-H "X-User-Id: SEU_ID_DO_USUÁRIO" \
"http://localhost:3000/api/v1/livechat/room?token=TOKEN_DO_VISITANTE"
Substitua SEU_TOKEN, SEU_ID_DO_USUÁRIO e TOKEN_DO_VISITANTE pelas informações corretas.

Enviando Mensagens

Como Agente

Se você é um agente e deseja enviar mensagens, use o seguinte comando curl:

curl -H "X-Auth-Token: SEU_TOKEN" \
-H "X-User-Id: SEU_ID_DO_USUÁRIO" \
-H "Content-type:application/json" \
http://localhost:3000/api/v1/chat.sendMessage \
-d '{"message": { "rid": "ID_DA_SALA", "msg": "Esta é uma mensagem de teste!" }}'

Substitua SEU_TOKEN, SEU_ID_DO_USUÁRIO e ID_DA_SALA pelas informações corretas.

Como Usuário (Visitante)

Para enviar mensagens como um usuário (visitante), use este comando curl:

curl -X POST \
-H "Content-type:application/json" \
http://localhost:3000/api/v1/livechat/message \
-d '{"token": "TOKEN_DO_VISITANTE", "rid": "ID_DA_SALA", "msg": "Mensagem do visitante via API"}'
Substitua TOKEN_DO_VISITANTE e ID_DA_SALA pelas informações corretas.

Transferindo a Conversa para um Agente

Transfira a conversa para um agente específico usando o seguinte comando curl:

curl -X POST \
-H "Content-type:application/json" \
-H "Authorization: Bearer SEU_TOKEN" \
http://localhost:3000/api/v1/livechat/room.transfer \
-d '{
"roomId": "ID_DA_SALA",
"token": "TOKEN_DO_VISITANTE",
"userId": "ID_DO_AGENTE"
}'

Substitua SEU_TOKEN, ID_DA_SALA, TOKEN_DO_VISITANTE e ID_DO_AGENTE pelas informações corretas.

Explorando Mais Recursos

Este guia abordou alguns comandos essenciais do Rocketchat via API, mas esta plataforma oferece uma ampla gama de recursos e possibilidades. Agora que você tem uma base sólida, sinta-se à vontade para explorar outras funcionalidades, como transferência entre departamentos, notificações e muito mais. Lembre-se de consultar a documentação oficial do Rocketchat para obter detalhes completos sobre todas as funcionalidades disponíveis.

Vale lembrar que o Rocketchat é uma plataforma open source e a comunidade anda ajudando em peso!

Com esses comandos em mãos, você estará melhor preparado para dominar o Rocketchat e aproveitar ao máximo essa plataforma poderosa de comunicação e colaboração, isso inclui fazer interações com bot e clientes através do Whatsapp. Espero que essas dicas sejam úteis, já que pra mim será uma mão na roda para projetos futuros.

· Leitura de 11 minutos
Anderson Marlon

Algumas pessoas que me conhece sabe que eu já trabalhei e até os dias de hoje trabalho com Rocketchat, é uma ferramenta fundamental para ter uma ampla comunicação com o cliente, se tratando de ecommerce, ele é simplesmente fantástico. Ele é um app onde poderíamos centralizar contatos vindos de diferentes plataformas de comunicação em um único meio de atendimento. Existem funcionalidades já prontas disponíveis na loja da plataforma, permitindo integrar com o WhatsApp, Telegram ou Twitter. Além disso, é disponibilizado na área administrativa um script nativo personalizado capaz de adicionar ao seu site um frame externo do próprio Rocket para conversação.

Agora, vamos entender melhor como realizar essa integração de forma manual, entendendo os usos das APIs e Webhooks.

Vale lembrar que esse artigo não é de minha autoria, mas do 4Linux Blog, estou apenas compartilhando para ser um atalho até mesmo pra mim.

Entendendo o caso de uso

Imagine que na sua empresa seja disponibilizado um chat (seja via web e/ou aplicativo) para os clientes e você deseja integrá-lo ao Rocket para centralizar os atendimentos em uma única plataforma, que é especializada nesse tipo de situação. Ou até mesmo, você ainda não tem esse chat, mas deseja criá-lo e quer ter o menor custo de implementação.

Tudo isso é simples! Com o Rocket você não vai precisar se preocupar com um servidor complexo, armazenamento de dados, atendimento etc. Você pode apenas criar o frontend para o cliente (ou utilizar o widget fornecido) e um backend simples capaz de realizar as chamadas à API do Rocket e receber chamadas de resposta via Webhook.

Para se comunicar com o Rocket, temos dois meios disponíveis:

  • Via API: Criação de usuários (visitantes), criação de salas, envio de mensagens;
  • Via Webhook: Rockchat enviando informações sobre as salas abertas – Respostas dos atendentes, encerramento de salas, transferências; Pode parecer complicado em um primeiro momento, mas não é! Vamos entender melhor o que será necessário.

Preparando o ambiente

Como o foco aqui é como realizar a integração, não vamos ficar perdendo tempo com instalação do Rocket. Vamos utilizar o Docker para auxiliar com isso.

Criei um docker-compose de exemplo para facilitar a infraestrutura. Você pode visualizar ele aqui:

version: "3.0"

services:
rocketchat:
image: rocketchat/rocket.chat:3.16.2
command: >
bash -c
"for i in `seq 1 30`; do
node main.js &&
s=$$? && break || s=$$?;
echo \"Tried $$i times. Waiting 5 secs...\";
sleep 5;
done; (exit $$s)"
restart: unless-stopped
volumes:
- ./uploads:/app/uploads
environment:
- PORT=3000
- ROOT_URL=http://localhost:3000
- MONGO_URL=mongodb://mongo:27017/rocketchat
- MONGO_OPLOG_URL=mongodb://mongo:27017/local
- ADMIN_USERNAME=rocket
- ADMIN_PASS=PZxs7wsHWEJLP98z
- ADMIN_EMAIL=admin@rocketchat.local
depends_on:
- mongo
ports:
- 3000:3000

mongo:
image: mongo:4.0
restart: unless-stopped
volumes:
- ./data/db:/data/db
- ./data/dump:/dump
command: mongod --smallfiles --oplogSize 128 --replSet rs0 --storageEngine=mmapv1

mongo-init-replica:
image: mongo:4.0
command: >
bash -c
"for i in `seq 1 30`; do
mongo mongo/rocketchat --eval \"
rs.initiate({
_id: 'rs0',
members: [ { _id: 0, host: 'localhost:27017' } ]})\" &&
s=$$? && break || s=$$?;
echo \"Tried $$i times. Waiting 5 secs...\";
sleep 5;
done; (exit $$s)"
depends_on:
- mongo

Ele irá iniciar o ambiente com tudo que precisamos, e já irá criar um usuário administrador (Login rocket e senha PZxs7wsHWEJLP98z). Basta fazer login e realizar a configuração inicial.

Com o Rocket rodando, precisamos realizar uma simples configuração. Por padrão o Omnichannel não vem habilitado, mas é simples ajustar isso!

Basta acessar a Administração, procurar pelo menu Omnichannel e marcar a opção Omnichannel habilitado. Não se esqueça de salvar.

A configuração é simplesmente isso! Agora temos o Rocket prontinho para receber nossa integração.

Acessando a documentação

Nessa página temos detalhes sobre os endpoints disponibilizados, tanto para o Rocket como um todo, quanto especificamente para o Omnichannel. Nesse caso, como iremos trabalhar integrando com o livechat, podemos acessar sua documentação específica.

Há alguns termos que aparecem bastante quando acessamos a documentação, então vamos entendê-los melhor:

Agent – Agentes são os atendentes dos chats. Eles acessaram o Rocket pela sua interface e recebem os chats vindos via Omnichannel.

Visitor – Visitantes são os seus clientes que entraram via Omnichannel. Para que haja o atendimento dentro do Rocket é necessário que esse cliente seja criado como um visitante. Visitantes existem apenas no Omnichannel, não são usuários do Rocket e não podem acessá-lo.

Custom field – Campos personalizados que podem ser adicionados ao registro dos visitantes.

Contact – Contato é basicamente um visitante. Apesar de existir na documentação APIs diferentes referenciando individualmente cada um, eles são o mesmo registro dentro do banco. Há apenas diferença nas suas APIs, tendo mais campos obrigatórios para manipulação.

Room – Sala criada para realizar a conversa entre o agente e o cliente. A sala deve ser encerrada ao final do atendimento e cada novo irá gerar uma nova sala, mesmo que seja o mesmo contato.

Tendo entendido isso, vamos ter um último passo antes de analisar as APIs que precisamos.

Autenticando no Rocket

Nenhuma das APIs que vamos utilizar necessita de autenticação, mas é bom entender como conseguir esses dados antes de continuarmos. E isso é bem simples: estando logado com um usuário administrador, basta gerar um token.

Para gerar o token, basta acessar Minha conta, e clicar em Token de acesso pessoal. Na tela aberta, você deve digitar um nome para identificar esse token e opcionalmente selecionar Ignorar Autenticação de dois fatores (só faz sentido caso deseje utilizar 2FA nessa conta) e clicar em Adicionar.

Será aberto uma tela com os dados do token. Guarde bem esses dados! Eles não serão exibidos novamente. Caso perca, será necessário gerar um novo token.

Observação: Poderia ser qualquer usuário, não necessariamente um administrador, mas nesse caso precisaria ajustar as permissões desse usuário manualmente para permitir o uso da API e ter os acessos necessários ao livechat. Com o administrador, fica mais fácil, mas em um ambiente produtivo seria mais interessante ter um usuário específico com apenas os acessos necessários.

Agora que já temos tudo preparado, podemos começar a analisar as APIs.

Começando com as APIs: Criando um visitante

A primeira coisa a se fazer para integrar o seu chat com o Rocket é criar o visitante. Esse passo será constante, visto que sempre que um novo usuário for transferido, ele precisará ser criado ou atualizado. A mesma API realiza as duas ações, criar e atualizar o visitante.

Para essa ação, temos basicamente um campo obrigatório para criar o visitante. Mas vamos entender melhor cada um:

token* – Um texto de identificação desse visitante. Essa informação deve ser gerada pelo seu sistema para poder encontrar o visitante dentro do Rocket. Ele é o único campo obrigatório e será utilizado como chave para criação e atualização dos dados.

name – O nome do visitante. Será exibido como nome das salas e em cada mensagem.

email – O e-mail do visitante. Além de ser exibido para os agentes que atendem esse contato, pode ser utilizado para envio da transcrição da conversa automaticamente.

department – Departamento do visitante. Esse campo é muito importante pois ele será decisivo ao tentar criar uma sala para o contato. Caso o contato tenha um departamento e não tenha sido especificado um agente específico, será criado a sala apenas com o departamento especificado. phone – Telefone do visitante.

username – Usuário do visitante. Será utilizado para identificação interna e buscas. Se não for informado na criação, será gerado um valor aleatório. Esse valor não poderá ser alterado.

customFields – Campos personalizados do contato. Esses campos precisam ter sido previamente criados via API ou interface. Nesse momento eles terão apenas seus valores definidos. Esse campo é uma lista de objetos contendo a seguite extrutura:

  • key – O nome do campo definido quando foi criado.

  • value – O valor desse campo.

  • overwrite – Se deseja sobrescrever o valor ou não. Se verdadeiro sempre irá definir o valor. Se falso, só irá definidor o valor caso ainda não tenha nenhuma informação.

Agora que entendemos os campos, teríamos o corpo da requisição seguinte a estrutura:

{
"visitor": {
"token": "visitante-identificador",
"name": "Meu visistante",
"email": "visitante@meusite.com",
"department": "SAC",
"phone": "+55 11 98765-4321",
"username": "meuvisitante-123",
"customFields": [{
"key": "address",
"value": "Rocket.Chat street",
"overwrite": true
}]
}
}

O endereço dessa API seria: /api/v1/livechat/visitor. Utilizando o método POST, você poderá criar e atualizar visitantes por esse endereço.

Além do momento da criação, o seu uso é interessante para alternar entre os departamentos e atualizar os campos customizados. Com isso, já temos o visitante criado e pronto para falar com um atendente.

Avançado com as APIs: Criando salas e enviando mensagens

A criação de salas é um processo simples. Ela utiliza o método GET e endereço /api/v1/livechat/room. Ela é utilizada tanto para criar salas como resgatar seus dados.

Todos seus parâmetros são informados via query param na url. Vamos entender melhor eles:

token* – O token do visitante que irá utilizar essa sala. Esse campo é obrigatório em qualquer requisição a esse endpoint. rid – O id da sala. Quando você está criando uma sala esse valor não deve ser informado, afinal, sequer existe. Porém para leitura, deverá ser informado ou uma nova sala será criada. agentId – O id do agente que irá atender essa sala. Se esse valor não for informado, a sala será criada para um atendente aleatório. Caso o visitante tenha um departamento definido, será atribuído um atendente desse departamento. Um ponto importante na criação de salas é a disponibilidade dos agentes: existe a opção de aceitar que as salas sejam criadas mesmo que o agente não esteja online. Mas caso essa opção não seja marcada, a criação de sala apenas funciona se o agente estiver online no Rocket e no Omnichannel.

Agora que já termos a sala criada, podemos enviar mensagens! Também é um processo simples. Esse endpoint utiliza o método POST e o endereço /api/v1/livechat/message.

O seus poucos parâmetros possíveis são passados via corpo da requisição. Vamos entender melhor eles:

token* – O token do visitante que está enviando a mensagem. Precisa ser do mesmo visitante que criou a sala. Esse campo é obrigatório. rid* – O id da sala onde a mensagem será enviada. Ela precisa estar com o status aberta. Esse campo é obrigatório. msg* – O texto da mensagem a ser enviada. Esse campo não pode ultrapassar o limite definido nas configurações do Rocket. Ele é obrigatório. _id – O id da mensagem a ser criada. Caso não seja informado, um id será criado. agent – Na documentação informa que esse campo deve ser o agente da sala. Mas olhando o código do Rocket ele não faz sentido e nunca será usada. Podemos ignora-lo.

Teríamos o corpo da requisição seguindo a estrutura:


{
"token": "visitante-identificador",
"rid": "sala-id-123",
"msg": "Bom dia!"
}

Com isso, já podemos criar um visitante, uma sala e enviar mensagens. Agora o próximo passo é receber o retorno do Rocket com as mensagens enviadas pelos agentes e os eventos que podem ocorrer.

Webhooks: Recebendo retorno do Rocket

Como havia dito, para receber o retorno do Rocket sobre os eventos ocorridos na sala, a melhor forma é via Webhook. Você até conseguiria fazer isso via API (pode visualizar melhor isso na documentação). Porém, via API você teria que efetuar constantes requisições para receber atualizações e tratar cada item da resposta individualmente. Não há possibilidade de filtros por apenas dados não vistos ou algo parecido, no máximo por eventos ocorridos após um timestamp informado. Resumindo, é mais complexo utilizar API e menos prático.

Para utilizar Webhooks é simples! Para configurá-lo, basta acessar o menu Omnichannel e clicar em Webhooks. Na tela aberta, você deve digitar o endereço para onde essas requisições serão disparadas e selecionar quais eventos deverão disparar essa ação. Opcionalmente pode informar um token que será enviado no cabeçalho das requisições para validar a autenticidade. Clique em Salvar para aplicar as mudanças.

Os eventos possíveis são:

Chat Start – Sala criada. Chat Close – Sala encerrada. Agent Messages – Mensagem do atendente. Chat Taken – Agente recebeu a sala. Chat Queued – Sala entrou na fila para encontrar agente (Há possibilidade de uso de serviços externos para sorteio de agente, por isso esse evento pode fazer sentido). Forwarding – Sala encaminhada para outra agente/departamento. Offline Messages – Dependendo se tiver a opção de mensagens offline habilitada e utilizar o widget fornecido, ou utilizar a API, esse evento pode ocorrer. Basicamente o visitante poderia informar o seu nome, e-mail e uma mensagem quando não tiver agentes online. Visitor Messages – Mensagem do visitante. Para cada evento, é realizada uma requisição POST para o endereço informado. O corpo da requisição varia em cada evento, mas é identificado o tipo do evento entre os campos.

No mínimo, será necessário configurar os eventos de sala fechada e mensagem do agente, pois assim será possível saber quando ocorrem respostas e quando for encerrado. Os demais eventos podem não ser necessários.


E por enquanto é isso. Entendeu tudo? Se ainda estiver com dúvida, faço questão de poder te ajudar lá no Twitter através do @Yagasaki7K. Mas lembrando, existem suporte através da própria documentação - que não é lá complexa - existe comunidades dispostas a te ajudar e foruns a rodo. Então, pesquise, estude e se esforce bem. Até a próxima!