> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maketalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Bloco CRM Action
> Crie, mova ou feche deals no CRM do Chatwoot em pontos específicos do fluxo
## O que é o Bloco CRM Action?
O bloco **CRM Action** permite que o agente execute ações no **CRM do Chatwoot** durante a conversa — criar um novo deal, mover um deal existente para outra stage ou fechar como ganho/perdido. A IA escolhe quando executar a ação usando a ferramenta `execute_crm_action`, baseada no contexto e na posição do bloco no fluxo.
### Por que usar?
| Benefício | Descrição |
| --------------------------- | ---------------------------------------------------------------- |
| **Pipeline automatizado** | O CRM avança sozinho conforme a conversa evolui |
| **Sem entrada manual** | Vendedor não precisa clicar para mover o deal de stage |
| **Ganho/perda registrados** | Quando o cliente fecha (ou desiste), o deal é atualizado na hora |
| **Rastreabilidade** | Cada ação é registrada com origem `flow_builder` |
Para **criar um deal ao qualificar**, o bloco **Qualificação** já faz isso nativamente com a "Integração CRM". Use o CRM Action quando precisar de controle granular em outros pontos do fluxo (mover stage, fechar, criar um segundo deal, etc.).
***
## Quando usar
Use o bloco CRM Action nos momentos em que o **estado do negócio muda** na conversa. Exemplos típicos:
* Depois de enviar uma cotação → mover o deal para "Proposta enviada"
* Quando o cliente confirma compra → fechar como **ganho**
* Quando o cliente desiste explicitamente → fechar como **perdido** com motivo
* Quando um lead frio volta → criar novo deal no pipeline de reengajamento
***
## Como funciona
```
Fluxo chega no bloco CRM Action
↓
IA identifica que é o momento de executar a ação
↓
Chama execute_crm_action(action_id=)
↓
Sistema resolve a ação configurada:
• create_deal → POST /deals
• move_deal → encontra deal aberto + muda stage
• close_deal → encontra deal aberto + marca ganho/perdido
↓
Ação registrada no CRM com fonte "flow_builder"
```
Para **mover** ou **fechar** deals, o sistema usa `find_open_deal_for_conversation` para localizar automaticamente o deal aberto vinculado à conversa atual.
***
## Campos principais
### Identificação
| Campo | Descrição | Exemplo |
| -------------- | ------------------------------------------------------ | ----------------------------- |
| **ID da ação** | Identificador estável usado pela IA na chamada da tool | `crm_action_proposta_enviada` |
O **ID da ação** é referenciado pela IA (`execute_crm_action(action_id=...)`). Evite renomear depois que o fluxo estiver publicado — isso quebra a referência.
### Tipo de ação
Três variantes disponíveis:
| Ação | Descrição |
| --------------- | ------------------------------------------------ |
| **Criar deal** | Cria um novo deal no pipeline/stage configurados |
| **Mover deal** | Move o deal aberto da conversa para outra stage |
| **Fechar deal** | Fecha o deal aberto como ganho ou perdido |
### Campos por variante
**Criar deal:**
| Campo | Descrição | Exemplo |
| --------------------- | ---------------------------------- | ----------------------------------------------------- |
| **Pipeline** | Em qual pipeline criar | "Novos Leads" |
| **Stage inicial** | Stage onde o deal entra | "Qualificados" |
| **Título (template)** | Nome do deal, com placeholders | `{contact.name} — {flow_name}` |
| **Owner** | Dono do deal | Atendente da conversa (default) ou atendente fixo |
| **Valor** | Valor do deal (opcional) | 5000 |
| **Dados adicionais** | JSON extra com metadata (opcional) | `{"origem": "demo site", "campanha": "black-friday"}` |
**Mover deal:**
| Campo | Descrição |
| ----------------- | ------------------------------------- |
| **Pipeline** | Pipeline onde encontrar o deal aberto |
| **Stage destino** | Para onde mover |
**Fechar deal:**
| Campo | Descrição |
| ------------------- | -------------------------------------------- |
| **Outcome** | Ganho ou Perdido |
| **Motivo da perda** | Texto livre, apenas quando outcome = perdido |
Placeholders disponíveis no título do deal: `{contact.name}`, `{flow_name}`, `{lead_name}`.
***
## Exemplo de uso em fluxo
**Cenário — Pipeline B2B completo:**
```
[Roteador]
└── "Quer orçamento"
↓
[Qualificação] → cria deal na stage "Qualificado"
↓
[Cotação]
↓
[CRM Action: Proposta enviada] → move para "Proposta"
↓
[Condição LLM: Cliente aceitou?]
├── Sim → [CRM Action: Fechar como ganho] → [Handoff: financeiro]
└── Não → [CRM Action: Fechar como perdido] → fim
```
**Configuração do "CRM Action: Proposta enviada":**
* ID da ação: `crm_proposta_enviada`
* Tipo: **Mover deal**
* Pipeline: "Novos Leads"
* Stage destino: "Proposta"
Quando o fluxo chega nesse bloco (depois da cotação), a IA executa a ação e o deal já criado na Qualificação avança para a stage "Proposta" automaticamente.
***
## Boas práticas
* Use **ID de ação descritivo** — algo como `crm_proposta_enviada` ajuda a debugar, `crm_action_1` não.
* Para criar o **primeiro deal** do fluxo, prefira a **Integração CRM do bloco Qualificação**. O CRM Action é para ações subsequentes.
* Em fluxos com múltiplos pontos de fechamento (venda direta vs. transferência para humano), crie **um CRM Action para cada cenário**.
* O owner padrão (atendente da conversa) costuma ser a escolha certa — use "fixo" apenas quando o deal deve ir para uma pessoa específica independente de quem atende.
***
## Blocos relacionados
Cria o deal inicial ao qualificar o lead.
Decida entre ganho/perdido usando o modo LLM.
Transfira para humano depois de atualizar o deal.
Direcione leads para o fluxo comercial.