Com a Papo (https://papo.global/), você pode usar a API REST para listar conversas, enviar mensagens de texto, aplicar etiquetas e atribuir conversas a agentes, automatizando processos de atendimento sem acessar a interface. A API oferece endpoints que espelham as funcionalidades do módulo de Conversas, permitindo que sistemas externos gerenciem interações de forma programática.
| Ação da API | O que faz | Exemplo de uso |
|---|---|---|
| Listar conversas | Retorna as conversas da conta, com filtros por status, etiqueta ou agente | Monitorar atendimentos ativos ou encerrados de um CRM externo |
| Enviar mensagem de texto | Dispara uma mensagem de texto para um contato (respeitando a janela de 24h do WhatsApp) | Notificar um cliente sobre atualização de pedido |
| Aplicar etiqueta | Cria uma etiqueta (se não existir) e a aplica no contato e na conversa aberta | Marcar conversas como “Urgente” ou “Pós‑venda” automaticamente |
| Atribuir conversa | Atribui as conversas abertas de um contato a um agente específico | Direcionar leads para o vendedor responsável pela região |
Como funciona a API de Conversas da Papo
A API da Papo segue o padrão REST, com autenticação via chave secreta (Bearer token) e respostas em JSON. Todas as operações descritas aqui utilizam a mesma base de autenticação e podem ser combinadas para criar fluxos de trabalho automatizados — por exemplo, um sistema de triagem que, ao receber um novo lead, lista as conversas recentes, aplica uma etiqueta de “Novo” e atribui ao agente de plantão.
A base da API é https://app.papo.global/api/v1. Para utilizar os endpoints de conversas, etiquetas e atribuições, você precisa de um token de API gerado no painel da Papo. A documentação completa com os endpoints específicos e parâmetros está disponível em papo.global/pt/docs.
Passo a passo para utilizar os recursos da API
1. Gere um token de API
No painel da Papo, acesse a seção de desenvolvedor ou tokens de acesso. Crie uma chave secreta (sk_live_…) com as permissões adequadas para gerenciar conversas. Guarde o token em local seguro — ele será enviado no cabeçalho Authorization de todas as requisições.
2. Liste as conversas
Utilize o endpoint de listagem de conversas para obter os atendimentos da conta. A requisição aceita parâmetros de filtro como:
- Status: conversas abertas, encerradas ou todas.
- Etiqueta: filtra por uma ou mais etiquetas aplicadas.
- Agente: restringe às conversas atribuídas a um usuário específico.
- Período: intervalo de datas para limitar a consulta.
A resposta inclui o identificador da conversa, o contato, o canal, o status e as últimas mensagens. Com esses dados, você pode monitorar o volume de atendimentos ou disparar ações condicionais a partir de um sistema externo.
3. Envie uma mensagem de texto
Para enviar uma mensagem de texto para um contato, utilize o endpoint de envio de mensagens. A requisição exige:
- Número do destinatário no formato internacional (ex.:
5511999999999). - Texto da mensagem.
- Identificador da instância (opcional) — caso sua conta tenha mais de uma conexão WhatsApp, você pode especificar qual delas usar.
A API retorna uma confirmação de que o pedido foi aceito. Lembre-se de que o envio de mensagens de texto está sujeito à janela de 24 horas do WhatsApp; para comunicações fora desse período, é necessário utilizar modelos de mensagem (HSM) previamente aprovados.
4. Aplique etiquetas a contatos e conversas
A API permite gerenciar etiquetas de duas formas:
- Criar uma etiqueta na conta: defina um título, cor e descrição para a nova etiqueta.
- Aplicar uma etiqueta: associe uma etiqueta existente a um contato e à conversa aberta desse contato. Se a etiqueta ainda não existir, ela será criada automaticamente durante a aplicação.
Isso é útil para classificar conversas automaticamente com base em regras do seu sistema — por exemplo, marcar como “Reclamação” quando o cliente envia uma palavra‑chave específica.
5. Atribua conversas a agentes
Com o endpoint de atribuição, você pode designar um agente para todas as conversas abertas de um determinado contato. Basta informar o identificador do contato e o ID do usuário/agente. A lista de agentes da conta pode ser obtida por meio do endpoint de listagem de usuários, que retorna nome, e‑mail e ID de cada membro da equipe.
Essa funcionalidade é essencial para roteamento automático: um sistema de CRM pode, ao identificar o perfil do lead, atribuí‑lo ao vendedor correto sem intervenção manual.
Quem deve usar a API de Conversas
- Operações que já utilizam sistemas externos (ERP, CRM, plataformas de e‑commerce) e desejam integrar o atendimento da Papo sem duplicar esforços.
- Equipes de suporte com regras de roteamento complexas, que precisam classificar e direcionar conversas automaticamente com base em dados do cliente.
- Desenvolvedores que constroem dashboards personalizados ou disparam notificações a partir de eventos do atendimento.
- Revendas white label que gerenciam múltiplas contas e querem automatizar a configuração de etiquetas e atribuições para cada cliente.
Perguntas frequentes
Preciso de um token de API para usar esses endpoints?
Sim. Todas as requisições à API da Papo exigem autenticação via chave secreta, enviada no cabeçalho Authorization: Bearer sk_live_…. Tokens são gerados no painel da conta.
A API permite enviar mensagens fora da janela de 24 horas do WhatsApp?
O envio de mensagens de texto pela API respeita a janela de 24 horas. Para comunicações proativas fora desse período, é necessário utilizar modelos de mensagem (HSM) aprovados. A Papo oferece endpoints específicos para envio de HSM.
Posso listar conversas por etiqueta?
Sim. O endpoint de listagem de conversas aceita filtro por etiqueta, permitindo que você recupere apenas os atendimentos marcados com uma ou mais tags específicas.
Como aplico uma etiqueta a um contato via API?
Utilize o endpoint de etiquetas, informando o identificador da etiqueta (ou os dados para criação) e o identificador do contato. A etiqueta será aplicada ao contato e à conversa aberta correspondente.
A API retorna o histórico completo da conversa?
A listagem de conversas retorna os metadados e as últimas mensagens. Para obter o histórico completo de mensagens de uma conversa específica, consulte a documentação da API, que detalha os endpoints de recuperação de mensagens.
É possível atribuir uma conversa a um agente sem saber o ID do usuário?
Você pode primeiro listar os usuários da conta (endpoint de agentes) para obter os IDs e depois usar o endpoint de atribuição. A lista de agentes inclui nome e e‑mail, facilitando a identificação.
Leia também
- Como usar a API da Papo para gerenciar clientes da sua revenda white label
- Como usar a API da Papo para gerenciar atributos personalizados dos contatos
Teste a API e todos os módulos da Papo sem custo — o primeiro usuário é gratuito e não exige cartão de crédito.