Novidades do PipesBot: Importação de Histórico no Coexistence, API de Números e Modo App no OpenClaw
Resumo: quando um cliente conecta um número que já usa no WhatsApp Business app (Coexistence), o PipesBot agora pode pedir ao WhatsApp o histórico de conversas e os contatos desse número e entregá-los no seu webhook. Você também pode listar todos os números conectados ao seu App com GET /v1/numbers, incluindo o metadata que você anexou ao criar o link de onboarding. O plugin de canal do OpenClaw ganhou um modo App para números BYON, com lista de remetentes confiáveis, e o dashboard agora mostra avisos e um feed de Novidades.
O limite diário de envios do sandbox, a aba de Webhooks, a retenção de 7 dias e o novo visual do dashboard estão no post da semana passada.
Por que o Coexistence ficou mais importante
Duas mudanças recentes da Meta tornam o Coexistence (um mesmo número usado no WhatsApp Business app e pela API ao mesmo tempo) o caminho padrão para muitas empresas:
- O Embedded Signup v5, lançado em 20 de outubro de 2026, vem com o onboarding de números do WhatsApp Business app ligado por padrão. Para desligar, a integração precisa optar por sair explicitamente (Meta: versões do Embedded Signup).
- As mensagens de marketing pela Cloud API acabam em 13 de outubro de 2027. Depois disso, templates de marketing passam pela Marketing Messages API for WhatsApp. Mensagens de utilidade, autenticação e serviço não fazem parte dessa mudança (Meta: fim das mensagens de marketing na Cloud API, visão geral da Marketing Messages API).
Mais clientes vão chegar com um número que já tem anos de conversa. O trabalho desta semana é levar esse contexto até o seu agente.
Importação de histórico e contatos em números Coexistence
Até agora, a escolha de “compartilhar o histórico de conversas” que a empresa fazia no Embedded Signup era ignorada. Agora o PipesBot age sobre ela.
Como ligar
- Por App: no dashboard, em Settings, há duas chaves, Import chat history e Import contacts. As duas vêm desligadas e só existem em Apps da API v2.
- Por link de onboarding:
POST /v1/apps/tokenaceita os booleanos opcionaisimportHistoryeimportContacts. Quando enviados, eles substituem as chaves do App para aquele link, nos dois sentidos (falsedesliga uma importação que o App tem ligada). Um valor que não seja booleano retorna400. - O webhook
number.onboardedagora informa os valores efetivos deimportHistoryeimportContactsdaquele número.
O que você recebe
- O histórico chega como eventos
historypelo contrato de webhook v2, em blocos, com um valor de progresso. Se a empresa recusar no celular, você recebe um único eventohistorycom o código de erro2593109e nenhuma mensagem. As mídias do histórico chegam primeiro como marcadores e depois a mídia em si. - Os contatos chegam como eventos
smb_app_state_sync(add/remove). - A página Numbers do dashboard mostra o estado da importação com selos como “Importing history”, “History imported” e “History not shared”.
Limites
- Só vale para números Coexistence conectados depois que você ligar a opção.
- O WhatsApp permite a importação uma vez por número, em até 24 horas após a conexão, e a empresa precisa aceitar no celular. Erros temporários da Meta são tentados de novo dentro dessa janela.
- Esses eventos não entram na fila offline, então configure uma URL de webhook no App antes de ligar as importações.
- Histórico é conversa passada: seu agente deve guardar e nunca responder.
Os detalhes, exemplos de payload e fixtures estão na documentação de Coexistence.
Liste seus números: GET /v1/numbers
Até agora, você só ficava sabendo do número de um cliente pelo webhook number.onboarded ou pelo redirect do onboarding. Se perdesse esse evento, não tinha como remontar a lista.
GET /v1/numbersretorna os números BYON do seu App, do mais antigo ao mais novo, com paginação por cursor (limitpadrão 50, máximo 100; a resposta é{ data, nextCursor }). Números com registro pendente também aparecem.GET /v1/numbers/{numberId}retorna um único número. Retorna404 NUMBER_NOT_FOUNDpara um número de outro App ou para um número sandbox.- Cada número traz
numberId,phoneNumber,displayName,status(active,pending,needs_pin,blocked,token_invalidouinactive),mode(cloud_apioucoexistence),metadataeconnectedAt. - Exige uma chave de App (
ak_). Uma chave de sandbox (pk_) recebe403 BYON_ONLY.
Metadata do onboarding em cada número
O metadata que você envia ao criar um link de onboarding agora fica salvo junto com o número e volta no GET /v1/numbers, então você consegue ligar cada número ao seu próprio cliente sem depender do webhook. Ele vem {} quando o link não tinha metadata, e null em números conectados antes desta mudança ou adicionados pelo dashboard.
O status vem dos nossos próprios registros e não consulta a Meta. Para quality rating e tier de mensagens, continue usando GET /v1/pool-numbers/{id}/health. Veja Listing numbers na documentação.
Canal do OpenClaw: modo App com remetentes confiáveis
O plugin pipes-bot-channel para OpenClaw, versão 0.2.0, agora aceita chaves de App (ak_) além das chaves de sandbox (pk_):
- A chave define o modo.
pk_continua funcionando exatamente como antes.ak_conecta pela API v2 aos seus números BYON. - Remetentes confiáveis (
allowFrom). Um número sandbox só conversa com quem o ativou, mas qualquer pessoa pode mandar mensagem para um número BYON. No modo App, o plugin só repassa ao seu agente mensagens de remetentes da listaallowFrom: números de telefone em qualquer formato, ou BSUIDs. Mensagens de qualquer outra pessoa são descartadas, e uma lista vazia descarta tudo. - Um número por conexão, se quiser. O
poolNumberIdopcional limita a conexão a um único número. - Mensagens que você envia pelo WhatsApp Business app num número Coexistence (ecos) são ignoradas, duplicadas são filtradas e falhas de envio são reportadas.
Instale ou atualize com openclaw plugins install @pipes.bot/pipes-bot-channel. O README explica as configurações do modo App.
Avisos no dashboard
O dashboard em app.pipes.bot agora pode mostrar avisos do produto como banners ou pop-ups, e há um feed de What’s new no cabeçalho com um contador de itens não lidos.
Documentação
- Docs reorganizadas para integradores. A documentação agora começa por conectar os números dos seus clientes (BYON), com páginas novas sobre como montar uma plataforma, cobrança e um checklist para ir para produção. Os números compartilhados foram para a seção Sandbox. As URLs existentes não mudaram.
- Importação de histórico e contatos no Coexistence documentada, com exemplos de payload.
GET /v1/numbersdocumentado, e o download de mídia com chave de App (GET /v1/media/download/{mediaId}) agora funciona para os números do próprio App.- Correção: o
phoneNumberdonumber.onboardedvem no formato de exibição da Meta (+1 555-123-4567), não em E.164. Os exemplos agora mostram isso corretamente.
Teste
Tudo acima já está no ar. Ligue as chaves de importação em Settings no seu App antes do próximo cliente Coexistence se conectar, e chame GET /v1/numbers para conferir quais clientes estão conectados. A documentação tem a referência completa.