# Levantamento CRM Linkia — PX3 LAB
## Sistema de Notificações Automáticas via WhatsApp

**Data do levantamento:** 2026-07-07  
**Location ID:** W7PGxpfbsFaEEUoQOtUb  
**Executado por:** Amanda (Gerente CRM Linkia)

---

## 1. USUÁRIOS DA SUBCONTA

Total de usuários encontrados: **8**

| Nome | Email | ID no CRM | Telefone/WhatsApp | Role |
|------|-------|-----------|-------------------|------|
| Monique Miranda | monique@px3lab.com.br | `FKCKhrtdwZjHS6ISgAFF` | **+55 11 93431-3883** | admin |
| Mary Oliveira | mary@px3lab.com.br | `n2TXqcFucc2mSfK5p0Do` | **+55 11 98531-8465** | user |
| Naiane Nascimento | naiane@px3lab.com.br | `0ZFCVED2VANUkXjfB4tL` | nao cadastrado | user |
| Eduardo Faria | eduardo.faria@ggvinteligencia.com.br | `MB5OrUBhTca9hbrunaQB` | nao cadastrado | user |
| Vinícius Amaral | vinicius@px3lab.com.br | `3egsMwQ3G5rHFHVhp555` | +55 11 99231-1361 | user |
| Vinícius ADMIN | vinicius@pixeltres.com.br | `PHjPxMsAxfFL43kzANLf` | nao cadastrado | admin |
| Renato Moraes | renato@px3lab.com.br | `BaTfAnfmGglY1wDQttrX` | +55 15 99650-5958 | user |
| Renato ADMIN | remoraes09@gmail.com | `ac04q9LetfURwWyQZ748` | nao cadastrado | admin |

### Observacoes importantes sobre usuarios:
- **Monique** e **Mary** sao as responsaveis operacionais que precisam de notificacao - ambas tem WhatsApp cadastrado.
- **Naiane** NAO tem telefone cadastrado no CRM. Para notifica-la via WhatsApp, precisamos do numero dela ou usar o email como fallback.
- Eduardo Faria tem email corporativo externo (ggvinteligencia), provavelmente parceiro/consultor.
- O campo `lcPhone` retornou vazio para todos os usuarios (objeto `{}`), ou seja, os numeros estao no campo `phone` do perfil, nao no lcPhone.

---

## 2. WEBHOOKS EXISTENTES NA SUBCONTA

**Resultado:** O endpoint `/webhooks/` retorna HTTP 404 para tokens do tipo Private Integration (pit-token). Esse endpoint da API GHL v2 so esta disponivel para apps OAuth (tokens gerados via fluxo de autorizacao de marketplace).

- Nao foi possivel listar webhooks via API com as credenciais atuais (pit-token).
- **Para verificar webhooks existentes:** acessar o painel do CRM Linkia > Settings > Integrations > Webhooks.
- **Alternativa tecnica:** usar a API de OAuth App se for necessario gerenciar webhooks programaticamente.

### Endpoints testados (todos 404 com pit-token):
- `GET /webhooks/?altId={locationId}&altType=location`
- `GET /webhooks/?locationId={locationId}`
- `GET /locations/{locationId}/webhooks`
- `GET /hooks/?locationId={locationId}`

---

## 3. EVENTOS DISPONIVEIS PARA WEBHOOK

Com base na documentacao da API GHL e no comportamento confirmado pelos workflows existentes na subconta, os eventos de webhook disponíveis para configurar na interface sao:

### Eventos de Contato
- `ContactCreate` — novo contato criado
- `ContactUpdate` — contato atualizado (inclui quando uma tag e adicionada)
- `ContactDelete` — contato excluido
- `ContactDndUpdate` — DND (Do Not Disturb) atualizado
- `ContactTagUpdate` — tag adicionada ou removida de um contato (**relevante para o trigger de 36h**)

### Eventos de Conversa / Mensagens
- `ConversationUnreadUpdate` — atualizacao de mensagens nao lidas
- `InboundMessage` — mensagem recebida (entrada)
- `OutboundMessage` — mensagem enviada (saida)
- `ConversationProviderOutboundMessage` — mensagem via provedor
- `ConversationUpdate` — atualizacao de status da conversa (**relevante para trigger de 24h**)

### Eventos de Oportunidade (Pipeline)
- `OpportunityCreate` — nova oportunidade criada
- `OpportunityUpdate` — oportunidade atualizada
- `OpportunityDelete` — oportunidade excluida
- `OpportunityStageUpdate` — mudanca de stage
- `OpportunityStatusUpdate` — mudanca de status (open, won, lost, abandoned)
- `OpportunityMonetaryValueUpdate` — valor monetario atualizado
- `OpportunityAssignedToUpdate` — responsavel atualizado

### Eventos de Agendamento
- `AppointmentCreate` — agendamento criado
- `AppointmentUpdate` — agendamento atualizado
- `AppointmentDelete` — agendamento excluido

### Eventos de Formulario/Nota
- `FormSubmission` — formulario enviado
- `SurveySubmission` — pesquisa enviada
- `NoteCreate` — nota criada
- `TaskCreate` — task criada

### Avaliacao para os triggers desejados:

| Trigger | Evento recomendado | Viabilidade |
|---------|-------------------|-------------|
| Ultima mensagem (24h sem resposta) | `InboundMessage` ou `ConversationUpdate` | Viavel via webhook externo com logica de timer |
| Tag "INICIOU FLUXO DE COMPRA CLOUD" (36h) | `ContactTagUpdate` | Viavel via webhook + filtro por nome da tag |

> **Atencao:** O evento de "conversa encerrada" (como status "closed") e capturado via `ConversationUpdate` — o payload incluira o novo status. Nao existe um evento especifico `ConversationClosed`.

---

## 4. CAMPO "assignedTo" NOS CONTATOS

**Confirmado:** o campo se chama `assignedTo` e contem o **ID do usuario** responsavel pelo contato.

### Estrutura JSON do contato (campo relevante):

```json
{
  "id": "JBwOgxUfE99lD1DBLqeA",
  "contactName": "moments eventos",
  "firstName": "Moments",
  "lastName": "Eventos",
  "locationId": "W7PGxpfbsFaEEUoQOtUb",
  "assignedTo": "n2TXqcFucc2mSfK5p0Do",
  "phone": null,
  "email": null,
  "tags": [],
  "type": "lead",
  "source": null,
  "dnd": false,
  "dateAdded": "2026-06-24T14:00:16.404Z",
  "dateUpdated": "2026-06-24T14:06:38.193Z",
  "country": "BR",
  "customFields": [...],
  "opportunities": [
    {
      "pipelineId": "Pj7dm7v7AJqUPiG7UESq",
      "id": "N8StJp5t4Efx1VOPynlx",
      "monetaryValue": 0,
      "pipelineStageId": "f0ac38d7-d85f-4a2a-82c5-1d1976125e9b",
      "status": "open"
    }
  ]
}
```

### Mapeamento assignedTo -> WhatsApp para notificacoes:

```python
ASSIGNED_TO_WHATSAPP = {
    "FKCKhrtdwZjHS6ISgAFF": "+5511934313883",  # Monique Miranda
    "n2TXqcFucc2mSfK5p0Do": "+5511985318465",  # Mary Oliveira
    "0ZFCVED2VANUkXjfB4tL": None,              # Naiane Nascimento — sem telefone
    "3egsMwQ3G5rHFHVhp555": "+5511992311361",  # Vinicius Amaral
    "BaTfAnfmGglY1wDQttrX": "+5515996505958",  # Renato Moraes
}
```

> **Observacao:** Naiane nao tem numero cadastrado. Precisa confirmar o numero com a Monique antes de incluir no sistema.

---

## 5. TOTAL DE CONTATOS NA SUBCONTA

- **Total:** 4.523 contatos ativos
- **Com assignedTo preenchido:** 19 contatos (campo ainda pouco utilizado)
- **Base de dados relevante:** contatos recebem tags como identificadores de estado no funil

---

## 6. WORKFLOWS EXISTENTES (resumo relevante)

Existem 23 workflows na subconta. Os mais relevantes para o contexto de notificacoes:

| Status | Nome | ID |
|--------|------|----|
| published | SDR MARIA: LEAD RESPONDEU (Claude) | `eb069475-ac5a-4c83-81b2-4750a0a28261` |
| published | RESPONDEU "MAIS INFORMACOES" | `c161b6ca-e942-4388-aa6d-6e7261884495` |
| published | LEADS QUE ENTRAM DA PROSPECCAO ATIVA | `d2995d50-9465-43ae-be39-6b0821aedf1f` |
| published | NOVOS LEADS FORMULARIO CLOUD | `bb6d2413-3bdb-484e-9e5d-5ef0d5dd5521` |
| published | WORKFLOW: SDR MARIA — FOLLOW-UP | `56262622-3eae-44bf-8a6a-839aee8bffcb` |
| draft | RESPOSTA VENDEDOR WHATSAPP | `2785f2b0-393f-43b6-8226-09034334513e` |

---

## 7. RECOMENDACOES PARA O SISTEMA DE NOTIFICACOES

### Arquitetura sugerida:

```
Webhook Externo (endpoint proprio)
  |
  ├── Evento: InboundMessage (lead enviou mensagem)
  |     -> Iniciar timer de 24h
  |     -> Se nao houver OutboundMessage em 24h, notificar vendedor via WPP
  |
  └── Evento: ContactTagUpdate (tag adicionada)
        -> Filtrar: tag == "INICIOU FLUXO DE COMPRA CLOUD"
        -> Iniciar timer de 36h
        -> Se tag ainda presente em 36h, notificar vendedor via WPP
```

### Variaveis necessarias para implementar:

1. **Numero da Naiane** — confirmar com Monique
2. **URL do endpoint webhook** — servidor para receber os eventos
3. **Canal de envio WPP** — verificar se a subconta tem numero WPP ativo para envio via API
4. **Logica de deduplicacao** — evitar multiplas notificacoes para o mesmo lead

### Como configurar webhook na interface:
> CRM Linkia > Settings > Integrations > Webhooks > Add New Webhook  
> Selecionar eventos: `ContactTagUpdate`, `InboundMessage`, `ConversationUpdate`  
> Endpoint: URL do servidor externo

---

*Documento gerado em 2026-07-07 | Amanda — Gerente CRM Linkia*