WhatsApp Hub (NooviConnect)

Endpoints do motor WhatsApp embutido (NooviConnect): gestão de sessões, grupos, canais e relatórios agregados. O {inbox_id} é o id da inbox NooviConnect. Requer a feature Hub WhatsApp ativa na conta e api_access_token.

Capability por provider

Endpoints de grupos/canais exigem um provider com suporte (NooviConnect). Inbox sem suporte retorna 422; inbox de outra conta retorna 404 (isolamento multi-tenant).

Visão Geral

Todos os caminhos abaixo são prefixados por /api/v1/accounts/{account_id}/noovi_connect/{inbox_id}.

Sessões

GET/api/v1/accounts/{account_id}/noovi_connect

Lista as sessões NooviConnect da conta (status, telefone, inbox, device).

GET/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/status

Status da sessão (stopped | starting | scan_qr_code | working | failed).

GET/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/qr

QR code atual da sessão (para parear o WhatsApp).

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/refresh_qr

Gera um novo QR code.

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/request_pairing_code

Solicita código de pareamento por telefone (alternativa ao QR).

Body

Nome	Tipo	Obrigatorio	Descricao
`phone`	`string`	Sim	Telefone E.164 (ex.: 5511999999999)

Validação e Presença

GET/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/check_number

Verifica se um número possui WhatsApp ativo (retorna o resultado do motor).

Query

Nome	Tipo	Obrigatorio	Descricao
`phone`(query)	`string`	Sim	Telefone E.164 (ex.: 5511999999999). Não-dígitos são removidos.

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/chat_presence

Envia presença (digitando / parou de digitar) para um contato.

Body

Nome	Tipo	Obrigatorio	Descricao
`phone`	`string`	Sim	Telefone E.164 do contato
`presence_action`	`string`	Sim	typing \| composing iniciam 'digitando'; qualquer outro valor para a digitação

json

{ "message": "Presence sent" }

Mensagens ricas

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/send_poll

Envia uma enquete para um contato.

Body

Nome	Tipo	Obrigatorio	Descricao
`phone`	`string`	Sim	Telefone do contato (ou JID completo com @)
`question`	`string`	Sim	Pergunta da enquete
`options`	`string[]`	Sim	Opções da enquete (mínimo 2)
`max_answer`	`integer`	Nao	Máximo de respostas; > 1 habilita seleção múltipla (limitado ao número de opções). Padrão 1.

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/send_location

Envia uma localização para um contato.

Body

Nome	Tipo	Obrigatorio	Descricao
`phone`	`string`	Sim	Telefone do contato (ou JID completo com @)
`latitude`	`string`	Sim	Latitude
`longitude`	`string`	Sim	Longitude
`title`	`string`	Nao	Título/rótulo da localização

Perfil

GET/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/profile

Retorna o perfil da conta de WhatsApp conectada (id, nome e URL da foto).

json

{ "id": "5511999999999@c.us", "name": "Atendimento Noovi", "picture": "https://..." }

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/set_pushname

Altera o nome de exibição (push name) do perfil da sessão.

Body

Nome	Tipo	Obrigatorio	Descricao
`push_name`	`string`	Sim	Novo nome de exibição

json

{ "message": "Profile name updated" }

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/set_profile_status

Altera o recado/status (about) do perfil da sessão.

Body

Nome	Tipo	Obrigatorio	Descricao
`status`	`string`	Sim	Novo recado (about)

json

{ "message": "Profile status updated" }

Foto e privacidade

Definir foto de perfil (set_avatar) e ler configurações de privacidade (privacy_settings) não são suportados pelo motor atual — ver Não suportados (501).

Chamadas

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/reject_call

Rejeita uma chamada de WhatsApp recebida. call_id e from vêm dos metadados da atividade de chamada.

Body

Nome	Tipo	Obrigatorio	Descricao
`call_id`	`string`	Sim	ID da chamada recebida
`from`	`string`	Sim	JID/telefone de origem da chamada

json

{ "message": "Call rejected" }

Grupos

GET/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/groups

Lista os grupos do WhatsApp da sessão (jid, nome, participants_count).

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/create_group

Cria um grupo.

Body

Nome	Tipo	Obrigatorio	Descricao
`title`	`string`	Sim	Nome do grupo
`participants`	`string[]`	Sim	Telefones dos participantes

GET/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/group_participants

Lista participantes de um grupo (shape normalizado).

Query

Nome	Tipo	Obrigatorio	Descricao
`group_jid`(query)	`string`	Sim	JID do grupo (...@g.us)

json

[
  {
    "jid": "5511999999999@s.whatsapp.net",
    "phone_number": "5511999999999",
    "display_name": "Fulano",
    "is_admin": true,
    "is_super_admin": false
  }
]

GET/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/group_picture

Obtém a URL da foto de um grupo (null quando não houver).

Query

Nome	Tipo	Obrigatorio	Descricao
`group_jid`(query)	`string`	Sim	JID do grupo (...@g.us)

json

{ "url": "https://..." }

GET/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/group_invite_link

Obtém o link de convite do grupo (shape normalizado).

Query

Nome	Tipo	Obrigatorio	Descricao
`group_jid`(query)	`string`	Sim	JID do grupo

json

{
  "invite_link": "https://chat.whatsapp.com/ABCDEF123456",
  "invite_code": "ABCDEF123456"
}

GET/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/group_info_from_link

Obtém informações de um grupo a partir de um link de convite (sem entrar).

Query

Nome	Tipo	Obrigatorio	Descricao
`link`(query)	`string`	Sim	Link de convite do grupo (https://chat.whatsapp.com/...)

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/join_group_with_link

Entra em um grupo a partir de um link de convite.

Body

Nome	Tipo	Obrigatorio	Descricao
`link`	`string`	Sim	Link de convite do grupo

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/set_group_name

Altera o nome do grupo. Body: group_jid, name.

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/set_group_topic

Altera o tópico/descrição. Body: group_jid, topic.

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/set_group_photo

Altera/remove a foto (multipart). Body: group_jid, image.

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/set_group_locked

Bloqueia/desbloqueia a edição das infos do grupo (apenas admins). Body: group_jid, locked (boolean).

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/set_group_announce

Ativa/desativa o modo somente-admins-enviam-mensagens. Body: group_jid, announce (boolean).

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/leave_group

Sai do grupo. Body: group_jid.

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/add_participants

Adiciona participantes. Body: group_jid, phones[].

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/remove_participants

Remove participantes. Body: group_jid, phones[].

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/promote_participants

Promove a admin. Body: group_jid, phones[].

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/demote_participants

Rebaixa de admin. Body: group_jid, phones[].

Solicitações de entrada não suportadas

As rotas participant_requests, approve_participant_requests e reject_participant_requests existem, mas o motor atual retorna 501 Not Implemented. Ver Não suportados (501).

Etiquetas (WhatsApp Business)

Etiquetas do WhatsApp Business da conta conectada — distintas das etiquetas de conversa nativas do NooviChat. Existem apenas em contas WhatsApp Business; contas pessoais retornam lista vazia.

GET/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/labels

Lista as etiquetas do WhatsApp Business (id, nome, cor).

json

[
  { "id": "1", "name": "Clientes", "color": 0, "colorHex": "#ff9485" }
]

GET/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/label_chats

Lista os chats marcados com uma etiqueta.

Query

Nome	Tipo	Obrigatorio	Descricao
`label_id`(query)	`string`	Sim	Identificador da etiqueta

Canais (Newsletters)

GET/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/newsletters

Lista os canais (newsletters) seguidos pela sessão.

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/unfollow_newsletter

Deixa de seguir um canal. Body: newsletter_id.

Criação de canal

A criação de canal não é exposta pelo motor — apenas listar e deixar de seguir.

Relatórios

GET/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/hub_report

Resumo agregado da sessão (grupos, canais, participantes, transmissões e atividade dos últimos 30 dias).

json

{
  "summary": {
    "groups": 29,
    "communities": 0,
    "channels": 4,
    "participants": 2471,
    "messages": 1840,
    "active_broadcasts": 0,
    "total_broadcasts": 12,
    "events": 35
  },
  "activity": { "messages": 1840, "replies": 720, "reactions": 96 },
  "top_participants": []
}

Estrutura da resposta

A resposta não tem wrapper data: os campos de topo são summary, activity e top_participants. As métricas de activity (messages/replies/reactions) e o campo summary.messages/summary.events são apurados a partir dos eventos nativos (ReportingEvent) dos últimos 30 dias no fuso da conta — degradam para 0 quando não há motor disponível. top_participants é sempre uma lista vazia no momento.

Não suportados (501)

As rotas abaixo existem por compatibilidade, mas o motor WhatsApp atual (GOWS) não as implementa: respondem 501 Not Implemented com { "error": "Operation not supported by the WhatsApp engine (GOWS)" }. Não dependa delas em integrações.

GET/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/privacy_settings

Configurações de privacidade — não suportado (501).

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/set_avatar

Definir foto de perfil — não suportado (501).

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/pin_chat

Fixar conversa — não suportado (501).

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/archive_chat

Arquivar conversa — não suportado (501).

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/set_disappearing_timer

Timer de mensagens temporárias — não suportado (501).

GET/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/participant_requests

Listar solicitações de entrada em grupo — não suportado (501).

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/approve_participant_requests

Aprovar solicitações de entrada — não suportado (501).

POST/api/v1/accounts/{account_id}/noovi_connect/{inbox_id}/reject_participant_requests

Rejeitar solicitações de entrada — não suportado (501).

Transmissão para grupos

Para disparar para grupos, crie um broadcast com source_type: "whatsapp_group" e broadcast_targets (ver API de Disparos):

json

{
  "broadcast": {
    "name": "Aviso grupos",
    "source_type": "whatsapp_group",
    "inbox_ids": [123],
    "broadcast_targets": [
      { "target_kind": "group", "provider_jid": "12345@g.us", "metadata": { "name": "Meu Grupo" } }
    ],
    "message_payload": { "messages": [{ "type": "text", "content": "Olá!" }] }
  }
}