Mensageria — Visão Geral
Mensageria — Visão geral
Pré-requisito: o telefone do WhatsApp Business do tenant precisa ser cadastrado (configuração de telefone) antes de criar qualquer configuração de mensageria que utilize o canal WhatsApp em uma fase. Sem esse cadastro, a criação de uma regra com canal WhatsApp falha por não localizar o número informado.
Endpoints deste domínio
| Método | Caminho | Descrição |
|---|---|---|
POST | /v1/flows/{flowId}/phone-config | Cadastra o telefone WhatsApp Business do flow |
GET | /v1/flows/{flowId}/phases/{phaseId}/messaging-config | Consulta a configuração de mensageria da fase |
POST | /v1/flows/{flowId}/phases/{phaseId}/messaging-config | Cria a configuração de mensageria da fase |
PUT | /v1/flows/{flowId}/phases/{phaseId}/messaging-config | Atualiza contatos e variáveis de template da configuração |
POST | /v1/flows/{flowId}/phases/{phaseId}/messaging-config/rules | Adiciona regras de disparo à configuração |
PUT | /v1/flows/{flowId}/phases/{phaseId}/messaging-config/rules/{ruleId} | Atualiza uma regra específica |
DELETE | /v1/flows/messaging-config/{id} | Remove a configuração de mensageria da fase |
Nota sobre nomenclatura: o endpoint de remoção não recebe o identificador do flow nem da fase no caminho — apenas o identificador da própria configuração de mensageria ( id), obtido previamente pela consulta da configuração da fase.
Estrutura da configuração
contacts.default[] são contatos fixos (estáticos); contacts.fields[] são contatos dinâmicos, resolvidos em tempo de execução a partir de um campo do card ou do formulário de entrada.{{1}}, {{2}}...) e compartilhadas por todos os canais das regras.channels[]) com condições (conditions[]).Sequência recomendada de configuração
1.
POST .../phone-config), caso ainda não exista para a empresa.2.
POST .../messaging-config), com os contatos e, se necessário, as variáveis de template.3.
POST .../messaging-config/rules).4.
Comportamentos importantes
rules[] fica inerte — pelo menos uma regra é necessária para que uma mensagem seja efetivamente enviada.name, não type — por exemplo, {name: 'whatsapp', templateId: '...', setup: {phoneId: '...'}}.phone-config) é vinculado à empresa (tenant), não a um flow individualmente, e a chamada é idempotente: se o telefone já existir, a API responde com sucesso indicando que o registro já existia.contacts.default é obrigatório mesmo quando não há nenhum contato fixo — nesse caso, envie um array vazio.contacts.fields[] precisa de uma description não vazia — omiti-la ou enviá-la em branco retorna erro de validação.fields, no nível raiz da configuração, também é obrigatório mesmo vazio — envie um array vazio quando a mensagem não utilizar variáveis dinâmicas no corpo, como em notificações fixas de aprovação ou reprovação.PUT da configuração), o campo type de contacts.fields[] aceita um conjunto mais restrito de valores do que na criação — utilize sempre 'default' para os contatos-padrão (nome, telefone, e-mail).contacts.default[] precisa ter um telefone não vazio, mesmo para contatos que devem receber a mensagem apenas por e-mail; nesse caso, utilize um número de telefone fictício em formato válido.fields[] raiz precisa do campo required informado explicitamente (true ou false).PUT .../rules/{ruleId}), o identificador da regra vai apenas na URL — incluí-lo também no corpo da requisição retorna erro de validação.setup.phoneId apontando para um telefone previamente cadastrado; sua ausência retorna erro 404.Modificado em 2026-07-28 20:38:32