[Guia para desenvolvedores] Conheça os recursos da API para envio de mensagens no WhatsApp
CRIADO
por
Calebe Ribeiro
A API da Huggy possibilita que desenvolvedores criem soluções integradas ao WhatsApp com diferentes objetivos:
- Comunicações de marketing integradas a CRMs
- Ações ativas para recuperação de carrinho abandonado em lojas virtuais
- Atualização em tempo real de encomendas
- Entre outros
Neste guia técnico, você encontrará detalhes sobre os recursos disponíveis na API para o envio de mensagens no WhatsApp.
Conhecendo as diferentes abordagens
Para enviar mensagens no WhatsApp via API, você conta com algumas possibilidades:
- Disparar uma mensagem em uma conversa em andamento
- Enviar um modelo de mensagem para iniciar uma conversa, ou em uma conversa em andamento
Além disso, com o Flow é possível estabelecer fluxos automatizados que enviam mensagens e opcionalmente executam outras ações. Nesse tipo de abordagem, você pode:
- Disparar um fluxo que envia mensagens em um chat
- Iniciar um chat com o envio de um modelo de mensagem para um contato cadastrado na Huggy
Efetuando as requisições para a API
As requisições à API v3 devem ser feitas para a URL https://api.huggy.app/v3, contendo os seguintes cabeçalhos:
Content-Type: application/json
Accept: application/json
Authorization: Bearer xxxxxxx
Disparando uma mensagem em um chat
Veja como estruturar sua requisição para enviar uma mensagem em um chat.
Método: POST
Endpoint: chats/{chatID}/messages
Body: Inclua o texto da mensagem que será enviada utilizando o parâmetro “text”.
{
"text": "Olá, John!"
}Disparando um modelo de mensagem em um chat
Você pode utilizar a API para efetuar o envio de um modelo de mensagem em um chat. Essa estratégia deve ser utilizada quando já existe um chat criado na Huggy.
Método: POST
Endpoint: chats/{chatID}/messages
Body: Informe o identificador da template e os parâmetros de mensagem (se houverem).
{
"hsm": {
"template_id": 675,
"params":
{
"1": "John Doe",
"2": "Huggy"
}
}
}Para criar um chat na Huggy com a API, você deve utilizar o seguinte recurso:
Método: POST
Endpoint: contacts/{id}/chats
{
"channelUuid": "28b407cd-81a4-3abf-94d6-ca4f948d5d2f"
}O id é o identificador do contato. Para acessá-lo, vá para o módulo Contatos e clique no contato desejado. O ID estará à direita, logo abaixo do nome do contato. Você pode também utilizar a API para obter dados de contatos.
Para obter o valor de channelUuid , acesse Configurações > Canais > WhatsApp, escolha o canal desejado e localize o UUID.
Utilizando o Flow
A Huggy permite que você crie fluxos conversacionais automatizados com o Flow. Esses fluxos podem ser disparados pela API em duas situações:
- Para iniciar uma conversa com um contato
- Para disparar mensagens em um chat
Utilizando esse tipo de automação, além de agregar novas funcionalidades aos seus chatbots, você evita penalidades impostas por descumprimento de regras da Meta.
Configuração do Flow
Utilizaremos o fluxo a seguir como exemplo para disparar pela API. Neste caso, automatizamos o envio de um modelo de mensagem e aguardamos que a resposta seja recebida.
Executando um flow para um contato
Veja como configurar uma requisição para executar um flow para um contato:
Método: PUT
Endpoint: contacts/{contactId}/execFlow
Body: Deve informar os campos uuid e flowId:
{
"uuid": "a12cal3r-4a14-8826-d50ad7e9ccc",
"flowId": 35504
}Propriedades
uuid: identificador do canal em que a comunicação vai acontecer. Para localizá-lo, acesse Configurações > Canais > WhatsApp e escolha o canal desejado.
flowId: valor numérico único pelo qual identificamos o fluxo que será executado. Esse valor pode ser encontrado na URL do flow, como destacado na imagem:
contactId: identificador do contato. Para acessá-lo, vá para o módulo Contatos e clique no contato desejado. O ID estará à direita, logo abaixo do nome do contato. Você pode também utilizar a API para obter dados de contatos.
Propriedades opcionais
Algumas propriedades podem ser incluídas na requisição para personalização adicional:
{
"uuid": "a12cal3r-4a14-8826-d50ad7e9ccc",
"flowId": 35504,
"whenInChat": true,
"whenWaitForChat": true,
"whenInAuto": true,
"variables":
{ "data": "15/10/2019",
"inscricao": "confirmada"
}
}whenInChat: define o comportamento quando o atendimento está em chat com um agente.
- true: O agente é removido e o fluxo é acionado.
- false: O fluxo não é executado.
whenWaitForChat: define o comportamento quando o atendimento está aguardando na fila.
- true: O fluxo não é executado.
- false: O atendimento retorna para a camada automática e o fluxo é executado.
whenInAuto: define o comportamento quando o atendimento está na camada automática, ou com outro flow em processamento.
- true: O fluxo em execução é abortado e o novo fluxo é iniciado.
- false: O fluxo não é executado.
Obs.: Quando essas propriedades não são especificadas, o valor padrão é false.
variables: permite a definição de variáveis de contexto personalizadas para incorporar novas informações ao chat.
As variáveis data e inscricao, exemplificadas abaixo, podem ser utilizadas de modo que, após uma resposta positiva do cliente, a confirmação da inscrição e a data de um evento sejam informadas pelo Flow:
"variables": {
"data": "15/10/2019",
"inscricao": "confirmada"
}Executando um flow em um chat
Veja agora como configurar uma requisição para executar um flow em um chat em andamento:
Método: POST
Endpoint: /chats/{chatId}/flow
Para encontrar o chatId, acesse o atendimento desejado e localize o valor na seção Detalhes do atendimento, presente na lateral direita da tela.
Body: Deve informar o flowId para indicar qual flow executar:
{
"flowId": 142714
}Se outro flow estiver em execução no chat, ele será abortado para iniciar o novo fluxo.
Personalize seu flow
O Flow tem um recurso que vai te ajudar a explorar as propriedades opcionais mencionadas aqui: a ação Condicional.
Clique aqui para acessar um conteúdo exclusivo sobre a Condicional e aprenda a deixar seu fluxo de mensagens ainda mais inteligente.
