Visão geral
O canal de API é um canal genérico para integrações personalizadas. Em vez de um canal pronto (WhatsApp, e-mail, site), você conecta o seu próprio sistema ou um canal não nativo: o seu aplicativo envia mensagens para a plataforma e recebe as respostas por API e webhooks.
É a base ideal para integrar canais sob medida, bots e sistemas externos, mantendo as conversas centralizadas com histórico, atribuição e automações como em qualquer outro canal.
Pré-requisitos
- Perfil de administrador para criar a caixa de entrada de API.
- Conhecimento técnico para consumir uma API HTTP e tratar webhooks no seu sistema.
- Um endpoint público no seu lado para receber os eventos de webhook (mensagens da plataforma).
- As credenciais de acesso da API da sua conta (consulte a categoria de API & Desenvolvedores).
Passo a passo
- Em Configurações → Caixas de Entrada, crie uma nova caixa e escolha API.
- Informe o nome do canal e, se aplicável, a URL de webhook do seu sistema.
- Conclua a criação — a caixa de entrada passa a ter um identificador próprio.
- No seu sistema, use a API para criar/identificar o contato e enviar mensagens para a caixa.
- Configure o webhook para receber, no seu sistema, as respostas e eventos da plataforma.
- Envie uma mensagem de teste pela API e confirme que ela aparece como conversa.
Configurações & opções
- Identificador da caixa: usado nas chamadas de API para direcionar mensagens à inbox certa.
- URL de webhook: endpoint do seu sistema que recebe as mensagens e eventos da plataforma.
- Contatos e conversas: criados/atualizados via API, com os mesmos recursos dos demais canais.
- Automação e atribuição: aplique regras como em qualquer outro canal.
Casos de uso
- Conectar um canal próprio ou um sistema legado que não tem integração nativa.
- Construir um bot personalizado que conversa com os contatos pela plataforma.
- Integrar um aplicativo interno para registrar e responder conversas automaticamente.
Dicas, limites e boas práticas
- Trate o webhook de forma idempotente para evitar conversas ou mensagens duplicadas.
- Proteja suas credenciais de API: mantenha-as no servidor, nunca expostas no cliente.
- Implemente novas tentativas no envio para lidar com falhas temporárias de rede.
Solução de problemas
- As mensagens não entram: confira o identificador da caixa e as credenciais usadas na API.
- Não recebo eventos no meu sistema: valide a URL de webhook e se o endpoint responde com sucesso.
- Conversas duplicadas: garanta o tratamento idempotente dos webhooks no seu lado.