# WhatsApp ## 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 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. {% file src="/files/-MgucsVcFgaHl778Wq67" %} Artigo técnico do WhatsApp (inglês) {% endfile %} {% hint style="danger" %} 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. {% endhint %} ## 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 {% hint style="warning" %} 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. {% endhint %} ## 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.](/files/-MgC5WorBbCYFjSHh3n1) ## Instância e sincronização Essa API foi desenvolvida utilizando os módulos presentes no [WhatsApp Web](https://web.whatsapp.com) 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 ](/apis-v2/whatsapp.md#webhooks)como Callbacks, DLRs e outros. {% hint style="warning" %} 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. {% endhint %} ### 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](https://v2.smsfire.com.br) e criar uma a partir do menu ***WhatsApp → Instâncias*** ![Menu de criação de instâncias](/files/-Mg6VJQV6j3FFi8ZVvbL) 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](/files/-Mg6WC6O7dHACFsKWxuD) 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](/files/-Mg6WfhvpxKJ6Ck9JVY5) {% hint style="success" %} 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. {% endhint %} ### 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](https://web.whatsapp.com), 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](/files/6YcG0sh4W3c2I7TOh4VV) #### 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](/files/-Mg6YYzSgpnwaZaYlPmF) 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](/files/-Mg6ZDTEziWY82H4KO6y) 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. {% hint style="info" %} O WhatsApp no momento não permite a utilização de múltiplos dispositivos, por isso é importante salientar que ao sincronizar o seu número em nosso Portal você deverá evitar sincroniza-lo no WhatsApp Web, porque isso fará com que a sincronização seja perdida. {% endhint %} ## 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](https://v2.smsfire.com.br) ou [API](/apis-v2/whatsapp/enviar-mensagem.md), enquanto seu número estiver sincronizado/pareado com a [SMSFire](https://smsfire.com.br). > 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. {% hint style="info" %} Enquanto a sessão estiver ativa, não há limitação de envios e recebimento de mensagens entre você e o contato. {% endhint %} {% hint style="success" %} 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. {% endhint %} ## WhatsApp Web Neste momento o WhatsApp não disponibiliza um módulo ou função que permita o compartilhamento da sincronização entre múltiplos dispositivos. Por isso, ao sincronizar o seu número no [WhatsApp Web](http://web.whatsapp.com) enquanto estiver conectado ao Portal SMSFire, ou vice-versa, fará com que a sincronização seja encerrada com o nosso sistema. ## 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*. {% hint style="info" %} 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*. {% endhint %} 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](/apis-v2/whatsapp.md#notificacoes-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](/files/-MfDhONXWm76SCqDEcDq) {% hint style="warning" %} 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. {% endhint %} {% hint style="danger" %} **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. {% endhint %} ### Qrcode Modelo de objeto JSON enviado ao seu endpoint a cada atualização do qrcode. ```json { "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](https://github.com/davidshimjs/qrcodejs) {% hint style="info" %} 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.. {% endhint %} ### Callbacks e DLR Modelo de objeto JSON enviados ao seu endpoint. ```typescript { "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: ```typescript { "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: {% hint style="success" %} Verifique os detalhes sobre mensagens multimídia a partir da seção [Suporte a Multimídia](/apis-v2/whatsapp/enviar-mensagem.md#suporte-a-multimidia) {% endhint %} ```typescript { "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 ```typescript { "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" } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.smsfire.com.br/apis-v2/whatsapp.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.