menu

Primeiros Passos

A API

O que é

Para entender o que é o ChatPro WhatsApp API, primeiramente precisamos entender o que é uma API.

API é um conjunto de rotinas e padrões ara acesso de dados de um aplicativo ou plataforma, é utilizada para comunicação entre sistemas, aplicativos ou plataformas.

O ChatPro WhatsApp API é um conjunto de métodos que irão fazer com que o seu sistema, aplicativo ou plataforma ENVIE e RECEBA mensagens via WhatsApp.

Com o ChatPro WhatsApp API seu sistema poderá, de forma manual ou automática, enviar mensagens para clientes informando, por exemplo, o detalhamento de uma compra, podendo lembrar o paciente de uma consulta marcada no seu sistema, enviando mensagens de rastreamento de encomentas, controle de logística, automação residencial e industrial, rastreamento veicular, criação de atendimento automático, entre várias outras possibilidades que podem ser alcançadas.

Seu sistema também será capaz de receber mensagens e interagir com elas. Por exemplo: seu sistema pode realizar uma ação baseado na resposta do cliente, salvá-la no seu banco de dados, alterar o status de uma transação... dentre várias possibilidades.

O que é preciso

Por ser uma API, é necessário integrá-lo a uma aplicação (sistema, app, site...).

Para isso, é necessário conhecimentos de desenvolvimento. Caso você não seja desenvolvedor, sugerimos que busque o auxílio de um para realizar a integração da API com sua aplicação.

Não é necessário conhecimentos aprofundados em programação. A API pode ser manipulada em diversas linguagens de programação através de requisições HTTP.

Como começar

Para que tenha total segurança na utilização do ChatPro WhatsApp API, disponibilizamos 15 dias e 100 créditos grátis para testes.

Para testar, siga os passos abaixo:

  1. Clique no botão Teste grátis
  2. Preencha os dados corretamente. Sua senha de acesso será enviada para o telefone/WhatsApp informado. Notificações importantes serão enviadas por e-mail.
  3. Ao receber a senha, clique no botão Login ou acesse diretamente em api.chatpro.com.br/painel
  4. Informe seu e-mail e a senha recebida.

Esse é o primeiro passo para começar a utilizar a API. Nos próximos tópicos explicaremos cada seção do painel. Se já quiser efetuar um teste, siga os passos abaixo:

  1. Abra o WhatsApp no seu smartphone. Acesse ajustes, depois WhatsApp Web.
  2. Leia o QR Code do seu painel da API.
  3. Aguarde alguns segundos. Se der tudo certo, o painel mostrará conectado (caso demore mais de 1 minuto, atualize a página).
  4. Com o status conectado, desça a barra de rolagem até o final. Há dois campos para informar número de telefone e mensagem.
  5. Informe um telefone com DDD (que não seja o próprio número conectado), informe uma mensagem e clique em Enviar mensagem.

Note que a mensagem será enviada do seu aparelho e o painel te retornará uma resposta da requisição, contendo id da mensagem e status.

Caso clique em Perfil, o painel irá executar o método /get_profile, que retorna os dados do número inserido, inclusive a foto de perfil (caso esses dados estejam disponíveis no número informado).

Conceitos

Painel

O painel é onde você tem controle dos seus créditos, consumo e instâncias.

Na barra superior, você tem acesso aos créditos da conta, podendo Comprar Créditos ou ver Histórico, tanto de pagamentos quanto de consumo.

Mais abaixo temos as instâncias contratadas na conta. Todas as instâncias presentes aqui compartilham o mesmo pacote de créditos.

Valores e Créditos

A API trabalha com o modelo de pacotes de créditos pré-pago, onde cada crédito representa uma mensagem enviada. Não cobramos por mensagens recebidas.

Quanto maior o pacote de créditos adquirido, menor o valor pago por crédito, podendo chegar a 4 centavos cada crédito. Confira nossa tabela de valores.

Para realizar uma recarga, basta acessar o Painel e clicar em Comprar créditos, escolher um pacote de créditos, inserir os dados do pagador e escolher a forma de pagamento. As formas de pagamento aceitas são: Boleto Bancário, Cartão de Débito ou Cartão de Crédito.

DICA 1
Os créditos não possuem data de validade.

DICA 2
Várias instâncias podem consumir o mesmo pacote de créditos, podendo assim adquirir um pacote com o preço/crédito mais em conta.

DICA 3
Os créditos pagos com cartão de crédito são liberados instantaneamente após a administradora do seu cartão confirmar o pagamento.

Instâncias

Cada instância significa uma possibilidade de conexão com um número de WhatsApp. Caso seu negócio necessite de vários números, é possível contratar instâncias adicionais, que compartilham os créditos de sua conta.

  • Cada instância possui infraestrutura e credenciais próprias.
  • Cada instância possui consumo mínimo de 15 créditos diários. Caso não utilize a instância ou consuma menos de 15 créditos no dia, será debitada a diferença em créditos.

Situação

O status da conexão de sua instância com o smartphone é exibido nessa tela.

Importante lembrar que para que a API funcione, o WhatsApp deve estar sincronizado com sua instância, atraves do QRcode.

O WhatsApp não permite mais de uma conexão externa simultânea, sendo assim, não é possível estar conectado na API e acessar o Whatsapp Web.

Sugerimos que antes de sincronizar o número com o QR Code, acesse no WhatsApp do smartphone em ajustes > Whatsapp Web > Sair de todas as sessões. Assim você garantirá ter apenas uma conexão com o servidor.

Para ler o QR Code, acesse o WhatsApp do smartphone em ajustes > Whatsapp Web > Escanear código QrCode (ou sinal de +).

Após sincronizar o WhatsApp (lendo o QRcode) aguarde até que o status da sua instância mude para Conectado (caso demore mais de 1 minuto, atualize a página). Durante a sincronização, o painel faz uma requisição que traz as informações atuais da conexão, então, juntamente com a alteração de status, o painel informa os dados do celular conectado, percentual da bateria e rede.

Credenciais

Esse espaço é destinado às informações da instância, como:

  • Código: Identificador único da sua instância.
  • EndPoint: Prefixo do endereço utilizado para acessar os métodos. Cada instância tem seu próprio endpoint.
  • Token: Token é a chave de acesso aos métodos. Deverá ser informado no header da requisição (com Authorization). Somente o token combinado com o endpoint mostrará ao servidor que é essa intância que está solicitando o método, portanto nunca divulgue seu token.
  • Nome da instância: É o nome que aparecerá no painel, para controle pessoal das instâncias.
  • Webhook: Opcional. Endereço do seu servidor que receberá as requisições enviadas pel API. Nessas requisições, você receberá status da mensagem, status de leitura, o corpo da mensagem recebida entre outros. A partir daí você pode manipular essas mensagens, por exemplo, salvando em banco de dados.

Testes e Implantação

Métodos

Para saber mais sobre os métodos disponíveis no chatPro WhatsApp API, acesse nossa página de documentação.

Documentação Interativa

A documentação interativa utiliza o Swagger, que permite realizar testes da API diretamente na documentação. Sendo assim, além de conhecer os métodos, é possível realizar testes em cada um deles.

Cada instância tem seu endereço de documentação interativa. Por isso, para acessar a documentação interativa, é necessário fazer login no painel e acessar a instância.

  1. Faça login no seu painel (api.chatpro.com.br/painel)
  2. Acesse uma instância
  3. Certifique-se que o celular está sincronizado com a instância (Conectado)
  4. Desça a barra de rolagem e clique no botão Acessar documentação interativa

Para que o Swagger utilize a API com as suas credenciais, é necessário autorizar essa sessão com seu Token:

  1. Clique link Authorize localizado no canto direito da plataforma Swagger.
  2. No campo Value informe o Token da sua instância
  3. Clique em Authorize
  4. Feche a pequena janela clicando em Close

Pronto, um cadeado "trancado" será exibido, indicando que a sessão do seu navegador está devidamente autorizada a utilizar a API com o celular conectado e executar os métodos.

Realize um teste no método /status. Esse método retorna o status da conexão do WhatsApp com o servidor.

  • Clique método /status
  • Clique em Try it now localizado no canto direito.
  • Clique no botão Execute logo abaixo.
  • O Swagger retornará a informação (trazendo o status atual da conexão).

Realize um teste de envio de mensagem pelo Swagger:

  1. Clique no método /send_message
  2. Clique em Try it now. Preencha no body o número do whatsapp e a mensagem que deseja enviar (substituindo o termo string pelo número e pela mensagem)
  3. Clique em Execute.
    A mensagem será enviada, e o Swagger retornará uma resposta contendo o status do envio.

Postman/Insomnia

Postman e Insomnia são APIs Rest Client. De forma simplificada, são softwares utilizados para testar APIs, enviando requisições e recebendo as respostas.

Os dois softwares são muito semelhantes, por isso vamos testar aqui somente o Postman. Caso o software instalado seja o Insomnia, a lógica é a mesma e você será capaz de realizaar os mesmos testes.

Realizando um teste com o método /status

Lembrando que para realizar qualquer teste com a API, o celular precisa estar conectado à API (status Conectado)

  1. Primeiramente faça o download e instale o Postman do site oficial www.getpostman.com.
  2. Ao abrir o programa, vamos começar com uma nova requisição, clique em New > Request.
  3. Em Request Name preencha Teste API Status
  4. Em Create Colletion, preencha API ChatPro, para criar uma colação de testes dessa API
  5. Clique em Save to API ChatPro
  6. O método /status é do tipo GET, então ao lado esquerdo de Enter request Url, escolha a opção GET.
  7. A URL da requisição é composta por [Seu EndPoint] + [/api/v1/] + [método (no caso /status)], então em Enter request Url, preencha api.service.chatpro.com.br:374xx/api/v1/status (lembrando que o texto que está em vermelho deve ser substituido pelo seu endpoint).
  8. Agora temos que preencher o header com o Token para autorizar essa requisição. Para isso clique abaixo do campo de url, em Headers
  9. Em Query Params, abaixo de KEY, preencha Authorization e à frente, em VALUE, cole o Token que está no seu painel.
  10. Pronto, basta clicar no botão Send.
    O Postman faz a requisição com o método status e retorna o status da conexão logo abaixo no formato Json, com informações importantes da conexão.

Realizando um teste com o método /send_message para enviar uma mensagem do seu Whatsapp:

  1. Crie uma nova requisição, clicando novamente em New > Request
  2. Para essa requisição daremos o nome de Teste API Envio.
  3. O método /send_message é do tipo POST, então teremos que selecionar a opção POST do lado esquerdo da URL da requisição.
  4. A URL da requisição nesse caso muda somente o método em comparação com a URL anterior, ficando api.service.chatpro.com.br:374xx/api/v1/send_message (lembrando que o texto que está em vermelho deve ser substituido pelo seu endpoint).
  5. Agora temos que preencher o header com o Token para autorizar essa requisição. Para isso clique abaixo do campo de url, em Headers
  6. Em Query Params, abaixo de KEY, preencha Authorization e à frente, em VALUE, cole o Token que está no seu painel.
  7. A diferença nessa requisição é que ela tem um corpo (body) com o Json de parâmetros. Para poder escrever o json, clique em Body
  8. Escolha o tipo Raw
  9. Escreva no corpo da requição o json informado na documentação para esse método.

    {
"message": "string",
"number": "string"
}

  10. Troque a palavra String em frente a message por um texto qualquer (o texto da mensagem), e a palavra String em frente ao number, pelo número com DDD que receberá a mensagem (aconselhável não enviar para o próprio número conectado)
  11. Pronto. Basta clicar no botão Send.
    O Postman faz a requisição com o método e retorna a resposta com status, ID da mensagem e o timestamp.

Após fazer as requisições com sucesso, você ainda pode entender como seria a requisição em várias linguagens, clicando no Code, abaixo do botão Send e escolhendo uma linguagem de programação.

Testes no seu servidor

Acesse os exemplo de código disponíveis na página de documentação.

Precisa
de ajuda?