Skip to main content

​
🎯 API de Funis (Kanban)

API para gerenciar funis de vendas e pipeline de conversas. Feature exclusiva da versão Ai Focus.

​
🔐 Autenticação

Header: api_access_token: SEU_TOKEN_AQUI

​
📋 Listar Funis

Liste todos os funis da conta.

​
Endpoint

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

​
Exemplo de Requisição

curl -X GET \
  'https://chat.seudominio.com/api/v1/accounts/1/funnels' \
  -H 'api_access_token: SEU_TOKEN' \
  -H 'Content-Type: application/json'

​
Resposta de Sucesso

[
  {
    "id": 1,
    "name": "Pipeline de Vendas B2B",
    "description": "Funil principal para vendas corporativas",
    "stages": [
      {
        "name": "Novo Lead",
        "order": 0,
        "color": "#3B82F6"
      },
      {
        "name": "Qualificação",
        "order": 1,
        "color": "#8B5CF6"
      },
      {
        "name": "Proposta",
        "order": 2,
        "color": "#F59E0B"
      },
      {
        "name": "Fechado",
        "order": 3,
        "color": "#10B981"
      }
    ],
    "conversations_count": 45,
    "total_value": 125000.00,
    "created_at": "2025-01-10T00:00:00Z"
  }
]

​
🔍 Buscar Funil por ID

Obtenha detalhes de um funil específico.

​
Endpoint

GET /api/v1/accounts/{account_id}/funnels/{funnel_id}

​
Resposta

{
  "id": 1,
  "name": "Pipeline de Vendas B2B",
  "description": "Funil principal para vendas corporativas",
  "stages": [...],
  "conversations_count": 45,
  "total_value": 125000.00,
  "metrics": {
    "conversion_rate": 15.5,
    "average_time_per_stage": {
      "Novo Lead": 24,
      "Qualificação": 48,
      "Proposta": 120
    }
  }
}

​
✨ Criar Funil

Crie um novo funil.

​
Endpoint

POST /api/v1/accounts/{account_id}/funnels

​
Body Parameters

CampoTipoObrigatórioDescrição
namestringSimNome do funil
descriptionstringNãoDescrição do funil
stagesarraySimLista de estágios

​
Exemplo de Requisição

curl -X POST \
  'https://chat.seudominio.com/api/v1/accounts/1/funnels' \
  -H 'api_access_token: SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Pipeline de Vendas B2C",
    "description": "Funil para vendas diretas ao consumidor",
    "stages": [
      {
        "name": "Novo Lead",
        "order": 0,
        "color": "#3B82F6"
      },
      {
        "name": "Contato",
        "order": 1,
        "color": "#8B5CF6"
      },
      {
        "name": "Proposta",
        "order": 2,
        "color": "#F59E0B"
      },
      {
        "name": "Fechado",
        "order": 3,
        "color": "#10B981"
      },
      {
        "name": "Perdido",
        "order": 4,
        "color": "#EF4444"
      }
    ]
  }'

​
🔄 Atualizar Funil

Atualize nome, descrição ou estágios.

​
Endpoint

PATCH /api/v1/accounts/{account_id}/funnels/{funnel_id}

​
Exemplo

curl -X PATCH \
  'https://chat.seudominio.com/api/v1/accounts/1/funnels/1' \
  -H 'api_access_token: SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Pipeline B2B Atualizado",
    "description": "Nova descrição"
  }'

​
🗑️ Deletar Funil

⚠️ Remove todas as conversas do funil!

​
Endpoint

DELETE /api/v1/accounts/{account_id}/funnels/{funnel_id}

​
🎨 Templates de Funil

Liste templates pré-configurados.

​
Endpoint

GET /api/v1/accounts/{account_id}/funnels/templates

​
Resposta

{
  "templates": [
    {
      "name": "Vendas B2B",
      "description": "Template para vendas corporativas",
      "stages": [...]
    },
    {
      "name": "Vendas B2C",
      "description": "Template para vendas diretas",
      "stages": [...]
    },
    {
      "name": "Suporte Técnico",
      "description": "Template para tickets de suporte",
      "stages": [...]
    }
  ]
}

​
📥 Criar Funil a Partir de Template

​
Endpoint

POST /api/v1/accounts/{account_id}/funnels/from_template

​
Body

{
  "template_name": "Vendas B2B",
  "name": "Meu Pipeline B2B"
}

​
📊 Kanban - Listar Conversas do Funil

Liste todas as conversas organizadas por estágio.

​
Endpoint

GET /api/v1/accounts/{account_id}/funnels/{funnel_id}/kanban/conversations

​
Query Parameters

ParâmetroTipoDescrição
stage_namestringFiltrar por estágio específico
pageintegerPágina (padrão: 1)
per_pageintegerItens por página (padrão: 25)

​
Exemplo de Requisição

curl -X GET \
  'https://chat.seudominio.com/api/v1/accounts/1/funnels/1/kanban/conversations' \
  -H 'api_access_token: SEU_TOKEN'

​
Resposta de Sucesso

{
  "stages": {
    "Novo Lead": {
      "count": 12,
      "total_value": 45000.00,
      "conversations": [
        {
          "id": 123,
          "contact": {
            "id": 45,
            "name": "João Silva",
            "email": "[email protected]"
          },
          "assignee": {
            "id": 1,
            "name": "Agente 1"
          },
          "stage_entered_at": "2025-01-16T10:00:00Z",
          "time_in_stage": 24,
          "products": [
            {
              "id": 1,
              "name": "Plano Premium",
              "value": 5000.00
            }
          ],
          "checklist": [
            {
              "item": "Validar CNPJ",
              "completed": true
            },
            {
              "item": "Enviar material",
              "completed": false
            }
          ],
          "labels": ["urgente", "enterprise"]
        }
      ]
    },
    "Qualificação": {
      "count": 8,
      "total_value": 32000.00,
      "conversations": [...]
    }
  },
  "total_conversations": 45,
  "total_value": 125000.00
}

​
📌 Conversas de um Estágio Específico

Liste apenas conversas de um estágio.

​
Endpoint

GET /api/v1/accounts/{account_id}/funnels/{funnel_id}/kanban/stage_conversations

​
Query Parameters

ParâmetroTipoObrigatórioDescrição
stage_namestringSimNome do estágio
pageintegerNãoNúmero da página

​
Exemplo

curl -X GET \
  'https://chat.seudominio.com/api/v1/accounts/1/funnels/1/kanban/stage_conversations?stage_name=Proposta&page=1' \
  -H 'api_access_token: SEU_TOKEN'

​
🔄 Mover Conversa Entre Estágios

Mova uma conversa de um estágio para outro.

​
Endpoint

POST /api/v1/accounts/{account_id}/funnels/{funnel_id}/kanban/move_conversation

​
Body Parameters

CampoTipoObrigatórioDescrição
conversation_idintegerSimID da conversa
stage_namestringSimNome do estágio destino
notesstringNãoNotas sobre a movimentação

​
Exemplo de Requisição

curl -X POST \
  'https://chat.seudominio.com/api/v1/accounts/1/funnels/1/kanban/move_conversation' \
  -H 'api_access_token: SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "conversation_id": 123,
    "stage_name": "Proposta",
    "notes": "Cliente solicitou proposta formal"
  }'

​
Resposta

{
  "success": true,
  "conversation_id": 123,
  "previous_stage": "Qualificação",
  "current_stage": "Proposta",
  "time_in_previous_stage": 48,
  "moved_at": "2025-01-16T14:00:00Z"
}

​
✅ Gerenciar Checklist

​
Adicionar Item ao Checklist

​
Endpoint

POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/funnel_mappings/{mapping_id}/add_checklist_item

​
Body

{
  "item": "Enviar proposta comercial"
}

​
Atualizar Item do Checklist

​
Endpoint

PATCH /api/v1/accounts/{account_id}/conversations/{conversation_id}/funnel_mappings/{mapping_id}/update_checklist_item

​
Body

{
  "index": 0,
  "completed": true
}

​
Remover Item do Checklist

​
Endpoint

DELETE /api/v1/accounts/{account_id}/conversations/{conversation_id}/funnel_mappings/{mapping_id}/remove_checklist_item

​
Body

{
  "index": 0
}

​
👥 Gerenciar Agentes no Funil

​
Atribuir Agente

​
Endpoint

POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/funnel_mappings/{mapping_id}/assign_agent

​
Body

{
  "agent_id": 2,
  "role": "collaborator"
}
Roles disponíveis:
  • owner - Responsável principal
  • collaborator - Colaborador
  • observer - Apenas observa

​
Remover Agente

​
Endpoint

POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/funnel_mappings/{mapping_id}/remove_agent

​
Body

{
  "agent_id": 2
}

​
⏱️ Gerenciar Timers

​
Iniciar Timer

POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/funnel_mappings/{mapping_id}/start_timer

​
Pausar Timer

POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/funnel_mappings/{mapping_id}/pause_timer

​
Resetar Timer

POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/funnel_mappings/{mapping_id}/reset_timer

​
📈 Métricas e Relatórios

​
Obter Métricas do Funil

​
Endpoint

GET /api/v1/accounts/{account_id}/funnels/{funnel_id}/metrics

​
Resposta

{
  "total_conversations": 45,
  "total_value": 125000.00,
  "average_ticket": 2777.78,
  "conversion_rate": 15.5,
  "stages_metrics": {
    "Novo Lead": {
      "count": 12,
      "value": 45000.00,
      "average_time": 24,
      "conversion_to_next": 66.7
    },
    "Qualificação": {
      "count": 8,
      "value": 32000.00,
      "average_time": 48,
      "conversion_to_next": 62.5
    },
    "Proposta": {
      "count": 5,
      "value": 28000.00,
      "average_time": 120,
      "conversion_to_next": 60.0
    },
    "Fechado": {
      "count": 3,
      "value": 20000.00,
      "average_time": 0
    }
  },
  "win_rate": 15.5,
  "loss_rate": 8.9,
  "average_deal_cycle": 192
}

​
💡 Exemplos Práticos

​
Criar Funil Completo

// Node.js
const axios = require('axios');

const API_URL = 'https://chat.seudominio.com/api/v1';
const TOKEN = 'SEU_TOKEN';

async function createFunnelWithStages() {
  const response = await axios.post(
    `${API_URL}/accounts/1/funnels`,
    {
      name: 'Pipeline de Vendas 2025',
      description: 'Funil principal para vendas',
      stages: [
        {
          name: 'Novo Lead',
          order: 0,
          color: '#3B82F6'
        },
        {
          name: 'Qualificação',
          order: 1,
          color: '#8B5CF6'
        },
        {
          name: 'Demo',
          order: 2,
          color: '#EC4899'
        },
        {
          name: 'Proposta',
          order: 3,
          color: '#F59E0B'
        },
        {
          name: 'Negociação',
          order: 4,
          color: '#F97316'
        },
        {
          name: 'Fechado',
          order: 5,
          color: '#10B981'
        },
        {
          name: 'Perdido',
          order: 6,
          color: '#EF4444'
        }
      ]
    },
    {
      headers: {
        'api_access_token': TOKEN,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}

​
Mover Múltiplas Conversas

# Python
import requests

API_URL = 'https://chat.seudominio.com/api/v1'
TOKEN = 'SEU_TOKEN'

def move_conversations_to_stage(funnel_id, conversation_ids, stage_name):
    headers = {
        'api_access_token': TOKEN,
        'Content-Type': 'application/json'
    }
    
    results = []
    for conv_id in conversation_ids:
        response = requests.post(
            f'{API_URL}/accounts/1/funnels/{funnel_id}/kanban/move_conversation',
            json={
                'conversation_id': conv_id,
                'stage_name': stage_name
            },
            headers=headers
        )
        results.append(response.json())
    
    return results

# Mover conversas 123, 124, 125 para "Proposta"
move_conversations_to_stage(1, [123, 124, 125], 'Proposta')

​
⚠️ Erros Comuns

​
404 - Funil não encontrado

{
  "error": "Funnel not found"
}

​
422 - Estágio inválido

{
  "error": "Stage 'XYZ' does not exist in this funnel"
}

​
409 - Conversa já está no funil

{
  "error": "Conversation is already in a funnel"
}

​
📚 Ver Também

Feature Exclusiva: Funis são uma customização da Ai Focus e não estão disponíveis no Chatwoot original.
Atenção: Deletar um funil remove todas as conversas vinculadas a ele. Essa ação é irreversível!