Como usar a API da Papo para gerenciar Flows de automação

Abrir em

Ver como Markdown

Abrir no ChatGPT Abrir no Claude

Vitor

Última atualização em Oct 19, 2026

Com a API REST da Papo, você pode listar todos os flows disponíveis na sua conta, ativar ou desativar jornadas e matricular contatos em automações de forma programática — tudo por requisições autenticadas, sem abrir o painel. É a maneira de integrar o motor de flows com sistemas externos, workflows de n8n, CRMs ou scripts internos.

A API da Papo expõe recursos de flows que permitem gerenciar automações assim como você já gerencia caixas de entrada ou contatos. Com ela, equipes de desenvolvimento, integradores e revendedores white label conseguem controlar em lote quais jornadas estão ativas, iniciar contatos em sequências e sincronizar o status das automações com processos de negócio.

Resumo das operações de Flow via API

Operação	Descrição	Exemplo de uso
Listar flows	Retorna os flows e sequências disponíveis, com identificador, nome, tipo e status (Ativo/Inativo).	Auditar automações, sincronizar com dashboards externos ou verificar o que está em execução.
Ativar/desativar flow	Altera o status de um flow específico, liberando ou pausando o recebimento e processamento de contatos.	Pausar uma jornada durante manutenção, liberar após ajustes ou desativar uma campanha encerrada.
Matricular contato	Insere um contato existente no início de um flow ativo, dando início à jornada configurada.	Incluir leads do CRM externo, disparar um fluxo de boas‑vindas após integração ou corrigir entradas manuais.

Como funciona a autenticação da API

Todas as chamadas à API, inclusive as que envolvem flows, exigem a chave secreta da conta. Ela deve ser enviada como token Bearer no cabeçalho Authorization. A chave pública da conta é opcional, mas se enviada precisa corresponder à mesma conta da chave secreta.

A URL base da API é https://app.papo.global/api/v1. As chaves são geradas na área de desenvolvedor do painel da Papo. A chave secreta aparece uma única vez na criação; guarde‑a em local seguro e revogue se houver suspeita de vazamento.

O padrão de autenticação é o mesmo usado em todos os endpoints:

curl https://app.papo.global/api/v1/me \
  -H "Authorization: Bearer sk_live_…" \
  -H "X-Papo-Public-Key: pk_live_…"

Gerenciando flows via API na prática

Embora os detalhes exatos de cada endpoint e parâmetros estejam na documentação oficial da API, o fluxo geral de trabalho segue estes passos conceituais:

Autentique-se com a chave secreta (e, se desejar, a chave pública) para validar a conta.
Liste os flows para obter a relação atual de jornadas, incluindo seus identificadores e status. Isso permite mapear o que já existe e escolher o flow correto para as próximas operações.
Altere o status de um flow específico, se necessário. Envie uma requisição que defina o flow como ativo (liberado para receber contatos) ou inativo (pausado). Apenas flows ativos processam contatos e aceitam matrículas.
Matricule um contato em um flow ativo. Informe o identificador do contato e o identificador do flow desejado para inseri‑lo no início da jornada. O histórico do contato no CRM é preservado.
Integre com sistemas externos — por meio de webhooks ou chamadas diretas, você pode iniciar contatos vindos de um formulário externo, um evento em outro sistema ou um pipeline de dados.

A plataforma também suporta a criação de flows vazios e inativos e o preenchimento de seus nós via API, possibilitando provisionar automações completas de forma programática. Para os formatos exatos de payload, campos obrigatórios e exemplos de código, consulte a seção de flows na documentação da API Papo.

Para quem essa integração faz sentido

Equipes de TI que operam múltiplas automações e precisam pausar, reativar ou monitorar flows em lote sem acessar o painel manualmente.
Revendedores white label que desejam provisionar journeys padronizadas para cada novo cliente automaticamente, matricular contatos iniciais e manter alinhamento entre plataformas.
Integradores e desenvolvedores que conectam a Papo a CRMs, ERPs ou ferramentas como n8n, acionando flows a partir de eventos externos (uma compra, um cadastro, um agendamento).
Operações que trabalham com matrícula condicional, onde contatos são incluídos em flows somente após passarem por regras de negócio definidas em outros sistemas.

Perguntas frequentes

Preciso da chave secreta para listar os flows?

Sim. A listagem de flows, assim como qualquer operação que retorna dados da conta, requer autenticação com a chave secreta. O padrão é o mesmo de todos os outros endpoints: envie o token Bearer no cabeçalho Authorization.

Posso ativar ou desativar um flow pela API?

Sim. A API permite alterar o status de um flow entre ativo e inativo. Você precisa do identificador do flow e da chave secreta. Flows inativos não recebem contatos e não avançam na jornada, mesmo que uma matrícula seja tentada.

Como faço para matricular um contato em um flow via API?

Forneça o identificador do contato e o identificador do flow ativo na chamada de matrícula. O contato será inserido no início da jornada, sem apagar o histórico de conversas ou dados do perfil. A documentação oficial detalha o formato exato dos parâmetros.

É possível criar um flow do zero pela API?

Sim. A API permite criar um flow vazio (apenas com o nó Start) e inativo, além de preencher seus nós com perguntas, mensagens e condições. Isso é útil para provisionar automações de forma escalável, principalmente em cenários de revenda ou onboarding de novos clientes.

A API retorna o status de cada flow ao listar?

Sim. A listagem inclui o status (Ativo ou Inativo) de cada flow e sequência, além de identificador, nome e tipo, permitindo que sistemas externos monitorem o que está funcionando e o que está pausado.

Onde encontro a documentação completa das rotas de flows?

A documentação oficial está disponível em https://papo.global/pt/docs. Lá você encontra todos os endpoints, parâmetros aceitos, códigos de erro e exemplos em várias linguagens. As rotas de flows seguem o mesmo padrão REST e autenticação dos demais módulos.