Como usar a API da Papo para gerenciar Sequências de follow-up

Para gerenciar Sequências de follow-up via API na Papo, você pode listar as cadências disponíveis, matricular contatos e pausar a participação de um lead usando a atualização de atributos personalizados — tudo por requisições autenticadas, sem abrir o painel. É a forma de integrar a nutrição de leads a CRMs, ERPs e fluxos de automação externos.

Resumo das operações via API

Como funciona a autenticação e os endpoints

Todas as operações usam a API REST da Papo, autenticada com a chave secreta da conta (token Bearer). A URL base é https://app.papo.global/api/v1. As chaves são geradas no painel, na área de desenvolvedor.

Os recursos de sequências estão agrupados nos endpoints de flows. A API permite listar todos os flows, incluindo os do tipo "sequence", e também ativar/desativar um flow inteiro. Para matricular um contato, há um endpoint específico que recebe o identificador do contato e o do flow.

Os detalhes exatos de cada endpoint (parâmetros, payloads e exemplos) estão disponíveis na documentação oficial da API da Papo. Aqui, focamos no fluxo de trabalho para gerenciar sequências de follow-up.

Passo a passo: listar, matricular e pausar

1. Listar as sequências disponíveis

Antes de matricular leads, você precisa saber quais sequências existem e seus identificadores. A chamada de listagem retorna uma relação com nome, ID e status (ativo/inativo). Apenas sequências ativas aceitam novas matrículas.

Com a lista em mãos, seu sistema externo pode mapear qual sequência usar para cada lead.

2. Matricular um contato em uma sequência

Com o ID do contato (obtido via busca ou criação pela API de contatos) e o ID da sequência ativa, você envia uma requisição para inseri-lo no início da jornada. O contato precisa existir no CRM da Papo; caso contrário, crie-o antes usando o endpoint de contatos.

A matrícula inicia imediatamente o envio das mensagens programadas, respeitando os intervalos configurados no Flow. O histórico do contato é preservado.

3. Pausar a cadência para um contato específico

A API da Papo não possui um comando direto para "pausar" a participação de um contato em uma sequência. No entanto, você pode obter o mesmo efeito combinando a API de contatos com uma condição no Flow.

Pré-requisito: a sequência deve ter sido construída com um nó de condição que verifica um atributo personalizado (ex.: status_pausa). Se o atributo for igual a "pausado", a condição bloqueia o envio das próximas mensagens; caso contrário, libera. (Veja o artigo sobre pausa temporária para detalhes de montagem do Flow.)

Com essa estrutura no Flow, a pausa é feita em dois passos via API:

1. Identifique o contato pelo ID ou busque-o por telefone/e-mail usando o endpoint de listagem de contatos.
2. Atualize o atributo personalizado do contato para "pausado" (ou o valor que sua condição espera). Utilize o endpoint de atualização de contato, enviando o campo customizado.

A partir desse momento, quando o fluxo chegar à condição, ele identificará o valor "pausado" e não enviará a mensagem. Para retomar, basta atualizar o atributo para qualquer outro valor (ex.: "ativo") ou limpá-lo, e o contato continuará de onde parou.

Esse método mantém o contato matriculado e o progresso na cadência, sem perder o histórico.

Para quem essa integração é útil

• Operações de SDR e vendas B2B que disparam sequências a partir de eventos externos (ex.: um lead baixou um material, um negócio foi criado no CRM).
• Revendedores white label que provisionam jornadas de follow-up automaticamente para novos clientes, matriculando contatos iniciais sem ação manual.
• Times de marketing e automação que usam ferramentas como n8n ou Zapier para conectar a Papo a dezenas de sistemas e precisam de controle granular sobre as cadências.
• Empresas com processos de pausa condicional, onde um lead pede um tempo e o vendedor quer interromper a sequência sem perder o ponto da cadência — tudo acionado por um botão no CRM externo.

Perguntas frequentes

Preciso da chave secreta para listar sequências?

Sim. Toda operação que retorna dados da conta requer autenticação com a chave secreta, enviada como token Bearer no cabeçalho Authorization.

Posso matricular um contato que ainda não existe na Papo?

Não. O contato precisa existir no CRM da Papo. Você pode criá-lo primeiro via API de contatos (com nome, telefone ou e-mail) e depois matriculá-lo na sequência.

A API permite remover um contato da sequência?

A remoção (cancelamento da matrícula) não está disponível como endpoint específico na versão atual. A alternativa para interromper os envios é pausar via atributo personalizado, conforme descrito, ou desativar o flow inteiro, o que afeta todos os contatos.

Como sei se a pausa por atributo funcionou?

Após atualizar o atributo, a sequência continuará processando os nós de espera. Quando chegar à condição, ela verificará o valor. Se estiver "pausado", a mensagem não será enviada. Você pode confirmar no perfil do contato, no módulo de Contatos, que ele permanece matriculado, mas as próximas mensagens não são disparadas.

Posso pausar a sequência inteira pela API?

Sim. A API permite alterar o status de um flow para inativo, pausando a sequência para todos os contatos. Use o endpoint de ativação/desativação de flow. Para retomar, basta reativá-lo.

Onde encontro os endpoints exatos e exemplos de código?

A documentação completa da API está disponível em https://papo.global/pt/docs. Lá você encontra os endpoints de flows, contatos e os formatos de requisição.

Leia também

• Como usar a API da Papo para gerenciar Flows de automação
• Como usar a API da Papo para criar e atualizar contatos em massa

Comece grátis e automatize suas sequências →

Com a API da Papo, você integra a nutrição de leads diretamente ao seu stack, sem abrir o painel — o primeiro usuário é gratuito para você testar.