Disparo ativo

Inicia uma conversa de WhatsApp a partir do seu sistema, com um template aprovado e um fluxo de qualificação alternativo.

Inicia uma conversa com um lead a partir de um sistema seu. É o caminho usado quando o lead não chegou pelo WhatsApp: veio de um formulário, de uma importação, de uma campanha ou de um ERP.

A chamada envia um template aprovado do WhatsApp e vincula a conversa a um fluxo ativo — um fluxo de qualificação alternativo, próprio para conversas que a empresa começa.

POST /api/active-flows/run
Authorization: Bearer elv_...
Content-Type: application/json

Corpo da requisição#

Campo	Tipo	Obrigatório	Descrição
`activeFlowId`	string	sim	Fluxo ativo a executar.
`templateId`	string	sim	Template do WhatsApp enviado como primeira mensagem.
`destination`	string	sim	Telefone do lead, no formato `55DDDNNNNNNNN`.
`parameters`	array	não	Valores das variáveis `{{1}}`, `{{2}}`… do template, na ordem.
`contactId`	string	não	Contato já existente no Modari. Exclusivo com `contact`.
`contact`	objeto	não	Dados para criar um contato novo. Exclusivo com `contactId`.

contactId e contact são mutuamente exclusivos: envie um ou outro. Sem nenhum dos dois, a conversa é aberta apenas com o número de destino.

Objeto `contact`#

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim	Nome do contato.
`phone`	string	não	Telefone no formato `55DDDNNNNNNNN`. Omitido, usa `destination`.
`email`	string	não	E-mail válido.
`title`	string	não	Cargo do contato.
`notes`	string	não	Observações livres.
`origin`	string	não	Origem do contato.
`referralSource`	string	não	Fonte da indicação, por exemplo `google`.
`utmMedium`	string	não	UTM medium da campanha de origem.
`utmCampaign`	string	não	UTM campaign da campanha de origem.
`country`, `state`, `city`	string	não	Localização do contato.
`facebook`, `linkedin`	string	não	Perfis sociais.
`birthday`	data	não	Data de nascimento, em ISO 8601.
`customFields`	array	não	Campos personalizados. Ver abaixo.

Campos personalizados#

Cada item de customFields tem key, label, type e value. A chave precisa corresponder a um campo personalizado já configurado para a empresa.

{
  "key": "faixa_investimento",
  "label": "Faixa de investimento",
  "type": "text",
  "value": "30 a 50 mil"
}

Exemplo — contato novo#

{
  "activeFlowId": "507f1f77bcf86cd799439011",
  "templateId": "507f191e810c19729de860ea",
  "destination": "5511999999999",
  "parameters": ["Ana", "cozinha planejada"],
  "contact": {
    "name": "Ana Souza",
    "email": "ana@exemplo.com.br",
    "city": "Florianópolis",
    "state": "SC",
    "utmCampaign": "black-friday-2025",
    "customFields": [
      { "key": "faixa_investimento", "label": "Faixa de investimento", "type": "text", "value": "30 a 50 mil" }
    ]
  }
}

Exemplo — contato existente#

{
  "activeFlowId": "507f1f77bcf86cd799439011",
  "templateId": "507f191e810c19729de860ea",
  "destination": "5511999999999",
  "contactId": "6512c0f2a3b1d4e5f6a7b8c9"
}

Resposta#

{
  "status": 201,
  "success": true
}

success: true significa que o template foi aceito para envio pelo WhatsApp. A entrega ao aparelho do lead é assíncrona e depende da operadora e das políticas da Meta.

Exemplo com curl#

curl -X POST "https://moveis-api.smarktech.app.br/api/active-flows/run" \
  -H "Authorization: Bearer $MODARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "activeFlowId": "507f1f77bcf86cd799439011",
    "templateId": "507f191e810c19729de860ea",
    "destination": "5511999999999",
    "parameters": ["Ana"],
    "contact": { "name": "Ana Souza" }
  }'

Depois do disparo#

A conversa passa a existir no painel como qualquer outra. O lead responde ao template e o agente assume a partir do fluxo ativo vinculado — mesma mecânica descrita em Qualificação, incluindo follow-up se o lead ficar em silêncio.

Erros comuns#

Situação	Resposta
`destination` fora do formato `55DDDNNNNNNNN`	`400` com a mensagem do campo
`activeFlowId` ou `templateId` que não existem na sua empresa	`404`
API key revogada por uma geração mais recente	`401`
`contactId` e `contact` enviados juntos	`400`