GWhats
    Referência de API

    Documentação da API GWhats

    Integre o GWhats à sua aplicação usando nossa API REST. Gerencie contatos, conversas, mensagens, agentes, equipes e receba eventos em tempo real via webhooks.

    BASE URLhttps://app3.gwhats.app

    Introdução

    A API GWhats é uma interface REST que permite integrar sua aplicação ao sistema de atendimento omnichannel. Todas as respostas são em JSON e todas as requisições devem ser feitas via HTTPS.

    Application API

    Para automação e integrações de agentes. Usa user access token. Prefixo: /api/v1

    Client API

    Para criar experiências de chat customizadas. Usa inbox e contact identifiers.

    Platform API

    Ferramentas administrativas (self-hosted). Usa Platform App tokens.

    Esta documentação cobre a Application API — a mais utilizada para integrações. A maioria dos endpoints usa o prefixo /api/v1, exceto Relatórios que usa /api/v2.

    Autenticação

    Todas as requisições precisam incluir o API Access Token no header. Acesse app3.gwhats.app → Configurações do Perfil → Tokens de Acesso para gerar o seu.

    Como gerar seu token

    1. 1Faça login em https://app3.gwhats.app
    2. 2Clique no seu avatar (canto inferior esquerdo)
    3. 3Acesse "Configurações do Perfil"
    4. 4Role até a seção "Tokens de Acesso"
    5. 5Clique em "Copiar" ao lado do token

    Via header (recomendado)

    bash
    curl -X GET "https://app3.gwhats.app/api/v1/profile" \
  -H "api_access_token: SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json"

    Via query string

    bash
    curl "https://app3.gwhats.app/api/v1/profile?api_access_token=SEU_TOKEN_AQUI"

    Encontrando seu Account ID

    O account_id aparece na URL após o login: https://app3.gwhats.app/app/accounts/123/...

    Contatos

    Contatos representam clientes ou leads. Suportam atributos customizados e podem ter múltiplas conversas associadas.

    Conversas

    Conversas são os atendimentos vinculados a um contato. Cada conversa pertence a um canal (WhatsApp, Instagram, E-mail, etc.) e pode ser atribuída a agente ou equipe.

    Mensagens

    Envie e liste mensagens dentro de uma conversa. Suporta texto, notas privadas e anexos.

    Tipos de mensagem (message_type)

    0incoming — Recebida do contato
    1outgoing — Enviada pelo agente
    2activity — Atividade do sistema
    3template — Template aprovado (WhatsApp)

    Agentes

    Agentes são os atendentes da sua conta. Gerencie permissões, disponibilidade e atribuições via API.

    Papéis (role)

    agent — Atendente padrão
    administrator — Acesso administrativo total

    Equipes

    Organize agentes em equipes para facilitar a distribuição de conversas e relatórios por grupo.

    Caixas de Entrada

    Caixas de entrada (Inboxes) representam os canais de comunicação: WhatsApp, Instagram, E-mail, Chat no site, etc.

    Tipos de canal (channel_type)

    Channel::WhatsappChannel::InstagramChannel::EmailChannel::WebWidgetChannel::ApiChannel::FacebookPageChannel::SmsChannel::Telegram

    Labels

    Labels são etiquetas que categorizam conversas (ex: "urgente", "vip", "pós-venda"). Use-as para filtrar e organizar atendimentos.

    Webhooks

    Webhooks enviam notificações HTTP em tempo real para a sua URL quando eventos ocorrem. Também configurável em Configurações → Integrações → Webhooks.

    Eventos disponíveis

    conversation_created

    Nova conversa criada

    conversation_status_changed

    Status alterado (ex: aberto → resolvido)

    conversation_updated

    Conversa atualizada (agente, equipe, label)

    message_created

    Nova mensagem recebida ou enviada

    message_updated

    Mensagem atualizada (ex: status lida)

    contact_created

    Novo contato criado

    contact_updated

    Contato atualizado

    webwidget_triggered

    Widget ativado no site

    Exemplo de payload — nova mensagem

    json
    {
  "event": "message_created",
  "id": 502,
  "content": "Olá! Quero saber mais sobre os planos.",
  "message_type": "incoming",
  "content_type": "text",
  "private": false,
  "created_at": "2024-01-15T11:35:00.000Z",
  "conversation": {
    "id": 101,
    "status": "open",
    "channel": "Channel::Whatsapp",
    "inbox_id": 3
  },
  "sender": {
    "id": 42,
    "name": "João Silva",
    "phone_number": "+5511999990000",
    "type": "contact"
  },
  "account": {
    "id": 1,
    "name": "Minha Empresa"
  }
}

    Respondendo ao webhook (Node.js)

    javascript
    app.post('/webhook/gwhats', (req, res) => {
  const { event, conversation, sender, content } = req.body;

  if (event === 'message_created') {
    console.log(`Nova mensagem de ${sender.name}: ${content}`);
    // processe o evento...
  }

  // IMPORTANTE: responda 200 em até 10 segundos
  // O GWhats tenta reenviar até 3 vezes em caso de falha
  res.status(200).json({ received: true });
});

    Relatórios

    Acesse dados de performance de agentes, equipes, caixas de entrada e da conta geral.

    Os endpoints de Relatórios usam /api/v2 (não v1).

    Salas de Chat

    Salas de chat são espaços de comunicação interna entre agentes da sua equipe — separados das conversas com clientes. Use-as para coordenação interna, triagem de atendimentos e colaboração em tempo real.

    O recurso de Salas de Chat precisa estar habilitado na conta. Caso contrário a API retorna 403 com Feature chat_rooms is not enabled.

    Salas

    Membros

    Mensagens da Sala

    Mensagens Agendadas

    Programe mensagens para serem enviadas em um momento futuro — ideal para follow-ups pós-venda, lembretes de consulta, newsletters recorrentes e campanhas de nutrição de leads. Suportam texto simples, anexos (até 15), templates do WhatsApp e recorrência diária/semanal/mensal/anual.

    Nível de Conta

    Por Conversa

    Gerencie agendamentos dentro do contexto de uma conversa específica.

    Exemplo: campanha de nutrição de leads (3 toques)

    bash
    # Toque 1 — imediato
curl -X POST "https://app3.gwhats.app/api/v1/accounts/1/scheduled_messages" \
  -H "api_access_token: SEU_TOKEN" -H "Content-Type: application/json" \
  -d '{"inbox_id":5,"contact_id":789,"content":"Obrigado pelo interesse!","scheduled_at":"2026-04-15T10:00:00Z","title":"Lead Nurture - Dia 0"}'

# Toque 2 — 3 dias depois
curl -X POST "https://app3.gwhats.app/api/v1/accounts/1/scheduled_messages" \
  -H "api_access_token: SEU_TOKEN" -H "Content-Type: application/json" \
  -d '{"inbox_id":5,"contact_id":789,"content":"Teve chance de revisar as informações?","scheduled_at":"2026-04-18T10:00:00Z","title":"Lead Nurture - Dia 3"}'

# Toque 3 — 7 dias depois
curl -X POST "https://app3.gwhats.app/api/v1/accounts/1/scheduled_messages" \
  -H "api_access_token: SEU_TOKEN" -H "Content-Type: application/json" \
  -d '{"inbox_id":5,"contact_id":789,"content":"Oferta especial por tempo limitado!","scheduled_at":"2026-04-22T10:00:00Z","title":"Lead Nurture - Dia 7"}'

    Exemplo: mensagem recorrente semanal (toda segunda-feira)

    bash
    curl -X POST "https://app3.gwhats.app/api/v1/accounts/1/scheduled_messages" \
  -H "api_access_token: SEU_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "inbox_id": 5,
    "contact_id": 456,
    "content": "Bom dia! Aqui está sua newsletter semanal.",
    "scheduled_at": "2026-04-21T09:00:00Z",
    "title": "Newsletter Semanal",
    "recurrence_type": "weekly",
    "recurrence_interval": 1,
    "recurrence_days": [1],
    "recurrence_end_type": "never"
  }'

    Notas importantes

    • Datas devem estar no formato ISO 8601 em UTC
    • Não é possível agendar mensagens no passado
    • Máximo de 15 anexos por mensagem (use multipart/form-data)
    • Mensagens recorrentes criam automaticamente a próxima ocorrência após o envio
    • Excluir a mensagem pai interrompe todas as ocorrências futuras
    • Templates WhatsApp devem estar previamente aprovados na Meta
    • Status possíveis: pending → sent ou failed

    Códigos de Erro

    A API usa códigos HTTP padrão. Erros retornam um objeto JSON com detalhes.

    CódigoStatusSignificado
    200OKRequisição bem-sucedida
    201CreatedRecurso criado com sucesso
    204No ContentOperação realizada sem corpo de resposta
    400Bad RequestParâmetros inválidos ou ausentes
    401UnauthorizedToken ausente ou inválido
    403ForbiddenSem permissão para este recurso
    404Not FoundRecurso não encontrado
    422UnprocessableDados válidos mas não processáveis (ex: email duplicado)
    429Too Many RequestsLimite de requisições excedido — aguarde e tente novamente
    500Server ErrorErro interno — tente novamente em alguns instantes

    Formato de erro

    json
    {
  "error": "Recurso não encontrado",
  "description": "O contato com ID 999 não existe nesta conta."
}