API · Atualizado em 12/10/2026
Limitações da API do Pipe
Saiba o que a API por chave não faz, como cadastrar canais, ligações, webhooks e modelos, e quais alternativas existem na Gestão, no Builder e no MCP.
A API por chave cobre o dia a dia da operação: enviar, atender, consultar e acompanhar. Algumas tarefas ficam de fora de propósito (por envolverem risco, cobrança ou revisão da Meta) e outras ainda não existem. Este guia lista o que não está disponível e o que fazer no lugar.
Quando usar
Antes de planejar uma integração, para não esbarrar em algo que a API não faz, e ao receber uma recusa que parece inesperada.
O que a API não faz
| Tarefa | Situação | Alternativa |
|---|---|---|
| Conectar, ajustar ou desconectar canais (WhatsApp, Instagram, Messenger) | Só por pessoa na Gestão | Veja Conectar WhatsApp |
| Ligações pelo WhatsApp: habilitar, pedir permissão, atender e consultar | Só no Desk e na Gestão, por pessoa logada. Não há rota por chave | Configuração e uso pelas telas do Pipe |
| Criar, editar ou apagar webhooks | A chave só lê (webhooks:ler) | Cadastre na Gestão, em Integrações. Veja Webhooks e eventos |
| Criar, editar ou apagar etiquetas, respostas rápidas, filas, regras, horários, pausas e atendentes | Leitura apenas | Gestão ou MCP |
| Criar ou excluir modelos de mensagem | Não por chave, porque envolve revisão da Meta | Gestão, em Modelos de mensagem |
| Importar contatos em massa | Só pela tela | Importação na Gestão |
| Excluir contato | Não existe rota pública | Gestão |
| Convites, papéis, plano e cobrança | Só por pessoa | Gestão |
| Publicar ou editar fluxos do Builder | Não por esta API | Builder ou MCP |
Mensagens
- Enviar a um contato sem ticket: a rota de mensagens trabalha dentro de um ticket. Use mensagem ativa ou campanha com modelo aprovado, ou abra um ticket.
- Menus e botões interativos livres: não são enviados pela API de conversas. Use o Builder. Botões de modelo funcionam com
parametros_botoes. - Mídia por link: na rota estilo Blip (
POST /messages), mídia por link é recusada. Envie o arquivo porPOST /v1/attachments. - Outros canais em
POST /messagescom modelo: Instagram, Messenger e e-mail respondem 501. - Campanhas com modelos de mídia no cabeçalho ou botões de valor variável: ainda não são aceitos.
- Formatos do WhatsApp: imagem, áudio e vídeo precisam seguir as regras da Meta. Veja Enviar mensagens.
Eventos e notificações
- Notificações de mensagem no estilo Blip não são empurradas ao seu webhook. A recusa de um envio vem na própria resposta HTTP.
- O estado de entrega de uma mensagem chega pelo evento
mensagem.estado_entrega_alteradoou por leitura das mensagens do ticket. - Os webhooks dos canais (Meta e pagamentos) apontam para o Pipe e não fazem parte da API de integração.
Limites de uso
Chamadas por segundo e por minuto, tamanho de corpo, de arquivo e de lote têm teto. Veja Limites de uso e idempotência.
Escopo da chave
Chaves de fluxo veem só o próprio fluxo, e o que está fora responde 404. Escopos como contexto:escrever e relatorios:ler não vêm na chave padrão. Veja Escopos e permissões.
Ambiente de testes
Esta documentação não descreve um ambiente de testes separado. Para testar sem risco, use leituras, contatos e canais seus, e faça disparos primeiro para um número próprio.
Resultado esperado
Você sabe de antemão o que a API cobre e já tem o caminho alternativo para o que ela não faz.
Problemas comuns
- 404 em rota que você viu em outra documentação: só as rotas listadas nesta seção da central existem para chave de API. Rotas da Gestão e do Desk usam sessão de pessoa.
- 501 em envio de modelo para Instagram ou Messenger: o envio de modelo pela raiz estilo Blip é só para WhatsApp.
- Falta uma rota que você precisa: fale com o suporte do Pipe e descreva o caso. Se for configuração, o MCP pode resolver.
Boas práticas
- Faça da API a ponte entre sistemas e deixe a configuração para a Gestão ou o MCP.
- Desenhe a integração para conviver com respostas 404 e 403 sem travar.
Próximos passos
- Volte à visão geral da API.
- Veja o que um agente de IA consegue fazer em Limitações do MCP.
Perguntas frequentes
Posso conectar um canal WhatsApp pela API?
Não. A conexão e os ajustes de canal, inclusive as ligações pelo WhatsApp, são feitos na Gestão por pessoas com acesso, e não por chave de API.
Posso criar um webhook pela API?
Não. A chave só lê webhooks e entregas. O cadastro é feito na Gestão.
Dá para enviar mensagem a quem não tem ticket?
Não pela rota de mensagens. Use um modelo aprovado com mensagem ativa ou campanha, ou abra um ticket para o contato antes.
Existe sandbox para testar?
Esta documentação não descreve um ambiente de testes separado. Teste com leituras e com contatos seus.
Esse artigo foi útil?
Obrigado pelo retorno!