Introdução Webhooks

Conceituação

Neste tópico, abordamos os retornos dos webhooks utilizados pelo API WhatsApp Web.

Importante

Seu endpoint deve aceitar requisições POST para receber notificações de eventos.

Lembre-se: ao criar a instância, você precisa informar as URLs onde deseja receber notificações.

O que é e para que serve?

Webhooks servem para te informar sobre o envio e recebimento de mensagens, além da situação atual da sua instância.

A instância é a página do WhatsApp Web que gerenciamos para a sua conta.

Se você está integrando sua aplicação ao API WhatsApp Web, deve configurar os endpoints para receber notificações sobre todas as interações ocorridas no WhatsApp conectado.

Nossos Webhooks

• Delivery: Notifica quando uma mensagem é enviada.
• Receive: Notifica sempre que alguém interage com seu número.
• Status: Permite checar o status de uma mensagem: recebida, lida, respondida ou excluída.
• Disconnected: Indica interrupções na comunicação entre seu dispositivo e o WhatsApp.
• Connected: Indica o início da comunicação entre seu dispositivo e o WhatsApp.

Configuração de Webhook

Você pode configurar o webhook da sua instância acessando sua conta:

Ao criar uma nova instância, você pode adicionar configurações para receber mensagens.

Configuração via Painel

Acesse o painel de administração, clique em "Instâncias", visualize a instância desejada e edite as configurações.

Webhook ao Enviar

Alterar URL do Webhook via API

Essa API permite alterar a URL de webhook para envio de mensagens por meio de uma requisição PUT.

URL Base

URL Base: https://apiwhatsappweb.com/api/config/sent

Autenticação

Para autenticar as solicitações, você deve incluir a chave API (apiKey) e a identificação da instância ID no cabeçalho (Header).

{
    "apiKey": "Sua chave API aqui",
    "id": "A identificação da instância aqui"
}

Como Alterar o Webhook

Corpo da Requisição

O corpo da requisição deve ser um objeto JSON com a seguinte estrutura:

{
    "URL": "https://Your_Website_here.com/api/config/sent" 
    // Envie a URL onde deseja receber as notificações
}

Importante

O API WhatsApp Web não aceita webhooks que não sejam HTTPS.

Retornos dos Webhooks

O Webhook de envio permite que você seja notificado assim que uma mensagem for enviada com sucesso.

Exemplo de Retorno

{
    "message": "Text sent successfully!",
    "messageSent": "Mensagem enviada por você",
    "number": "Número do contato",
    "messageId": "Identificação da mensagem" // Permite acessar o status da mensagem posteriormente
}

Webhooks Recebido

Alterar URL de Webhook ao receber mensagem por API

Essa API permite trocar a URL para receber notificações por meio de uma requisição PUT.

URL Base

URL Base: https://apiwhatsappweb.com/api/config/receive

Autenticação

Para autenticar as solicitações, você deve incluir a chave API (apiKey) e a identificação da instância Id (identificação) no cabeçalho (Header).

{
    "apiKey": "Sua chave Api aqui",
    "id": "A identificação da instância aqui"
}

Corpo da Requisição

O corpo da requisição deve ser um objeto JSON com a seguinte estrutura:

{
    "URL": "https://Your_Website_here.com/api/config/receive"
}

Importante

O API WhatsApp Web não aceita webhooks que não sejam HTTPS.

Retornos de mensagem recebida

Webhooks de retorno permitem que você veja a mensagem recebida pela API.

Exemplo de Retorno

{
    "messageId": "Identificação da mensagem",
    "message": "Mensagem enviada por outra pessoa",
    "number": "Número enviado",
    "photo": "Foto", // Se não for foto, será null
    "video": "Vídeo", // Se não for vídeo, será null
    "senderName": "Nome do usuário", // Se não houver, será 'Unknown'
    "instanceName": "Nome da Instância cadastrada na plataforma",
    "instanceId": "ID da Instância cadastrada na plataforma",
    "whatsappStatus": {
        "message": "Received",
        "description": "Mensagem enviada por outra pessoa",
        "title": "Título" || null,
        "url": "Url enviada por outra pessoa", // Se não houver, será null
        "groupInvite": "Convite para grupo" // Se não houver, será null
    }
}
    

Webhooks Desconectado

Alterar URL de Webhook ao Enviar por API

Essa API permite alterar a URL que recebe mensagens quando sua instância desconecta via requisição PUT.

URL Base

URL Base: https://apiwhatsappweb.com/api/config/disconnect

Autenticação

Para autenticar as solicitações, você deve incluir a chave API (apiKey) e a identificação da instância Id (identificação) no cabeçalho (Header).

{
    "apiKey": "Sua chave Api aqui",
    "id": "A identificação da instância aqui"
}

Corpo da Requisição

O corpo da requisição deve ser um objeto JSON com a seguinte estrutura:

{
    "URL": "https://Your_Website_here.com/api/config/disconnect"
}

Importante!

O API WhatsApp Web não aceita webhooks que não sejam HTTPS.

Conceituação

Este é o webhook de resposta de desconexão da instância.

Exemplo de Retorno

{
    "instanceName": "O nome da instância que desconectou",
    "instanceId": "A identificação da instância que desconectou",
    "status": "Disconnected",
    "whatsappStatus": { "message": "Disconnected" }
}
    

Webhooks Conectado

Alterar URL de Webhook ao Enviar por API

Essa API permite alterar a URL que receberá notificações ao se conectar à instância, utilizando uma requisição PUT.

URL Base

URL Base: https://apiwhatsappweb.com/api/config/connect

Autenticação

Para autenticar as solicitações, inclua a chave API (apiKey) e a identificação da instância Id (identificação) no cabeçalho (Header).

{
    "apiKey": "Sua chave Api aqui",
    "id": "A identificação da instância aqui"
}

Corpo da Requisição

O corpo da requisição deve ser um objeto JSON com a seguinte estrutura:

{
    "URL": "https://Your_Website_here.com/api/config/connect"
    // Envie a URL onde deseja receber notificações quando a instância se conectar
}

Conceituação

Este webhook notifica sobre a conexão da instância ao sistema.

Exemplo de Retorno

{
    "instanceName": "O nome da instância que desconectou",
    "instanceId": "A identificação da instância que desconectou",
    "status": "Connected",
    "whatsappStatus": { "message": "Connected" }
}