**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](https://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](/hc/papo/articles/usar-api-papo-gerenciar-clientes-revenda-white-label)
- [Como usar a API da Papo para gerenciar atributos personalizados dos contatos](/hc/papo/articles/como-usar-api-papo-gerenciar-atributos-personalizados-contatos)

---

**[Comece a usar grátis →](https://chat.papo.global/app/auth/signup?papo_lp=home&utm_source=lp&utm_medium=landing&utm_campaign=home&utm_content=start-free&papo_lp_v=start-free)**

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.