WhatsApp

Informações úteis para as perguntas mais comuns ao utilizar este serviço.

Disclaimer

Essa API não é afiliada, associada, autorizada, endossada ou de qualquer outra forma conectada oficialmente com o WhatsApp ou qualquer um de seus afiliados ou provedores oficiais. O site oficial do WhatsApp pode ser acessado em https://whatsapp.com e a partir dele ter essas informações. "WhatsApp" assim como nomes relacionados, marcas, emblemas e imagens são marcas registradas de seus respectivos donos.

No momento nós não somos um parceiro global do WhatsApp e por isso, ao utilizar essa API você assume o risco de bloqueio do número no aplicativo, dado que a plataforma não autoriza o uso de bots ou APIs não oficiais e por isso o uso desta não pode ser considerado totalmente seguro de bloqueios.

Ainda assim, a intenção da disponibilização deste serviço é oferecer uma solução alternativa de custo reduzido, menos burocrática e acesso imediato a clientes de pequeno e médio porte que desejam automatizar sua comunicação através do aplicativo, ou até mesmo, em transformar o seu número em uma central de atendimento onde vários agentes podem ter acesso a um único número de forma simultânea.

435KB

artigo-técnico-Bloqueio-de-uso-não-autorizado.pdf

pdf

Apesar de todas as recomendações de boas práticas mencionadas no item a seguir a SMSFire não se responsabiliza por qualquer ônus que o cliente possa sofrer em decorrência do possível bloqueio do número ao aplicativo enquanto utilizar a ferramenta para fins de marketing massivo ou qualquer outro, ora identificado pelo WhatsApp, que venham ferir suas politicas de privacidade e termos de utilização.

Boas práticas

Algumas medidas de boas práticas, se adotadas, reduzem o risco de bloqueio e garantem que métodos de API como esta permaneçam ativas por mais tempo. Abaixo listamos algumas medidas que já identificamos que reduzem o risco de bloqueio do número no aplicativo, sendo:

• Evite envios em massa para não contatos

• Mesmo para contatos, evite envio de mensagens em massa

• Tente interagir de modo passivo, ou seja, deixe o contato iniciar a conversa

• Utilize o WhatsApp Business com um perfil válido ao invés do WhatsApp convencional

• Evite utilizar números recém cadastrados no aplicativo e/ou recém habilitados na operadora

• Disponibilize um meio de opt-out para o destinatário solicitar a saída da sua lista de comunicação

• Evite envios de links de domínios públicos como bit.ly, goo.gl, entre outros

• Evite envios de mensagens a destinatários de países distintos ao do número sincronizado

• Evite o envio de imagens ou arquivos sem um texto descritivo (legenda)

• Tente personalizar ao máximo o texto para cada destinatário

Não temos informações adicionais e/ou recomendações sobre o volume máximo diário de disparos ou o ideal de espera entre o envio de uma mensagem e outra.

Notificações via e-mail

É possível registrar um ou mais endereços de e-mail para receber notificações quando a sua instância ou sincronização sofrer alterações. Para registrar os endereços de e-mail acesse o menu Minha conta → Configurações → Notificações e então ative a opção WhatsApp e siga as orientações em tela.

Tela de configurações de notificações via e-mail.

Instância e sincronização

Essa API foi desenvolvida utilizando os módulos presentes no WhatsApp Web e por isso é necessária a sincronização via Qrcode do seu número a uma instância vinculada ao seu usuário em nosso Portal.

Quando a instância está sincronizada ao seu número, você poderá enviar e receber mensagens a destinatários que estejam ou não em sua lista de contatos, receber dados de webhooks como Callbacks, DLRs e outros.

Durante a utilização da API é necessário manter o dispositivo ativo e com conexão de dados disponível e de boa qualidade. Sem isso, a sincronização poderá ser perdida mesmo nas versões mais recentes de múltiplos dispositivos e suas mensagens e/ou status não serão processados corretamente.

Criando uma instância

Neste momento não disponibilizamos um serviço de API capaz de criar ou editar uma instância. Por isso, é necessário acessar o nosso Portal Web e criar uma a partir do menu WhatsApp → Instâncias

Menu de criação de instâncias

Logo que a instância estiver criada acesse as configurações da mesma para adquirir o TOKEN da instância. Este TOKEN é necessário na utilização dos serviços da API.

Modal com TOKEN da instância

Nas configurações da instância, também será possível alterar o seu nome, compartilhar acesso a sub usuários, entre outras opções.

Modal das configurações da instância

Os sub usuários que receberem permissão para acessar a instância, poderão também realizar a utilização do serviço via API desde que você compartilhe o TOKEN de acesso a eles.

Sincronização

Este processo é importante para que consigamos processar os dados de mensagens enviadas e recebidas além dos dados de webhooks.

A sincronização acontece da mesma forma que você faz para acessar o WhatsApp Web, ou seja, a partir da leitura do Qrcode via aplicativo.

Sincronização via menu Instâncias

Após ter criado a sua instância, mantenha-se no mesmo menu WhatsApp → Instâncias e na linha da instância desejada, clique no botão "Sincronizar WhatsApp", aguarde o carregamento dos dados da instância e então faça o escaneamento do qrcode seguindo as orientações dada em tela.

Sincronizar WhatApp

Sincronização via menu Dashboard

Após ter criado a sua instância, você acessará o menu WhatsApp → Dashboard. Neste menu, você selecionará a instância que deseja sincronizar e seguir as orientações em tela.

Tela de sincronização do Qrcode

Após a sincronização do Qrcode o seu Dashboard será aberto, e a partir de então, todas as mensagens recebidas (com exceção dos números mencionados em Ignorar Interação nas configurações da instância) serão captadas pelo nosso sistema.

Tela do Dashboard com número sincronizado

Uma vez sincronizado, mantenha o dispositivo ligado e com conexão a internet ativa. Dessa forma a sincronização permanece ativa e válida para o correto processamento dos dados.

Sessões

Cada nova interação com um contato, seja ele da sua lista ou não, pode ser considerado como uma sessão que possuí uma duração de 24h corridas a partir da data da última interação.

A sessão é iniciada a partir do envio, assim como no recebimento também, de mensagens de contatos ou não contatos que ainda não tenham interação inicializada através do Portal Web ou API, enquanto seu número estiver sincronizado/pareado com a SMSFire.

Quando a sessão é iniciada a tarifa sempre é cobrada do usuário principal, mesmo quando ela tenha sido originada por uma subconta.

A sessão é renovada por mais 24h corridas a partir da última interação de mensagens enviadas ou recebidas, isso se essa situação ocorrer durante uma sessão ativa.

Enquanto a sessão estiver ativa, não há limitação de envios e recebimento de mensagens entre você e o contato.

Atualmente a sessão aberta não tem data definida de encerramento, ou seja, após 24h ela não será finalizada. Portanto, verifique com a área comercial em qual fase o serviço encontra-se para ter claro quais são as condições de cobrança do momento.

Webhooks

Todos os dados serão enviados ao seu endpoint encodados em JSON via POST. Cada atualização de status irá gerar uma requisição, ou seja, se você enviar 10 mil mensagens é possível que existam 30 mil requisições a sua URL ao considerar Callbacks, DLRs, MOs e Qrcode.

O DLR do WhatsApp acusará como DELIVERED quando a mensagem receber o duplo tique comum e caso o destinatário tenha a confirmação de leitura ativada (duplo tique azulado) em suas configurações de privacidade, você receberá um segundo DLR também como DELIVERED.

Atualizações de instância e sincronização não são enviadas por Webhooks. Para receber notificações sobre essas atualizações considere a leitura do item Notificações via E-mail.

Você poderá registrar diferentes endpoints para cada tipo de situação como CALLBACK, DLR, MO e QRCODE.

Para registrar seus endpoints acesse o menu Minha conta → Configurações → Webhooks

Tela de configurações de endpoints para Webhooks

Devido ao grande volume de requisições que nossa API poderá fazer em seu servidor, recomendamos fortemente a utilização de um software para gerenciamento de filas (RabbitMq ou Kafka por exemplo) para evitar gargalos em seu banco de dados e/ou servidores.

TIMEOUT - 10 segundos Este é o tempo de espera máxima que nossos servidores usam para ter uma resposta (positiva ou negativa) do seu endpoint cadastrado nos webhooks. Passado esse tempo, o pacote de dados será descartado, sem possibilidade de reenvio.

Qrcode

Modelo de objeto JSON enviado ao seu endpoint a cada atualização do qrcode.

{
  "instanceToken": "499893c21b1b467970b2n58dcak6009d92d9dscx1",
  "qrcode": "1@nmuAyY0Mxs23mM5EB04BgBdt0rrlpE+lXn3K3v3EtS++43I\/XaPAITEdLen4CdMQjuoTWzpw4k1X8A==,oGwWIwW8QpfZRO4i7fp+65qL0zQRqbnLipuOaHOD8B4=,bXkm89d+8i04vJbB2KeB+Q==",
  "date": "2021-12-03T17:10:10-0300"
}

Para a impressão do QRCode em ambiente web recomendamos a utilização da biblioteca qrcodejs

A instância permanecerá emitindo o qrcode por 3 minutos. Após este período a instância irá mudar seu estado para stand-by e então, será necessário reiniciar o processo..

Callbacks e DLR

Modelo de objeto JSON enviados ao seu endpoint.

{
  "instanceToken": "499893c21b1b467970b2n58dcak6009d92d9dscx1",
  "id": 12345,
  "customId": "firezap0001",
  "messageType": "TEXT",
  "country": "55",
  "phone": "5511944556677",
  "statusCode": 2,
  "statusName": "DELIVERED",
  "statusDate": "2021-08-02T13:37:48-0300",
  "sentDate": "2021-08-02T13:37:40-0300"
}

MO (Mensagem recebida)

Modelo de objeto JSON enviados ao seu endpoint a cada nova mensagem recebida em seu número enquanto sincronizado ao nosso Portal.

JSON de mensagem simples:

 { 
  "instanceToken": "499893c21b1b467970b2n58dcak6009d92d9dscx1",
  "id": 12345,
  "messageType": "TEXT",
  "country": "55",
  "phone": "5511944556677",
  "text": "Olá bom dia!",
  "receivedDate": "2021-08-02T17:55:37-0300",
  "openDate": "1969-12-31T21:00:00-0300"
}

JSON de mensagem multimídia:

Verifique os detalhes sobre mensagens multimídia a partir da seção Suporte a Multimídia

{
  "instanceToken": "499893c21b1b467970b2n58dcak6009d92d9dscx1",
  "id": 12345,
  "messageType": "IMAGE",
  "messageMedia": "https://smsfire.../E4FB488J1612477826D0!15106080CG8.jpeg",
  "country": "55",
  "phone": "5511944556677",
  "text": "Veja detalhes nessa imagem",
  "receivedDate": "2021-08-03T03:25:18-0300",
  "openDate": "1969-12-31T21:00:00-0300"
}

JSON de mensagem com localização

{
    "instanceToken": "499893c21b1b467970b2n58dcak6009d92d9dscx1",
    "id": 00001,
    "messageType": "LOCATION",
    "location":{
      "latidude": 40.01173076879178,
      "longitude": -105.01789945249678,
      "description": "Disney Land\nErie, CO 80516"
    },
    "country": "55",
    "phone": "5511977889900",
    "receivedDate": "2021-08-06T09:59:54-0300",
    "openDate": "2021-08-06T09:59:55-0300"
  }