Ir para o conteúdo

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.

As rotas /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, select ou bool), 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.

json
{"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:

actionO que fazCampos
createCria um negócio na etapa stageId (ou na primeira aberta).title (obrigatório, até 200, aceita variáveis), valueCents, currency
moveLeva o negócio para stageId; numa etapa de ganho ou perda, ele fecha.stageId
wonLeva o negócio para a etapa de ganho.—
lostLeva o negócio para a etapa de perda.reason (obrigatório, até 500, aceita variáveis)
set_ownerTroca 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.

json
{"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:

bash
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. tags pode ficar vazio quando há crmStages.
  • stageIds: de 1 a 50, todas do funil. Uma etapa de outro funil responde 400 crm_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.