integrate-whatsapp

Visão geral da skill integrate-whatsapp

O que a integrate-whatsapp faz

A skill integrate-whatsapp ajuda você a conectar o WhatsApp a um produto com Kapso, desde o onboarding do cliente até a entrega de mensagens. Ela é mais útil quando você precisa de um guia integrate-whatsapp que reúna, em um único fluxo, links de configuração, detecção de conexão, webhooks, envio de templates, mídia e WhatsApp Flows.

Casos de uso mais adequados

Use esta integrate-whatsapp skill para sistemas backend que precisam:

• fazer onboarding de clientes na própria conta do WhatsApp Business deles
• detectar quando um número passa a estar conectado
• receber eventos de mensagem e conversa via webhooks
• enviar mensagens, templates e mídia outbound
• gerenciar endpoints de Flows, criptografia e etapas de publicação

Por que vale a pena instalar esta skill

A principal vantagem é a completude do fluxo. O repositório oferece caminhos práticos tanto para integração com foco em CLI quanto para integração com foco em API, o que faz diferença se seu ambiente ainda está mudando ou se você precisa suportar múltiplos tenants. Se você está avaliando um integrate-whatsapp install, esta skill é mais forte do que um prompt genérico porque inclui os pontos que normalmente travam o trabalho em produção: IDs, roteamento de webhook, ciclo de vida do setup link e a distinção entre operações no nível do projeto e no nível do número de telefone.

Como usar a skill integrate-whatsapp

Instale e confirme o contexto

Instale com npx skills add gokapso/agent-skills --skill integrate-whatsapp. Antes de pedir ajuda de implementação, confirme o contexto do repositório no seu projeto e leia primeiro SKILL.md. Depois, examine references/getting-started.md, references/platform-api-reference.md, references/webhooks-overview.md e references/setup-links.md, porque eles explicam o caminho real da integração melhor do que uma passada rápida pelos assets.

Transforme um objetivo vago em um prompt útil

Para um melhor integrate-whatsapp usage, descreva:

• se você está usando o Kapso CLI ou chamadas diretas de API
• se o app é multi-tenant ou trabalha com um único número
• em qual etapa você travou: onboarding, detecção de conexão, tratamento de webhook, envio ou Flows
• quais objetos você já tem, como customer_id, phone_number_id, business_account_id ou o secret do webhook

Um prompt forte parece com isto:

Implemente o onboarding do WhatsApp para uma SaaS multi-tenant. Já tenho customer_id, preciso de um fluxo com setup-link, confirmação de webhook para whatsapp.phone_number.created e um caminho de envio de mensagens usando phone_number_id.

Arquivos e fluxos para ler primeiro

Comece pelos arquivos que moldam as escolhas de implementação:

• references/getting-started.md para o fluxo ponta a ponta
• references/detecting-whatsapp-connection.md para eventos de conexão e tratamento de redirect
• references/webhooks-reference.md e references/webhooks-overview.md para regras de entrega de eventos e verificação de assinatura
• references/templates-reference.md se você envia templates ou mídia
• references/whatsapp-flows-spec.md mais assets/sample-flow.json se você precisar de Flows

Assets úteis para revisar cedo:

• assets/webhooks-example.json
• assets/dynamic-flow.json
• assets/send-template-order-status-update.json
• assets/send-interactive-buttons.json

Dicas práticas de uso

Prefira o CLI quando estiver explorando o estado do projeto, clientes ou números, e use chamadas de API diretas quando for embutir a integração no seu próprio backend. Não confunda onboarding por setup-link com envio de mensagens: o onboarding cria ou resolve o número conectado, enquanto o envio exige o phone_number_id correto. Essa distinção é central para um integrate-whatsapp usage bem-sucedido e evita a maioria dos erros de integração.

FAQ da skill integrate-whatsapp

Isso é só para desenvolvimento backend?

Sim, esta integrate-whatsapp for Backend Development é voltada principalmente para trabalho de backend. Ela se encaixa em onboarding server-side, processamento de webhooks, autenticação de API e orquestração de mensagens. Não é uma skill de texto para UI nem um template de prompt puro para conteúdo de marketing.

Em que ela difere de um prompt comum?

Um prompt comum costuma descrever a integração com WhatsApp de forma vaga. A integrate-whatsapp skill é mais útil porque reflete a superfície real da integração: setup links, eventos de webhook, resolução de número e WhatsApp Flows. Isso reduz o chute quando você precisa de algo implantável, e não apenas ilustrativo.

Preciso do Kapso CLI para usar?

Não, mas o CLI é o caminho preferido na skill porque ajuda na seleção de projeto, no setup e na descoberta de números. Se sua equipe não puder usar ferramentas de CLI, as referências ainda dão suporte a chamadas diretas de API via X-API-Key.

Quando eu não devo usar a integrate-whatsapp?

Evite esta skill se você só quer uma visão geral de produto sobre WhatsApp, ou se está integrando com um provedor totalmente diferente e não pretende usar as Platform APIs da Kapso. Ela também é uma má escolha se você só precisa de um exemplo pontual de mensagem, sem onboarding nem webhooks.

Como melhorar a skill integrate-whatsapp

Dê à skill o estado inicial certo

As melhores melhorias vêm de fornecer o estado real da integração: ID atual do projeto, se o cliente já existe, o endpoint de webhook que é seu e o tipo de mensagem que você precisa enviar. Isso torna os resultados de integrate-whatsapp install mais acionáveis, porque a skill consegue raciocinar a partir de onde o seu fluxo começa, em vez de repetir a configuração do zero.

Seja explícito sobre o modo de falha

Se quiser resultados melhores, diga qual é o bloqueio:

• “o setup link abre, mas nenhum número de telefone é criado”
• “o webhook chega, mas a verificação de assinatura falha”
• “o envio de template funciona em teste, mas não em produção”
• “estou usando o phone_number_id errado”

Esse tipo de entrada gera orientações de integrate-whatsapp usage muito mais úteis do que pedir um plano genérico de integração.

Use os artefatos certos para iterar

Se a primeira resposta vier incompleta, itere com um destes:

• o payload de webhook que você recebeu
• o JSON do template que quer enviar
• o JSON do Flow que você quer publicar
• a saída do comando de kapso status, kapso whatsapp numbers list ou a resposta da sua API

Para trabalho de integrate-whatsapp guide, esses artefatos importam mais do que requisitos amplos, porque permitem corrigir rapidamente IDs, nomes de eventos, tratamento de redirect e formato do payload.

Fique atento aos erros comuns em produção

Os modos de falha mais comuns são usar o identificador errado, assinar o tipo errado de webhook ou assumir que a conclusão do setup já significa prontidão para envio de mensagens. Melhore a saída da skill dizendo se você precisa de webhooks de projeto ou de número de telefone, se está usando Kapso ou endpoints proxy da Meta e se seu app precisa suportar coexistência ou modo dedicado.