API WhatsApp – Hi Platform- Versão 1.0

Objetivo

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

HSM (Highly Structured Message)/Template

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 usuario 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/template/minha-config_id \
-H 'Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ==' \
-H 'Content-Type: application/json' \
-d '{}'

Modelo da mensagem

Cada HSM é 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/template/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.

O corpo da requisição deve seguir o padrão abaixo (Hi, Botmaker e Interaxa)

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/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"
}'

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:

Formato Botmaker:

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/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",
    "components": [
        {
            "type": "body",
            "parameters": [
                {
                    "variableName": "var_1",
                    "type": "text",
                    "text": "R$10"
                },
                {
                    "variableName": "var_2",
                    "type": "text",
                    "text": "5364"
                }
            ]
        }
    ]
}'

Formato Hi/Interaxa:

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/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",
    "components": [
        {
            "type": "body",
            "parameters": [
                {
                    "type": "text",
                    "text": "R$10"
                },
                {
                    "type": "text",
                    "text": "5364"
                }
            ]
        }
    ]
}'

Para ambas requisições (Hi, Botmaker e Interaxa) será entregue a seguinte mensagem com a utilização de variáveis para o destinatário:

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

Rate limit

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

Requisição

• Objetivo: Enviar Template para um destinatário com recursos adicionais
• Endpoint: https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/config_id
• Método: POST
• Parâmetros: uri + body

Envio de Template com Header, Footer, Botão e SEM variáveis no body

A utilização do Header, Footer e Botão não modifica a requisição da API, a exibição ou não destes recursos está relacionado a como o Template foi aprovado.

Considerando isso, caso o Template não tiver variáveis, o corpo da requisição fica da seguinte forma, seja Hi, Botmaker ou Interaxa:

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/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"
}'

No exemplo abaixo, o Template possui Header e Footer sem variáveis no body.

[HEADER (texto)]
Olá! Somos da Hi Platform e gostaríamos de falar sobre os seus canais de atendimento.

Escreva "quero saber mais" para um de nossos atendentes dar continuidade ao seu atendimento.
[FOOTER (texto)]

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

Envio de Template com Header, Footer, Botão e COM variáveis no body

No exemplo abaixo, a mensagem possui botões e quatro variáveis, que são identificadas pelos números 1, 2, 3 e 4

Olá {{1}}! Somos da Hi Platform e identificamos que os seus canais: {{2}}, {{3}}, {{4}} foram atualizados. 

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

Formato Botmaker:

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/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",
    "components": [
        {
            "type": "body",
            "parameters": [
                {
                    "variableName": "var_1",                   
                    "type": "text",
                    "text": "João"
                },
                {
                    "variableName": "var_2",                        
                    "type": "text",
                    "text": "Telefone"
                },
                {
                    "variableName": "var_3",                        
                    "type": "text",
                    "text": "Email"
                },
                {
                    "variableName": "var_4",                        
                    "type": "text",
                    "text": "Chat"
                }
            ]
        }
    ]
}'

Formato Hi/Interaxa:

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/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",
    "components": [
        {
            "type": "body",
            "parameters": [
                {
                    "type": "text",
                    "text": "João"
                },
                {
                    "type": "text",
                    "text": "Telefone"
                },
                {
                    "type": "text",
                    "text": "Email"
                },
                {
                    "type": "text",
                    "text": "Chat"
                }
            ]
        }
    ]
}'

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

Exemplo – Envio de Template com Imagem e COM variáveis no body

Além de variáveis no corpo da mensagem, o Template pode ter uma imagem (nos formatos jpg ou png) no header.

No exemplo abaixo, a mensagem é:

[HEADER (imagem)]
Olá {{1}}! Somos da Hi Platform e gostaríamos de falar sobre os nossos canais de atendimento.

Escreva "quero saber mais" para falar com um de nossos representantes.
[FOOTER (texto)]

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

Formato Botmaker:

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/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",
    "components": [
        {
            "type": "header",
            "parameters": [
                {
                    "type": "image",
                    "image": {
                        "link": "https://urldaimagem.com.br/imagem"
                    }
                }
            ]
        },
        {
            "type": "body",
            "parameters": [
                {
                    "variableName": "var_1",
                    "type": "text",
                    "text": "João"
                }
            ]
        }
    ]
}'

Formato Hi/Interaxa:

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/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",
    "components": [
        {
            "type": "header",
            "parameters": [
                {
                    "type": "image",
                    "image": {
                        "link": "https://urldaimagem.com.br/imagem"
                    }
                }
            ]
        },
        {
            "type": "body",
            "parameters": [
                {
                    "type": "text",
                    "text": "João"
                }
            ]
        }
    ]
}'

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

Se esse mesmo modelo de Template com imagem não tivesse variável, o corpo da requisição ficaria da seguinte forma (Hi, Botmaker e Interaxa):

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/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",
    "components": [
        {
            "type": "header",
            "parameters": [
                {
                    "type": "image",
                    "image": {
                        "link": "https://urldaimagem.com.br/imagem"
                    }
                }
            ]
        }
    ]
}'

Exemplo – Envio de Template com Documento e COM variáveis no body

O Template pode ter um documento no formato pdf em seu header.

No exemplo abaixo, a mensagem é:

[HEADER (documento)]
Olá {{1}}!! Somos da Hi Platform e gostaríamos de falar sobre os nossos canais de atendimento.

Escreva "quero saber mais" para falar com um de nossos representantes.
[FOOTER (texto)]

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

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/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",
    "components": [
        {
            "type": "header",
            "parameters": [
                {
                    "type": "document",
                    "document": {
                        "link": "https://urldodocumento.com.br/documento",
                        "filename": "Informativo"
                    }
                }
            ]
        },
        {
            "type": "body",
            "parameters": [
                {
                    "variableName": "var_1",
                    "type": "text",
                    "text": "Gabriel Spina"
                }
            ]
        }
    ]
}'

Formato Hi/Interaxa:

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/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",
    "components": [
        {
            "type": "header",
            "parameters": [
                {
                    "type": "document",
                    "document": {
                        "link": "https://urldodocumento.com.br/documento",
                        "filename": "Informativo"
                    }
                }
            ]
        },
        {
            "type": "body",
            "parameters": [
                {
                    "type": "text",
                    "text": "Gabriel Spina"
                }
            ]
        }
    ]
}'

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

Se esse mesmo modelo de Template com documento não tivesse variável, o corpo da requisição ficaria da seguinte forma (Hi, Botmaker e Interaxa):

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/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",
    "components": [
        {
            "type": "header",
            "parameters": [
                {
                    "type": "document",
                    "document": {
                        "link": "https://urldodocumento.com.br/documento",
                        "filename": "Informativo"
                    }
                }
            ]
        }
    ]
}'

Os modelos abaixo funcionam apenas para Hi Broker

Exemplo – Envio de Template com modelo de autenticação

Os modelos de autenticação de cópia de código permitem que você envie aos usuários uma senha ou um código descartável junto com um botão de copiar código.

curl --location 'https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/minha-config' \
--header 'Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ==' \
--header 'Content-Type: application/json' \
--data '{
    "to": "55119999999",
    "namespace": "default",
    "elementName":  "elementName_Enviado_Pela_Hi",
    "components": [
        {
            "type": "otp",
            "parameters": [
                {
                    "type": "text",
                    "text": "123456"
                }
            ]
        }
    ]
}'

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

Exemplo – Envio de Template com váriavel de texto no header

A variável no header serve para personalizar a saudação inicial no seu modelo.

curl --location 'https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/minha-config' \
--header 'Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ==' \
--header 'Content-Type: application/json' \
--data '{
    "to": "5511999999",
    "namespace": "default",
    "elementName": "elementName_Enviado_Pela_Hi",
    "components": [
        {
            "type": "header",
            "parameters": [
                {
                    "type": "text",
                    "text": "TEXTO AQUI"
                }
            ]
        }
    ]
}'

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

Exemplo – Envio de Template com cupom de desconto e variável no body

Os modelos de código de cupom são modelos de marketing que mostram um botão único de copiar código. Quando o cliente toca no botão, o código é copiado para a área de transferência.

Limitações

• Os modelos de código de cupom não são compatíveis com o WhatsApp Web para clientes.
• Os códigos têm limite de 15 caracteres.
• O texto do botão não pode ser personalizado.

Os modelos podem ter apenas um botão de copiar código.

curl --location 
'https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/minha-config ' --header 'Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ=='
--header 'Content-Type: application/json'
--data '{
    "category": "Marketing",
    "to": "55119999999",
    "namespace": "default",
    "elementName": "elementName_Enviado_Pela_HI",
    "components": [
        {
            "type": "body",
            "parameters": [
                {
                    "type": "text",
                    "text": "TEXTO AQUI"
                }
            ]
        },
        {
            "type": "button",
            "parameters": [
                {
                    "index": "0",
                    "type": "coupon",
                    "coupon_code": "CUPOMAQUI"
                }
            ]
        }
    ]
}'

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

Exemplo – Envio de Template com link dinâmico e uma variável

Você pode inserir seus próprios parâmetros de URL personalizados ou usar os parâmetros de URL dinâmicos. Os parâmetros dinâmicos são úteis porque oferecem uma maneira automática de inserir os valores dos seus parâmetros com base nas informações que você fornece ao configurar o modelo.

curl --location 'https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/MINHA-CONFIG' \
--header 'Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ==' \
--header 'Content-Type: application/json' \
--data '{
    "category": "Marketing",
    "to": "551199999999",
    "namespace": "default",
    "elementName": "elementName_Enviado_Pela_HI",
    "components": [
        {
            "type": "body",
            "parameters": [
                {
                    "type": "text",
                    "text": "texto aqui"
                }
            ]
        },
        {
            "type": "button",
            "parameters": [
                {
                    "type": "url",
                    "index": 1,  // posição do botão na mensagem
                    "text": "BBBB"
                }
            ]
        }
    ]
}'

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

Exemplo – Envio de Template com dois links dinâmicos e uma variável no body

curl --location 'https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/MINHA-CONFIG' \
--header 'Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ==' \
--header 'Content-Type: application/json' \
--data '{
    "category": "Marketing",
    "to": "551199999999",
    "namespace": "default",
    "elementName": "elementName_Enviado_Pela_HI",
    "components": [
        {
            "type": "body",
            "parameters": [
                {
                    "type": "text",
                    "text": "texto aqui"
                }
            ]
        },
        {
            "type": "button",
            "parameters": [
                {
                    "type": "url",
                    "index": 0,    // posição do botão na mensagem
                    "text": "AAAA"
                }
            ]
        },
        {
            "type": "button",
            "parameters": [
                {
                    "type": "url",
                    "index": 1,  // posição do botão na mensagem
                    "text": "BBBB"
                }
            ]
        }
    ]
}'

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

Exemplo – Envio de Template com Header de mídia com vídeo

Permite o envio de vídeos de até 16mb no formato mp4 no header do modelo.

curl --location 'https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/minha-config' \
--header 'Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ==' \
--header 'Content-Type: application/json' \
--data '{    
    "to": "55119999999",
    "namespace": "default",
    "elementName": "elementName_Enviado_Pela_HI",
    "components":  [
        {            
            "type": "header",
            "parameters": [                
                {                    
                    "type": "video",                    
                    "video": 
                        {                        
                           "link": "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerMeltdowns.mp4"  // Formato MP4 até 16mb
                        }                
                }            
            ]        
        }
    ]
}'

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

Parâmetros

Respostas

A partir do disparo de HSMs via esta API, retornamos as seguintes informações:

Cotas de consumo

Cota de consumo: 60 requisições em janela de 10 minutos.
Recomenda-se a extração de até 31 dias para uma melhor performance no tempo de resposta.
Como funciona a cota de consumo: O cliente que usar essa API estará sujeito a um limite na quantidade de requisições que poderá enviar em um dado período de tempo. Essa prática é conhecida como Rate Limiting e é fundamental para garantir a qualidade do serviço.
A cada 'X' minutos (variável conforme o método solicitado) o cliente tem direito a fazer um determinado número de requisições (também variável conforme o método solicitado). Passado o tempo especificado, o limite é reiniciado.
O consumo do limite pode variar conforme o método solicitado e deve ser acompanhado pelos seguintes http 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.

Disparo de HSM

Adição de propriedade no disparo:

curl -X POST \
https://app.hiplatform.com/platform/whatsappconnect/1.0/api/message/template/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",
    "externalLabel": "black_friday"
}'

Relatório via API

Disponibilizado endpoint para consumo do relatório de HSM, através da seguinte requisição:

curl --location --request GET 'https://app.hiplatform.com/platform/whatsappconnect/1.0/api/reports/hsm?pageSize=200&pageNumber=1&startDate=1670335698&endDate=1670345698' \
-H 'Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ==' \
--H 'Content-Type: application/json'

Parâmetros

Rate limit: 60 requisições em janela de 10 minutos

Tendo como exemplo de retorno:

{
    "status": "OK",
    "data": {
        "totalResults": 383356,
        "totalPages": 1917,
        "pageNumber": 1,
        "items": [
            {
                "sender": "5511912341234",
                "recipient": "5511998769876",
                "origin": "API",
                "namespace": "cd551e83_8455_45fd_a2ff_35ef6a51f3c6",
                "elementName": "hiplataform_2",
                "operatorName": "",
                "billable": true,
                "externalLabel": "black_friday",
                "dispatchDate": 1670336766,
                "sentDate": 1670336766,
                "receivedDate": 1670336767,
                "readDate": 1670336840
            },
            ...
        ]
    }
}

Artigos relacionados:

Gestão de usuários de API