API WhatsApp – Hi Platform- Versão 1.0


Objetivo

Disponibilizar as operações necessárias para o envio de mensagem ativa (HSM) no WhatsApp

HSM (Highly Structured Message)

HSMs são templates de mensagens que passam por um processo de aprovação no Facebook, antes de serem disponibilizados na conta requisitante.

Os templates devem seguir os padrões definidos pelo Facebook, para maiores informações, usar o seguinte artigo como referência: Message Template Guidelines

O processo para aprovação do template com o Facebook é feito pela Hi Platform.

Endereço base

  • URL: https://app.hiplatform.com/platform/whatsappconnect/1.0/api/

Autenticação / Autorização

A autenticação da API será feita utilizando o método Basic.

Utilize o seu usuário/senha da plataforma para gerar a sua autenticação. Siga os passos abaixo:

  • Concatene o usuário e a senha separado por : . No nosso exemplo ficaria usuarioApi:senhaApi;
  • Codifique o resultado acima utilizando o formato Base64. No nosso exemplo o exemplo o resultado (token) dessa operação é dXN1YXJpb0FwaTpzZW5oYUFwaQ==.

O token deve ser passado em todas as requisições através do header HTTP Authorization. O valor do header é a junção do esquema de autenticação (no caso Basic) com o token previamente enviado, separados por um espaço em branco. Exemplo:

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/hsm/minha-config_id \
-H 'Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ==' \
-H 'Content-Type: application/json' \
-d '{}'

Cotas de consumo

Os recursos da api possuem limites na quantidade de requisições que podem receber. Esse limites são rotativos respeitando um janela de tempo, por exemplo, o recurso api/message/hsm/ tem um limite de no máximo 500 requisições por minuto.

Cada recurso da api possui um rate limit individual e deve ser acompanhado pela aplicação cliente pelos seguintes headers:

  • X-Rate-Limit-Limit: informa o total de requisições permitidas dentro de uma janela de X minutos.
  • X-Rate-Limit-Remaining: informa quantas requisições para API ainda são permitidas dentro da janela de X minutos corrente. Se uma requisição for feita após esse valor retornar 0, a API retornará o HTTP status code 429 (Too many connections.).
  • X-Rate-Limit-Reset: devolve o número de segundos disponíveis na janela atual.

Template da mensagem

Cada template é identificado por duas propriedades providas pelo Facebook após a aprovação, são elas: namespace e element_name

Através dessas informações que o disparo do HSM poderá ser realizado.


Requisição

  • Objetivo: Enviar HSM para um destinatário.
  • Endpoint: https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/hsm/config_id
  • Método: POST
  • Parâmetros: uri + body
  • Rate limit: 500/min

Exemplo – Envio de HSM sem variáveis

No exemplo abaixo, a mensagem é:

Seu boleto venceu, entre em contato para mais informações.

Considerando isso, o corpo da requisição deve ficar da seguinte forma:

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/hsm/minha-config-id \
-H 'Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ==' \
-H 'Content-Type: application/json' \
-d '{
    "to": "551199999999",
    "namespace": "namespace_Enviado_Pela_Hi",
    "elementName": "elementName_Enviado_Pela_Hi",
}'

A request descrita acima vai gerar a seguinte mensagem para o destinatário:

Seu boleto venceu, entre em contato para mais informações.

Exemplo – Envio de HSM com variáveis

Variáveis permitem customizar informações especificas para cada número que receber a mensagem ativa.

No exemplo abaixo, a mensagem possui duas variáveis, que são identificadas pelos números 1 e 2.

Compra no valor de {{1}} realizado no cartão com o final {{2}} 

Considerando isso, o corpo da requisição deve ficar da seguinte forma:

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/hsm/minha-config-id \
-H 'Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ==' \
-H 'Content-Type: application/json' \
-d '{
    "to": "551199999999",
    "namespace": "namespace_Enviado_Pela_Hi",
    "elementName": "elementName_Enviado_Pela_Hi",
    "localizableParams": [
        {
            "default": "R$10"
        },
        {
            "default": "5364"
        }
    ]
}'

A request descrita acima vai gerar a seguinte mensagem para o destinatário:

Compra no valor de R$10 realizado no cartão com o final 5364

Rate limiting

  • Limite de requisições: 500
  • Janela de tempo: 1 minuto

Parâmetros

NomeObrigatórioDescrição
config_idSimParâmetro alfanumérico que identifica uma conta de WhatsApp na Hi Platform. Essa informação é disponibilizada via suporte.
toSimDestinatário da mensagem
namespaceSimNome do repositório de HSMs de uma conta
elementNameSimNome de uma HSM dentro do repositório
localizableParamsNãoLista ordenada dos parâmetros a serem substituidos no template

Respostas

CodigoMensagemDescrição
200OKMensagem enfilerada para envio
400Bad RequestParâmetros obrigatórios inválidos ou vazios
403ForbiddenAutenticação inválida ou não presente
401UnauthorizedAutenticação inválida