CRM
Funis, etapas, negócios e tarefas, e como os fluxos e as campanhas usam o CRM pela API.
O CRM fica na área do cliente, em CRM: os funis com as etapas em colunas (o kanban), os negócios de cada contato, as tarefas, os campos personalizados, a exportação e os relatórios. Ele mora na mesma API que os contatos, as conversas e os fluxos, então um fluxo mexe num negócio sem passar por ninguém.
/api/v1/crm/... não abrem com uma chave de API (wck_...): elas respondem 403 CLIENT_KEY_SCOPE. Na referência elas aparecem marcadas como da chave da plataforma. Pela sua chave, o CRM se usa pelos fluxos e pelas campanhas, como abaixo.O plano precisa incluir o CRM. Sem ele, os blocos de CRM de um fluxo esperam e tentam de novo a cada minuto (crm_not_in_plan), e a campanha por etapa responde 403 plan_feature_disabled.
Como o CRM funciona
- Funil: nasce com as etapas Novo, Qualificado, Proposta, Negociação, Ganho e Perdido. As etapas abertas ficam na ordem que você escolher; Ganho e Perdido ficam sempre no fim e não podem ser removidas.
- Negócio: fica num funil e numa etapa, com título, contato, valor em centavos e moeda (ISO 4217, padrão
USD), responsável, previsão de fechamento e a origem. Mover para Ganho ou Perdido fecha o negócio; perder pede um motivo. Entrar numa etapa aberta reabre. - Histórico: toda mudança fica no histórico do negócio, com quem fez. O que um fluxo faz aparece como
flow:<id do fluxo>. - Tarefas: o que fazer a seguir num negócio, com prazo e responsável; até 50 abertas por negócio. O cartão mostra a próxima.
- Campos personalizados: por negócio ou por contato, com tipo (
text,number,date,selectoubool), até 50 por entidade. - Exportação: a lista de negócios em CSV, com os filtros de agora, até 50.000 linhas.
- Relatórios: conversão e tempo por etapa, ganhos e perdas com os motivos, e o valor ganho por período e por responsável, num período de até 366 dias, em UTC. Moedas diferentes nunca se somam.
O CRM nos fluxos
Com uma chave com o escopo Fluxos (veja Fluxos), o grafo do fluxo pode usar:
O gatilho deal_stage_changed: o fluxo começa para o contato do negócio quando ele entra numa das etapas, ao ser movido, ganho, perdido, reaberto ou criado já nela.
{"type": "deal_stage_changed", "config": {"pipelineId": "<funil>", "stageIds": ["<Proposta>"], "fromStageIds": ["<Qualificado>"]}}fromStageIdsé opcional: com ele, só vale vindo de uma dessas etapas.- Cada entrada começa no máximo uma execução de cada fluxo; valem o opt-out e a execução ativa por contato. Um negócio sem contato não começa nada.
- No máximo uma execução por fluxo, negócio e etapa por minuto: um fluxo que tira o negócio da etapa e o põe de volta não se reinicia sozinho.
O bloco crm_deal, que age sobre o contato da execução no funil pipelineId:
action | O que faz | Campos |
|---|---|---|
create | Cria um negócio na etapa stageId (ou na primeira aberta). | title (obrigatório, até 200, aceita variáveis), valueCents, currency |
move | Leva o negócio para stageId; numa etapa de ganho ou perda, ele fecha. | stageId |
won | Leva o negócio para a etapa de ganho. | — |
lost | Leva o negócio para a etapa de perda. | reason (obrigatório, até 500, aceita variáveis) |
set_owner | Troca o responsável; "" tira. | owner (até 200, aceita variáveis) |
move, won, lost e set_owner agem sobre o negócio aberto mais recente do contato naquele funil. Sem negócio aberto, o bloco sai por not_found; as saídas são out e not_found.
A condição crm_stage: o contato tem um negócio aberto numa das stageIds (de 1 a 50) do funil? Sai por sim ou nao.
{"id": "proposta", "type": "crm_stage", "position": {"x": 0, "y": 200}, "data": {"pipelineId": "<funil>", "stageIds": ["<Proposta>"]}}As variáveis {{negocio.titulo}}, {{negocio.valor}}, {{negocio.moeda}}, {{negocio.etapa}}, {{negocio.etapaId}}, {{negocio.funil}}, {{negocio.funilId}} e {{negocio.id}} valem com o gatilho deal_stage_changed ou depois de um crm_deal. valor vem em unidades com duas casas (1500.00), vazio quando o negócio não tem valor.
Os ids do funil e das etapas são os do CRM da sua conta. O jeito mais simples é montar esses blocos no editor de fluxos da área do cliente, que lista os funis e as etapas; pela API, o grafo leva os mesmos ids. Um funil ou uma etapa que não existe mais termina a execução com crm_pipeline_not_found ou crm_stage_not_found.
A campanha para uma etapa
Com uma chave com o escopo Marketing (veja Marketing), o público de uma campanha pode ser os negócios abertos de algumas etapas:
curl -X POST "$API_URL/api/v1/marketing/campaigns" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Follow-up da proposta", "sender": {"instanceIds": ["<id do número>"]}, "audience": {"tags": [], "crmStages": {"pipelineId": "<funil>", "stageIds": ["<Proposta>", "<Negociação>"]}}, "message": {"type": "text", "text": "Olá {{nome}}, posso ajudar com a proposta?"}, "timezone": "America/Sao_Paulo", "window": {"start": "08:00", "end": "20:00"}, "ratePerMinute": 6, "scheduledAt": null}'- Entram os contatos dos negócios abertos nessas etapas; um negócio ganho ou perdido não conta.
- Com
tags, o público é a união dos dois, e cada contato entra uma vez.tagspode ficar vazio quando hácrmStages. stageIds: de 1 a 50, todas do funil. Uma etapa de outro funil responde400crm_stage_not_found.- A prévia e o opt-out são os de sempre, e o público é congelado ao iniciar ou agendar a campanha.
Para mover um negócio quando o contato responde a uma campanha, use um fluxo com o gatilho campaign_reply e o bloco crm_deal.
Os campos do contato
Os campos personalizados do contato também valem no Marketing: no PATCH /api/v1/marketing/contacts/<id> e na importação, as chaves do esquema do contato são conferidas pelo tipo (400 field_invalid; na importação, a linha é descartada com o motivo field_invalid:<chave>). As chaves fora do esquema continuam livres.