Catálogo completo de endpoints

Registra o cliente final do assinante usando external_customer_id como ligação com o CRM, ERP ou SaaS de origem. Se a chave ainda não existe nesse parceiro, cria um cadastro; se já existe, atualiza os dados fornecidos e preserva os opcionais omitidos. O cadastro do cliente não significa que um número de WhatsApp foi conectado: essa etapa vem pela criação da instância e pelo Embedded Signup.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Para criar um cliente novo: Webhook global habilitado, primário e com verificação GET salva. A HookCloud envia hub.mode=subscribe, hub.verify_token e hub.challenge=1234; seu servidor deve conferir o token e responder HTTP 200 com somente 1234 em texto puro. Testar sem salvar não libera cadastros. Ative também o POST na mesma URL para receber eventos.
• Definir uma chave externa estável que não mude quando o nome ou e-mail do cliente mudar.
• Para criar um cadastro novo, a cobrança precisa permitir novas operações; a implementação permite atualizar um cliente existente durante pendência de cobrança.

Autenticação e permissão

Partner API Key ativa com customers.write ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=upsert-partner-customer

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "external_customer_id": "cliente-001",
  "customer_name": "Nome do cliente"
}

O que preencher em cada campo

Como ler a resposta

HTTP 201 indica criação e HTTP 200 indica reaproveitamento. O corpo contém ok, reused, partner_id, partner_customer_id, external_customer_id, dados cadastrais, metadata, status, archived e warnings. Guarde partner_customer_id para chamadas com UUID; continue usando external_customer_id para reconciliar com o seu banco. reused não informa que existe conexão Meta.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 409 partner_webhook_verification_required: configure, valide e salve o webhook em Endpoints/update-partner-webhook-endpoint antes de tentar criar cliente, instância ou sessão. A validação avulsa não libera a operação. Consulte get-partner-onboarding-status.
• 400 missing_customer_fields: faltou chave externa/nome ou o nome está fora do limite.
• 400 invalid_customer_email/invalid_customer_phone: formato cadastral inválido.
• 409 customer_data_erased/customer_already_merged: use o cadastro de destino ou siga o tratamento de dados; não recrie automaticamente sob a mesma chave.
• Bloqueios de cobrança podem impedir a criação de um cliente novo.
• 409 billing_sync_required: o período de cobrança ou trial confirmado expirou e precisa ser reconciliado. O proprietário deve abrir Assinatura no Portal e clicar em Atualizar para consultar a Stripe; se persistir, procurar o suporte. Não repita novas criações automaticamente. Isso não confirma recusa do cartão nem desconecta números já ativos.

Depois desta chamada

• Criar o primeiro número com create-customer-instance.
• Consultar get-partner-customer para conferir o cadastro e seus vínculos.

Regras desta operação

• Não use o número de telefone como única chave do cliente se ele puder mudar.
• Esta operação não reativa automaticamente um cadastro cancelado nem desfaz mesclagem.
• Metadados enviados não são mesclados chave a chave; mande o objeto final desejado.
• O estado autoritativo da configuração vem de get-partner-onboarding-status. URL presente ou token configurado, isoladamente, não confirmam GET validado. Atualizações de um cliente já existente não são tratadas como novo cadastro.

Retorna uma visão paginada dos clientes pertencentes ao parceiro autenticado, incluindo resumos calculados a partir das instâncias. A lista serve para conciliar o cadastro externo com o Partner e identificar clientes cancelados, mesclados ou com dados eliminados quando esses filtros forem habilitados.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Usar credencial do parceiro correto.
• Percorrer as páginas até o total retornado, em vez de assumir que a primeira resposta contém todos os clientes.

Autenticação e permissão

Partner API Key ativa com customers.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=list-partner-customers&page=1&page_size=20

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

Retorna ok, items, page, page_size, total e pages. Os itens incluem os campos cadastrais selecionados, marcas de arquivamento/mesclagem/eliminação e resumo das instâncias. total é a contagem do filtro completo, não o tamanho de items. pages é no mínimo 1 mesmo quando a lista está vazia. Reaproveite o id do item em customer_id e o external_customer_id na sincronização.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 invalid_pagination: page ou page_size não é inteiro no intervalo permitido.
• Falhas de consulta retornam customer_operation_failed; não trate uma resposta de erro como lista vazia.
• 413 customer_instance_expansion_too_large: a expansão de instâncias desta resposta ultrapassa 20.000 números. A resposta não fornece totais parciais. Reduza page_size na listagem de clientes e consulte os números por list-partner-instances, filtrando customer_id e usando page/page_size.

Depois desta chamada

• Abrir get-partner-customer para o cadastro escolhido.
• Usar get-partner-customer-history para trilha completa de alterações.

Regras desta operação

• include_merged e include_erased só alteram visibilidade da lista.
• Clientes criados enquanto a paginação é percorrida podem deslocar posições; deduplique por id na reconciliação.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.
• A expansão de instances é lida em páginas internas para não truncar no limite de uma consulta ao banco. O orçamento por resposta é de 20.000 instâncias; para grandes integrações, prefira list-partner-instances paginado. Leituras em páginas não representam um snapshot transacional: deduplique por id e reconcilie alterações concorrentes pelos eventos.
• Uma importação deve guardar id + partner_id + external_customer_id, preservar archived/merged_into_customer_id/pii_erased e percorrer todas as páginas. Não recrie clientes por nome/telefone e não reative registros arquivados. A resposta desta lista não inclui partner_id na raiz: confira cada item. customers.write não concede customers.read implicitamente.

Carrega um cliente com o resumo de suas instâncias, os 50 registros de alteração mais recentes e o estado de risco Meta associado ao cadastro. É a consulta de detalhe que permite reunir o cadastro comercial e a situação operacional sem revelar o token Meta.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Conhecer customer_id/partner_customer_id ou external_customer_id pertencente ao parceiro.

Autenticação e permissão

Partner API Key ativa com customers.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-customer&external_customer_id=cliente-001

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

O corpo contém ok, customer, history e meta_risk_state. customer traz o cadastro resumido e seus vínculos; history inclui action, changed_fields, before_data, after_data, reason, ator, metadata e data. meta_risk_state pode ser null. Guarde customer.id e customer.updated_at quando disponíveis; o timestamp pode ser usado como expected_updated_at na edição. customer_risk contém a política individual do cliente: ban_count_30d, red_count_30d, limits={ban:20,red:5}, window_days=30, block_new_connections, reasons, next_exit_at, next_unlock_at e a cobertura histórica. Os limites bloqueiam novas conexões desse cliente, mesmo com vagas no pacote, sem desligar números existentes. Atualize seu cache com hookcloud.customer.risk_updated e reconcilie pela Partner API.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 para ausência de identificador utilizável.
• 404 customer_not_found quando o cadastro não está disponível ao parceiro autenticado.
• 413 customer_instance_expansion_too_large: a expansão de instâncias desta resposta ultrapassa 20.000 números. A resposta não fornece totais parciais. Reduza page_size na listagem de clientes e consulte os números por list-partner-instances, filtrando customer_id e usando page/page_size.

Depois desta chamada

• Usar update-partner-customer com expected_updated_at para evitar sobrescrever edição concorrente.
• Consultar get-partner-customer-history para páginas além dos 50 registros recentes.

Regras desta operação

• before_data e after_data podem conter dados cadastrais: mantenha o resultado em telas/rotinas autorizadas.
• A consulta não atualiza automaticamente os dados do número na Meta.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.
• A expansão de instances é lida em páginas internas para não truncar no limite de uma consulta ao banco. O orçamento por resposta é de 20.000 instâncias; para grandes integrações, prefira list-partner-instances paginado. Leituras em páginas não representam um snapshot transacional: deduplique por id e reconcilie alterações concorrentes pelos eventos.

Lista o histórico de mudanças de um cliente em páginas, com os valores anteriores e posteriores registrados pelas operações auditadas. Diferentemente da consulta de detalhe, não limita a navegação aos 50 registros mais recentes.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Identificar o cliente dentro do parceiro.
• Ter finalidade de consulta aos dados de antes/depois, pois podem conter informações pessoais.

Autenticação e permissão

Partner API Key ativa com customers.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-customer-history&external_customer_id=cliente-001&page=1&page_size=20

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

Retorna ok, customer_id, items, total, page e page_size. Cada item contém id, action, changed_fields, before_data, after_data, reason, actor_user_id, actor_source, metadata e created_at. Para a página seguinte, incremente page mantendo os mesmos filtros; este endpoint não retorna pages.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 404 customer_not_found se o seletor não resolver um cadastro acessível.
• 400 invalid_pagination para valores de paginação inválidos.

Depois desta chamada

• Comparar changed_fields e reason com a alteração solicitada no seu sistema.
• Consultar get-partner-customer para o estado atual.

Regras desta operação

• O histórico explica alterações registradas; não é um mecanismo de desfazer operação.
• Não copie dados de before_data para reverter automaticamente uma mesclagem ou eliminação.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Edita apenas nome, e-mail e telefone de um cliente existente, com suporte a controle de concorrência e idempotência. A operação é adequada para formulários de edição: recebe o conjunto de mudanças, registra histórico e, quando houve alteração, emite o evento hookcloud.partner.customer.updated. A chave externa e os identificadores técnicos permanecem imutáveis.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Consultar o cliente antes de editar para obter seu identificador e updated_at.
• Enviar ao menos um dos três campos editáveis; deixar campos fora de changes preserva os valores atuais.

Autenticação e permissão

Partner API Key ativa com customers.write ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=update-partner-customer

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json",
  "Idempotency-Key": "UUID_UNICO_PARA_ESTA_ALTERACAO"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "external_customer_id": "cliente-001",
  "changes": {
    "customer_name": "Cliente da integração atualizado"
  },
  "reason": "Teste de API"
}

O que preencher em cada campo

Como ler a resposta

Retorna ok e o resultado da transação, incluindo changed e changed_fields quando aplicáveis, o cadastro atualizado e immutable_fields com external_customer_id e instance_key. changed=false indica ausência de alteração efetiva. Releia o cliente após sucesso para continuar trabalhando com o updated_at atual.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 immutable_customer_fields: tentativa de editar status, metadata, external_customer_id ou identificadores proibidos.
• 400 invalid_customer_name/invalid_customer_email/invalid_customer_phone: dados inválidos.
• 409 customer_changed_since_last_read: recarregue os dados antes de reaplicar uma alteração intencional.
• 409 customer_data_erased/customer_already_merged: o cadastro não permite essa edição.
• 400 invalid_idempotency_key: a chave precisa ter 8 a 200 caracteres; reutilização incompatível é bloqueada pelo controle de idempotência.

Depois desta chamada

• Atualizar o estado do formulário com o cadastro confirmado.
• Consultar histórico para verificar os campos alterados.

Regras desta operação

• metadata não é editável aqui; use o contrato de upsert quando precisar atualizar metadados.
• Não mude expected_updated_at para um valor inventado para contornar um conflito.
• Repetir com a mesma idempotency_key deve preservar exatamente a intenção e o corpo originais.

Retira a imagem associada ao cadastro do cliente. Nome, external_customer_id, instâncias, conexões, cobrança e histórico permanecem intactos.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Cliente existente e pertencente ao parceiro autenticado.
• API Key com customers.write ou membro owner/admin/developer autorizado.

Autenticação e permissão

Partner API Key ativa com customers.write ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=remove-partner-customer-avatar

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "customer_id": "UUID_DO_CLIENTE"
}

O que preencher em cada campo

Como ler a resposta

Após a confirmação, avatar_url fica vazio/nulo e o Portal volta a mostrar as iniciais. Uma URL assinada emitida anteriormente pode ter duração residual até o vencimento; não a trate como endereço permanente.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 403/404: verifique escopo, função e vínculo do cliente.
• Em erro de rede, consulte o cadastro antes de repetir.

Depois desta chamada

• Limpe o avatar do cache do seu sistema e use as iniciais do cliente.

Regras desta operação

• Não exclui o cliente nem o número de WhatsApp.
• Não use essa operação para modificar a foto comercial mantida pela Meta.

Salva uma foto opcional para identificar o cliente na lista do Portal e no agrupamento de instâncias. É uma foto cadastral privada na HookCloud, independente da imagem do perfil comercial do WhatsApp.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Cliente existente e pertencente ao parceiro autenticado.
• API Key com customers.write ou membro owner/admin/developer autorizado.

Autenticação e permissão

Partner API Key ativa com customers.write ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=upload-partner-customer-avatar

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

O que preencher em cada campo

Como ler a resposta

O retorno e as consultas de cliente fornecem avatar_url, avatar_url_expires_at e avatar_updated_at. A URL é assinada e temporária, com duração aproximada de cinco minutos; para renová-la consulte novamente o cliente. Não armazene a URL como identificador permanente nem compartilhe o link publicamente.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400: confira customer_id e o arquivo enviado.
• 403/404: confira função, escopo e vínculo do cliente; não tente contornar alterando partner_id.
• Arquivo vazio, maior que 2 MiB, animado, acima de 4096 pixels por lado/16 megapixels ou com formato binário incompatível: escolha uma imagem estática dentro dos limites.

Depois desta chamada

• Atualize o avatar exibido com o retorno; em falha de carregamento, mostre as iniciais.
• Se o cadastro já foi salvo e só a foto falhou, repita somente o envio da foto para o mesmo customer_id. Não recrie o cliente nem a instância.

Regras desta operação

• Não configurar Content-Type multipart manualmente sem boundary; a biblioteca HTTP o cria.
• O arquivo não é enviado à Meta. A foto não ocupa vaga de número nem muda a saúde ou o nome aprovado.

Consolida dois cadastros duplicados do mesmo parceiro. A origem perde o papel de cadastro operacional principal, suas instâncias são vinculadas ao destino e o registro de origem é marcado como mesclado. A operação preserva as instance_keys e não transforma o ID externo da origem no ID externo do destino; o sistema externo deve registrar essa equivalência.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Origem e destino distintos, ambos do mesmo parceiro.
• Destino ativo e apto a receber instâncias; cadastros já mesclados ou com dados eliminados exigem tratamento específico.
• Conferir a lista de instâncias antes da operação.

Autenticação e permissão

Partner API Key ativa com customers.write ou *. Se optar por JWT, as funções permitidas são owner, admin.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=merge-partner-customers

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json",
  "Idempotency-Key": "UUID_UNICO_PARA_ESTA_ALTERACAO"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "source_customer_id": "SOURCE_CUSTOMER_ID",
  "target_customer_id": "TARGET_CUSTOMER_ID",
  "reason": "Teste de mesclagem"
}

O que preencher em cada campo

Como ler a resposta

Retorna ok, source_customer_id, target_customer_id, moved_instance_ids (array dos UUIDs movidos), moved_instances (quantidade), source_external_customer_id e target_external_customer_id, além de external_customer_id_immutable=true e instance_keys_unchanged=true. Reaproveite target_customer_id como referência operacional no sistema externo. Confirme a associação final consultando get-partner-customer do destino e, se necessário, inclua cadastros mesclados na listagem para localizar a origem.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 invalid_merge_payload: IDs ausentes ou fora do formato UUID.
• 400 merge_same_customer: origem e destino iguais.
• 404 source_customer_not_found/target_customer_not_found: um cadastro não pertence ao contexto acessível.
• 409 source_customer_already_merged/target_customer_already_merged/target_customer_inactive/customer_data_erased: estado incompatível.

Depois desta chamada

• Atualizar no CRM a referência ao cliente de destino.
• Listar instâncias do destino e verificar histórico/evento hookcloud.partner.customer.merged.

Regras desta operação

• Não existe operação pública para desfazer mesclagem; trate como decisão estrutural.
• Não use mesclagem apenas para mover um único número: existe uma operação específica para isso.

Inicia ou continua uma solicitação durável de encerramento para esse cliente, com lotes limitados e progresso consultável. Primeiro desliga as instâncias e autorizações pertencentes ao cliente, agrupando os números que compartilham WABA ou autorização quando o alcance seguro é comprovado. Depois avalia as relações empresariais HookCloud–portfólio do cliente. A retirada comercial só ocorre com inventário completo, exclusividade e confirmação independente; relações usadas por outros clientes, parceiros, produtos ou ativos são preservadas.

Referência oficial Meta: Números, registro e permissões · Webhooks da Cloud API · Meta: relação empresarial entre provedor e cliente

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Revisar todas as instâncias do cliente antes de confirmar.
• Garantir que o encerramento desse cliente, e não apenas de um número, foi a ação pretendida.

Autenticação e permissão

Partner API Key ativa com customers.write ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=deactivate-partner-customer

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "external_customer_id": "cliente-001",
  "reason": "Encerramento de teste"
}

O que preencher em cada campo

Como ler a resposta

POST retorna HTTP 202 com status=cancel_pending, archived=false enquanto houver processamento, confirmação ou ação necessária. HTTP 200 com status=canceled, archived=true indica conclusão do job. O envelope contém ok, partner_id, partner_customer_id, external_customer_id e offboarding; o POST também pode informar used_slots e slot_limit. offboarding traz job_id, generation, status, phase, technical, commercial, technical_complete, commercial_complete, all_relationships_removed e issues[]. Uma parceria compartilhada aparece em commercial.preserved_shared e não em commercial.removed. Consulte GET get-customer-offboarding para acompanhar o registro local; esse GET não consulta a Meta nem executa remoções. O POST repetido para o mesmo cliente retoma a mesma solicitação, respeitando as intenções já gravadas: uma escrita ambígua não é repetida. A vaga de cada número só é liberada após sua confirmação técnica; o cadastro do cliente só é arquivado quando a fase comercial também tem resultado terminal.

Campos retornados que atualizam o painel

Erros e como agir

• 404 customer_not_found: o cadastro não pertence ao parceiro autenticado ou não existe.
• 409 customer_offboarding_connection_inflight: uma conexão desse cliente ainda está em conclusão; confira seu resultado antes de iniciar o encerramento.
• 409 customer_offboarding_scope_limit: o escopo ultrapassou o orçamento de segurança desta execução; solicite orientação da HookCloud, sem dividir clientes ou omitir números para contornar a proteção.
• offboarding.issues[].code=customer_cleanup_scope_limit: um grupo de números que compartilha WABA ou autorização não pôde concluir a conferência inicial dentro de 40 leituras na Meta ou 45 segundos. O job fica action_required e não repete esse trabalho automaticamente. A HookCloud precisa avaliar uma forma segura de organizar o encerramento; não tente contornar a proteção criando novos clientes ou desconectando uma autorização compartilhada por conta própria.
• 409 customer_offboarding_not_configured: falta configuração administrativa necessária para criar a solicitação; a HookCloud precisa concluir essa configuração.
• Um resultado pending ou action_required dentro do job não deve ser tratado como encerramento concluído. Leia issues[].message e acompanhe pelo GET local.

Depois desta chamada

• Guardar offboarding.job_id e consultar get-customer-offboarding usando o mesmo cliente.
• Atualizar seu painel pelos estados e explicações do job. Os eventos por instância continuam úteis, mas não significam que a parceria comercial inteira foi retirada.
• Consultar as vagas efetivamente liberadas antes de reduzir o pacote.
• Em action_required, seguir a orientação explícita recebida; não remover manualmente aplicativos ou parceria empresarial ampla para tentar acelerar.

Regras desta operação

• POST, PATCH e DELETE usam corpo JSON e fazem encerramento lógico; não apagam o histórico nem excluem contas Meta.
• Não envie WABA, business_id, tokens, manifestos, flags de exclusividade ou permissões no body. A HookCloud deriva o alcance a partir do cliente autenticado e confirma as dependências.
• A relação comercial tem alcance de portfólio, não de telefone. Uma outra conexão do mesmo parceiro, de outro parceiro ou de outro produto HookCloud pode exigir sua preservação. Histórico comprovadamente desligado não conta como dependência ativa.
• Nenhuma varredura automática encerra clientes antigos apenas porque já estavam canceled. Esta operação nasce da solicitação explícita atual.
• Durante o encerramento, novas conexões, movimentações, mesclagem e reativação que alterariam seu alcance são bloqueadas. Reativar o cadastro após conclusão não reconecta os números automaticamente.
• Sua plataforma deve verificar e autenticar o evento de cobrança do seu cliente e então chamar esta API. A Stripe da HookCloud administra o contrato do parceiro com a HookCloud; não conhece automaticamente a assinatura do seu cliente final.

Lê a solicitação de encerramento já registrada pela HookCloud, com progresso técnico, situação das parcerias e explicações legíveis. Use esse resultado para acompanhar o ex-cliente no seu painel sem consultar a Meta diretamente.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• Conhecer o customer_id ou external_customer_id do cliente no parceiro autenticado.
• Ter solicitado o encerramento por deactivate-partner-customer.

Autenticação e permissão

Partner API Key ativa com customers.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=get-customer-offboarding&external_customer_id=cliente-001

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

Retorna HTTP 200 com ok, partner_id, partner_customer_id, external_customer_id, status, archived e offboarding. status é o estado do cliente; offboarding.status é o estado do processamento. O resumo e os campos têm o mesmo significado do POST. A consulta não inicia nem retoma escritas remotas. Ausência de job não significa que os números foram desligados.

Campos retornados que atualizam o painel

Erros e como agir

• 404 customer_not_found: cliente não encontrado no parceiro.
• 404 customer_offboarding_not_found: não há solicitação correspondente para esse cliente.

Depois desta chamada

• Se completed, apresentar o encerramento concluído e distinguir relações removidas das preservadas por compartilhamento.
• Se pending, acompanhar o processamento sem disparar várias solicitações concorrentes.
• Se action_required, mostrar issues[].message e seguir a orientação antes de continuar; não inferir sucesso pelo tempo decorrido. Em customer_cleanup_scope_limit, a HookCloud precisa avaliar o grupo: o GET não reinicia a conferência e não há repetição automática desse grupo.

Regras desta operação

• O GET usa somente dados locais e pode ser armazenado em cache por alguns segundos.
• Não confunda commercial.preserved_shared com erro: uma relação corretamente preservada pode ser resultado final do encerramento.
• Não use all_relationships_removed para decidir se a vaga de um número está livre; confira a conclusão técnica e os dados de capacidade.

Reabre um cadastro cancelado elegível, removendo o arquivamento e definindo status=active. A operação atua no cliente comercial; não recupera tokens revogados, não reinscreve callbacks e não executa um novo Embedded Signup.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• O cadastro não pode estar mesclado nem com dados pessoais eliminados.
• Se estiver cancel_pending, concluir a desconexão pendente antes de reativar.

Autenticação e permissão

Partner API Key ativa com customers.write ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=reactivate-partner-customer

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "external_customer_id": "cliente-001",
  "reason": "Retomar teste"
}

O que preencher em cada campo

Como ler a resposta

Retorna ok, partner_id, partner_customer_id, external_customer_id, status=active e archived=false. Esses campos confirmam a reabertura cadastral, não a conexão de WhatsApp. Use get-partner-customer para escolher quais instâncias precisam de nova conexão.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 404 customer_not_found: cliente não acessível.
• 409 customer_unavailable: mesclado ou com dados eliminados.
• 409 customer_deactivation_pending: desligamento anterior ainda precisa ser concluído.

Depois desta chamada

• Consultar o cliente e listar as instâncias.
• Gerar uma sessão adequada com create-connect-session ou criar uma nova instância, conforme o estado encontrado.

Regras desta operação

• status=active do cliente e status=connected da instância são estados diferentes.
• Não restaure credencial Meta antiga a partir de logs para evitar o fluxo de reconexão.

Cria uma instância para um número do cliente. A HookCloud gera uma instance_key imutável; não preencha esse campo. O nome inicial serve até a Meta aprovar o nome de exibição. Depois, instance_name acompanha automaticamente o nome aprovado da Meta.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Webhook global habilitado, primário e com verificação GET salva. A HookCloud envia hub.mode=subscribe, hub.verify_token e hub.challenge=1234; seu servidor deve conferir o token e responder HTTP 200 com somente 1234 em texto puro. Testar sem salvar não libera cadastros. Ative também o POST na mesma URL para receber eventos.
• Cliente existente, ativo e elegível para novas conexões.
• Cobrança e controles de risco devem permitir a criação; a capacidade efetiva é confirmada pela lógica de conexão.

Autenticação e permissão

Partner API Key ativa com instances.write ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=create-customer-instance

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json",
  "Idempotency-Key": "UUID_UNICO_PARA_ESTA_ALTERACAO"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "external_customer_id": "cliente-001",
  "instance_name": "Instância de teste",
  "create_connect_session": true
}

O que preencher em cada campo

Como ler a resposta

Retorna HTTP 201 para criação ou 200 para reaproveitamento, com reused, partner_customer_id, external_customer_id, instance_id, instance_key, instance_name, verified_name, effective_business_name, name_source, status, occupies_slot, slot_state, used_slots e slot_limit. Se create_connect_session=true, também retorna connect_session_id, connect_url e connect_expires_at; caso contrário, esses campos ficam null. Guarde instance_id/instance_key e entregue connect_url ao usuário que fará a autorização. Em repetição idempotente, o status HTTP e o corpo originais são preservados (inclusive reused, connect_url e connect_expires_at). Essa resposta representa a criação original; consulte get-partner-instance para o estado atual. O link não tem sua validade prorrogada pela repetição.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 409 partner_webhook_verification_required: configure, valide e salve o webhook em Endpoints/update-partner-webhook-endpoint antes de tentar criar cliente, instância ou sessão. A validação avulsa não libera a operação. Consulte get-partner-onboarding-status.
• 400 missing_instance_fields: faltou a identificação do cliente.
• 404 customer_not_found: crie o cadastro antes.
• 409 customer_inactive: cliente inativo/arquivado.
• Erros de cobrança/risco podem impedir iniciar uma nova conexão.
• 400 instance_key_server_managed: não defina uma chave nova; a HookCloud gera e devolve a chave.
• 423 meta_risk_customer_blocked: o cliente atingiu a política BAN/RED ou revisão manual; leia customer_risk. Vagas livres do parceiro não removem a trava. Não recadastre o cliente para contornar o histórico.
• 409 idempotency_key_reused: mesma chave com corpo diferente; para repetir, use o corpo original. Para editar dados, use a operação de atualização correspondente.
• 409 operation_in_progress: a primeira chamada com essa chave está em processamento; aguarde e repita a mesma requisição.
• 409 idempotency_result_unavailable: a operação anterior ficou interrompida ou seu resultado não pôde ser recuperado. Consulte a instância antes de iniciar outra operação; não gere outra chave automaticamente.
• 503 idempotency_result_pending: a criação pode ter sido concluída, mas o armazenamento da resposta falhou. Confira o cadastro antes de iniciar uma nova operação.
• 409 billing_sync_required: o período de cobrança ou trial confirmado expirou e precisa ser reconciliado. O proprietário deve abrir Assinatura no Portal e clicar em Atualizar para consultar a Stripe; se persistir, procurar o suporte. Não repita novas criações automaticamente. Isso não confirma recusa do cartão nem desconecta números já ativos.
• 400 invalid_ttl_hours: envie ttl_hours como número finito; se positivo, entre 1/60 de hora (1 minuto) e 168 horas (7 dias), nunca texto ou Infinity. Omissão, null ou valor não positivo usa o padrão configurado (fallback 24h). A rejeição ocorre antes de criar registros.

Depois desta chamada

• Abrir connect_url no navegador do responsável pelo negócio.
• Após concluir, consultar get-partner-instance para confirmar status e IDs Meta.

Regras desta operação

• Com a mesma Idempotency-Key e o mesmo corpo, repetir a criação não gera outro link. Se o link original expirar, use create-connect-session para a mesma instância.
• connect_session_metadata não é persistido aqui na implementação atual.
• O cadastro de uma instância pendente não equivale a conexão operacional nem a entrega de mensagens.
• Reservas técnicas novas e seguras têm TTL de 15 minutos, com limpeza na próxima solicitação de reserva. GET e passagem do tempo não liberam a vaga por si só. Reservas legadas, números em uso, callback ativo/incerto, configuração parcial e operação remota processing/needs_review permanecem protegidos. Não é carência de cobrança.
• Guarde instance_id e instance_key retornados. Para reconectar, reutilize a instância existente via create-connect-session; não crie uma nova a cada tentativa. A chave é gerada pelo servidor.
• Uma instance_key já existente pode ser usada apenas para reaproveitar a mesma instância por compatibilidade. Não se aceita uma chave personalizada nova.
• Após timeout, repita a mesma Idempotency-Key no mesmo endpoint e com o mesmo corpo, ou consulte as instâncias antes de criar. Não troque de endpoint ou de chave durante a repetição. Sem essa chave, uma nova chamada pode criar outra instância. Para renovar um link vencido ou reconectar, use create-connect-session com a instância persistida.
• O estado autoritativo da configuração vem de get-partner-onboarding-status. URL presente ou token configurado, isoladamente, não confirmam GET validado. Atualizações de um cliente já existente não são tratadas como novo cadastro.
• Toda instância nova registra o evento instance.created para entrega ao webhook. As duas rotas seguem esta regra; reaproveitamento e replay idempotente não geram outra ocorrência. Deduplique entregas por event_id. data.connect_url pode ser null se não foi solicitada sessão, se ela falhou ou se a entrega ocorreu antes do link ficar disponível; use a resposta HTTP ou create-connect-session sem recriar a instância.

Cria uma instância para um número do cliente. A HookCloud gera uma instance_key imutável; não preencha esse campo. O nome inicial serve até a Meta aprovar o nome de exibição. Depois, instance_name acompanha automaticamente o nome aprovado da Meta.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Webhook global habilitado, primário e com verificação GET salva. A HookCloud envia hub.mode=subscribe, hub.verify_token e hub.challenge=1234; seu servidor deve conferir o token e responder HTTP 200 com somente 1234 em texto puro. Testar sem salvar não libera cadastros. Ative também o POST na mesma URL para receber eventos.
• Assinatura elegível, cliente não arquivado e controles operacionais liberados.

Autenticação e permissão

Partner API Key ativa com instances.write ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=create-partner-instance

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json",
  "Idempotency-Key": "UUID_UNICO_PARA_ESTA_ALTERACAO"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "external_customer_id": "cliente-001",
  "customer_name": "Cliente de teste combinado",
  "create_connect_session": true
}

O que preencher em cada campo

Como ler a resposta

Retorna reused, partner_customer_id, external_customer_id, instance_id, instance_key, instance_name, status, occupies_slot, slot_state, display_phone_number, verified_name, quality_rating, used_slots, slot_limit e os dados opcionais de connect_session. HTTP 201 significa nova instância; 200 significa reaproveitamento. O campo warnings pode indicar um fallback aplicado. Use instance_id para as consultas posteriores. Em repetição idempotente, o status HTTP e o corpo originais são preservados (inclusive reused, connect_url e connect_expires_at). Essa resposta representa a criação original; consulte get-partner-instance para o estado atual. O link não tem sua validade prorrogada pela repetição.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 409 partner_webhook_verification_required: configure, valide e salve o webhook em Endpoints/update-partner-webhook-endpoint antes de tentar criar cliente, instância ou sessão. A validação avulsa não libera a operação. Consulte get-partner-onboarding-status.
• 400 invalid_payload: faltaram os valores finais necessários à criação.
• 403 partner_without_live_subscription: o backend não encontrou assinatura elegível.
• Erros de validação cadastral e bloqueios de cobrança/risco podem interromper a operação.
• 400 instance_key_server_managed: não defina uma chave nova; a HookCloud gera e devolve a chave.
• 423 meta_risk_customer_blocked: o cliente atingiu a política BAN/RED ou revisão manual; leia customer_risk. Vagas livres do parceiro não removem a trava. Não recadastre o cliente para contornar o histórico.
• 409 idempotency_key_reused: mesma chave com corpo diferente; para repetir, use o corpo original. Para editar dados, use a operação de atualização correspondente.
• 409 operation_in_progress: a primeira chamada com essa chave está em processamento; aguarde e repita a mesma requisição.
• 409 idempotency_result_unavailable: a operação anterior ficou interrompida ou seu resultado não pôde ser recuperado. Consulte a instância antes de iniciar outra operação; não gere outra chave automaticamente.
• 503 idempotency_result_pending: a criação pode ter sido concluída, mas o armazenamento da resposta falhou. Confira o cadastro antes de iniciar uma nova operação.
• 409 billing_sync_required: o período de cobrança ou trial confirmado expirou e precisa ser reconciliado. O proprietário deve abrir Assinatura no Portal e clicar em Atualizar para consultar a Stripe; se persistir, procurar o suporte. Não repita novas criações automaticamente. Isso não confirma recusa do cartão nem desconecta números já ativos.
• 400 invalid_ttl_hours: envie ttl_hours como número finito; se positivo, entre 1/60 de hora (1 minuto) e 168 horas (7 dias), nunca texto ou Infinity. Omissão, null ou valor não positivo usa o padrão configurado (fallback 24h). A rejeição ocorre antes de criar registros.

Depois desta chamada

• Entregar connect_url ao cliente e concluir o Embedded Signup.
• Usar get-partner-customer e get-partner-instance para conferir separadamente os dois recursos.

Regras desta operação

• Não é alias de create-customer-instance: o cadastro do cliente também participa da operação.
• Para uma edição pontual, use a operação específica e reduza efeitos sobre nome/contexto da instância.
• Guarde instance_id e instance_key retornados. Para reconectar, reutilize a instância existente via create-connect-session; não crie uma nova a cada tentativa. A chave é gerada pelo servidor.
• Uma instance_key já existente pode ser usada apenas para reaproveitar a mesma instância por compatibilidade. Não se aceita uma chave personalizada nova.
• Após timeout, repita a mesma Idempotency-Key no mesmo endpoint e com o mesmo corpo, ou consulte as instâncias antes de criar. Não troque de endpoint ou de chave durante a repetição. Sem essa chave, uma nova chamada pode criar outra instância. Para renovar um link vencido ou reconectar, use create-connect-session com a instância persistida.
• A repetição idempotente devolve o mesmo link, sem renovar a expiração. Para gerar um link novo, use create-connect-session com a instância existente.
• O estado autoritativo da configuração vem de get-partner-onboarding-status. URL presente ou token configurado, isoladamente, não confirmam GET validado. Atualizações de um cliente já existente não são tratadas como novo cadastro.
• Toda instância nova registra o evento instance.created para entrega ao webhook. As duas rotas seguem esta regra; reaproveitamento e replay idempotente não geram outra ocorrência. Deduplique entregas por event_id. data.connect_url pode ser null se não foi solicitada sessão, se ela falhou ou se a entrega ocorreu antes do link ficar disponível; use a resposta HTTP ou create-connect-session sem recriar a instância.

Lista os números/instâncias do parceiro em páginas, incluindo os IDs Meta e a situação local de capacidade e callback. A consulta pode ser filtrada por cliente e é a forma de conciliar todas as instâncias sem revelar suas credenciais.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Referência oficial Meta: Limites compartilhados do portfólio Meta · BSUID e usernames comerciais

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Credencial com acesso às instâncias do parceiro.
• Se filtrar por cliente, o cadastro precisa pertencer ao mesmo parceiro.

Autenticação e permissão

Partner API Key ativa com instances.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=list-partner-instances&page=1&page_size=20

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

Retorna ok, partner_id, items, total, page, page_size e pages. Cada item contém id, vínculos de parceiro/cliente, instance_key, nome, status, display_phone_number, verified_name, meta_phone_number_id, meta_waba_id, quality_rating, name_status, remote_callback_status, occupies_slot, slot_state e datas. Reaproveite items[].id como instance_id; meta_phone_number_id vira phone_number_id nas consultas Graph/Partner que usam esse nome. Atualização de28/09/2026: leia connection_health e os campos separados connection_status, authorization_status, callback_status, inventory_state, meta_account_state, messaging_capability, business_verification, meta_payment, evidence, issues e allowed_actions. A fotografia deve trazer data/fonte/completude; unknown não equivale a false. ready_to_operate permanece conservador. Apenas 141006 com prova completa da WABA exata mantém inventory_state=active, mas messaging_capability.state=blocked e ready_to_operate=false podem continuar. Não recalcular esses estados no seu sistema. operation informa id,kind,status,started_at,finished_at,lease_until,result_code e steps; observation_scope separa current de historical. processing não confirma conclusão; needs_review pede reconciliação sem repetir a ação. request_id no JSON e X-Request-ID no cabeçalho permitem rastrear esta requisição; não são chaves de idempotência. instance_name acompanha o nome aprovado; name_status identifica a aprovação e evidence.checked_at informa a observação. Use o mesmo GET de instância para atualizar seu painel; não precisa de uma rota exclusiva de nome. A sincronização automática é eventual, com cadência controlada e backoff; não é uma leitura em tempo real a cada tela. meta_business_name e meta_waba_name identificam o portfólio e a WABA, quando informados pela Meta; meta_synced_at e os metadados meta_sync indicam a sincronização. Eventos hookcloud.instance.updated notificam mudanças desses dados. customer_risk contém a política individual do cliente: ban_count_30d, red_count_30d, limits={ban:20,red:5}, window_days=30, block_new_connections, reasons, next_exit_at, next_unlock_at e a cobertura histórica. Os limites bloqueiam novas conexões desse cliente, mesmo com vagas no pacote, sem desligar números existentes. Atualize seu cache com hookcloud.customer.risk_updated e reconcilie pela Partner API. Pagamento: meta_payment.status confirmed exige fonte de pagamento identificada na WABA; no_issue_detected significa consulta completa sem pendência, sem confirmar método. action_required preserva pendências e unknown informa falta de evidência atual. method_presence pode ser identified, not_confirmed ou unknown; nenhuma destas respostas expõe cartão ou identificador financeiro. business_verification informa a verificação empresarial explícita e separada do nome aprovado. Confira checked_at/source e acompanhe hookcloud.instance.health_updated. Perfil opcional: meta_profile.messaging_limit e meta_profile.username trazem status, valor, fonte, checked_at, stale e unavailable_reason. O limite moderno é compartilhado pelo portfólio em 24 horas móveis, não saldo disponível. Username reserved não confirma uso ativo; estado ausente permanece null. O cache desses campos é de até 6 horas, independente da evidência de saúde. Mudanças materiais são enviadas em hookcloud.instance.health_updated; mudança apenas de timestamp não gera novo evento. first_connected_at informa a primeira conexão registrada da identidade de número dentro do parceiro; null significa histórico não confirmado. Reconexão e movimentação dentro do mesmo parceiro não reiniciam essa data. Consulte o significado completo nos campos de resposta. Registro do número: phone.status PENDING, PENDING_REGISTRATION ou UNVERIFIED na identidade atual não confirma disponibilidade de envio, mesmo que a WABA informe AVAILABLE. Sem bloqueio, limitação ou restrição real prioritária, connection_health.state e messaging_capability.state ficam unknown, messaging_capability.reason=meta_registration_not_confirmed, ready_to_operate=false e inventory_state=attention. O status técnico connected pode permanecer. issues mantém o código meta_phone_not_confirmed_connected. Exiba “Confirmação pendente na Meta”; não conclua banimento, não desconecte nem crie outro vínculo automaticamente. A regra financeira de 141006 não transforma registro pendente em inventário pronto. Essa classificação usa a evidência já armazenada e não acrescenta GET à Meta; acompanhe o webhook e as datas, sem polling extra. panel_category é a categoria de exibição calculada pela HookCloud: active, processing, verification_pending, account_alert, restricted, banned, callback_review, attention ou disconnected. O Portal reúne históricos confirmados em Substituídos, com o subtipo no próprio card; não há abas separadas de Transferidos ou Encerrados. connection_history registra trocas de identidade confirmadas, com status superseded e subtype meta_identity_replacement. Uma reconexão normal pode atualizar os IDs automaticamente quando a nova autorização e a consulta à Meta comprovam o mesmo número, com o vínculo anterior encerrado. Mover uma instância entre clientes, reconectar sem mudança de IDs ou apenas observar um telefone igual não cria histórico de substituição. Não derive banimento de pagamento, RED ou erro técnico. A categoria não altera vagas nem permissões: use allowed_actions e occupies_slot. Após desconexão concluída, status legado permanece canceled, connection_status é inactive e observation_scope é historical. Falha de callback ou de credencial, isoladamente, não é histórico de desconexão. meta_link distingue vínculo removido confirmado de acesso não confirmado; connection_history lista identidades antigas substituídas, sem duplicar a instância atual ou capacidade. Leia o significado de cada campo abaixo. Uma remoção assinada deixa a instância canceled, o vínculo inativo, envio unavailable e capacidade liberada localmente, sem declarar callback removido nem token global revogado.

Nesta listagem, os campos da instância abaixo ficam dentro de cada objeto de items[]. O request_id pertence à resposta HTTP completa; total, page, page_size e pages descrevem a paginação.

Campos retornados que atualizam o painel

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 invalid_customer_id: filtro de UUID inválido.
• 404 customer_not_found: cliente do filtro não acessível.
• 400 invalid_instance_status: filtro fora dos estados aceitos.
• 400 invalid_pagination: paginação inválida.

Depois desta chamada

• Consultar get-partner-instance para detalhes.
• Usar o ID correto da instância em atualização, token ou nova sessão.

Regras desta operação

• A lista não consulta a Graph API em tempo real.
• Instância paused ainda pode ocupar vaga; use occupies_slot/slot_state e a situação de desligamento.
• O sistema externo é controlado pelo assinante. HookCloud confirma sua conexão/configuração e expõe evidências; callback ativo não garante recebimento/processamento no sistema externo. Não repetir POSTs para atualizar saúde. A atualização deve usar refresh-partner-instance-meta respeitando cooldown/retorno da API.
• Use os campos adicionais sem remover os campos antigos ao atualizar seu consumidor. Não trate UNKNOWN de qualidade como GREEN, nem pagamento desconhecido como sem cartão. Guia: https://developers.hookcloud.app/connection-health.html
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.
• Prefira webhooks e o GET local para atualizar o painel. Limite e username usam cache opcional de até 6 horas; refreshed_at da consulta geral não substitui checked_at de cada observação.
• As informações opcionais indisponíveis ficam neutras e não tornam a conexão bloqueada nem liberada. Não use valores antigos em metadata para preencher o que a Meta não confirmou na identidade atual.
• Não marque Desconectado, BAN ou Substituído a partir de erro Graph genérico, pagamento, qualidade RED ou coincidência do telefone. Aguarde o estado calculado e a evidência da identidade atual. Histórico substituído é somente leitura, sob a mesma instance_key.
• Para importar números existentes, guarde items[].id, partner_id e partner_customer_id e reutilize a instância; não chame create-customer-instance para cada importação. A lista tem dados de saúde e perfil, mas o link whatsapp_manager_url é fornecido pelo GET individual get-partner-instance. Reconciliação e reconexão não devem consumir uma nova vaga.

Consolida o estado de uma instância: cadastro, cliente, conexão WhatsApp, dados Meta, callback, risco, sessões recentes e capacidade. É o principal ponto de verificação após o Embedded Signup. A consulta mostra se existe credencial ativa, mas não retorna o token em texto. Também fornece whatsapp_manager_url para implementar o botão WhatsApp Manager no painel do seu assinante.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Referência oficial Meta: Limites compartilhados do portfólio Meta · BSUID e usernames comerciais

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Conhecer exatamente um dos identificadores suportados.
• Distinguir UUID interno, instance_key e phone_number_id da Meta.

Autenticação e permissão

Partner API Key ativa com instances.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-instance&instance_key=cliente-001-whatsapp-principal

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

Retorna instance_id/instance_key, nomes interno e oficial, status, occupies_slot/slot_state, phone_number_id, waba_id, meta_business_id, graph_version, URLs de envio e WhatsApp Manager, sinais de credencial, estado de callback, erros, datas, customer, connection, recent_connect_sessions, used_slots e slot_limit. Guarde phone_number_id e waba_id para operações Meta; use a existência de credencial e o estado connected como sinais separados. recent_connect_sessions mostra até cinco sessões e não revela tokens de link. Atualização de28/09/2026: leia connection_health e os campos separados connection_status, authorization_status, callback_status, inventory_state, meta_account_state, messaging_capability, business_verification, meta_payment, evidence, issues e allowed_actions. A fotografia deve trazer data/fonte/completude; unknown não equivale a false. ready_to_operate permanece conservador. Apenas 141006 com prova completa da WABA exata mantém inventory_state=active, mas messaging_capability.state=blocked e ready_to_operate=false podem continuar. Não recalcular esses estados no seu sistema. operation informa id,kind,status,started_at,finished_at,lease_until,result_code e steps; observation_scope separa current de historical. processing não confirma conclusão; needs_review pede reconciliação sem repetir a ação. request_id no JSON e X-Request-ID no cabeçalho permitem rastrear esta requisição; não são chaves de idempotência. instance_name acompanha o nome aprovado; name_status identifica a aprovação e evidence.checked_at informa a observação. Use o mesmo GET de instância para atualizar seu painel; não precisa de uma rota exclusiva de nome. A sincronização automática é eventual, com cadência controlada e backoff; não é uma leitura em tempo real a cada tela. meta_business_name e meta_waba_name identificam o portfólio e a WABA, quando informados pela Meta; meta_synced_at e os metadados meta_sync indicam a sincronização. Eventos hookcloud.instance.updated notificam mudanças desses dados. customer_risk contém a política individual do cliente: ban_count_30d, red_count_30d, limits={ban:20,red:5}, window_days=30, block_new_connections, reasons, next_exit_at, next_unlock_at e a cobertura histórica. Os limites bloqueiam novas conexões desse cliente, mesmo com vagas no pacote, sem desligar números existentes. Atualize seu cache com hookcloud.customer.risk_updated e reconcilie pela Partner API. Pagamento: meta_payment.status confirmed exige fonte de pagamento identificada na WABA; no_issue_detected significa consulta completa sem pendência, sem confirmar método. action_required preserva pendências e unknown informa falta de evidência atual. method_presence pode ser identified, not_confirmed ou unknown; nenhuma destas respostas expõe cartão ou identificador financeiro. business_verification informa a verificação empresarial explícita e separada do nome aprovado. Confira checked_at/source e acompanhe hookcloud.instance.health_updated. Perfil opcional: meta_profile.messaging_limit e meta_profile.username trazem status, valor, fonte, checked_at, stale e unavailable_reason. O limite moderno é compartilhado pelo portfólio em 24 horas móveis, não saldo disponível. Username reserved não confirma uso ativo; estado ausente permanece null. O cache desses campos é de até 6 horas, independente da evidência de saúde. Mudanças materiais são enviadas em hookcloud.instance.health_updated; mudança apenas de timestamp não gera novo evento. first_connected_at informa a primeira conexão registrada da identidade de número dentro do parceiro; null significa histórico não confirmado. Reconexão e movimentação dentro do mesmo parceiro não reiniciam essa data. Consulte o significado completo nos campos de resposta. Registro do número: phone.status PENDING, PENDING_REGISTRATION ou UNVERIFIED na identidade atual não confirma disponibilidade de envio, mesmo que a WABA informe AVAILABLE. Sem bloqueio, limitação ou restrição real prioritária, connection_health.state e messaging_capability.state ficam unknown, messaging_capability.reason=meta_registration_not_confirmed, ready_to_operate=false e inventory_state=attention. O status técnico connected pode permanecer. issues mantém o código meta_phone_not_confirmed_connected. Exiba “Confirmação pendente na Meta”; não conclua banimento, não desconecte nem crie outro vínculo automaticamente. A regra financeira de 141006 não transforma registro pendente em inventário pronto. Essa classificação usa a evidência já armazenada e não acrescenta GET à Meta; acompanhe o webhook e as datas, sem polling extra. panel_category é a categoria de exibição calculada pela HookCloud: active, processing, verification_pending, account_alert, restricted, banned, callback_review, attention ou disconnected. O Portal reúne históricos confirmados em Substituídos, com o subtipo no próprio card; não há abas separadas de Transferidos ou Encerrados. connection_history registra trocas de identidade confirmadas, com status superseded e subtype meta_identity_replacement. Uma reconexão normal pode atualizar os IDs automaticamente quando a nova autorização e a consulta à Meta comprovam o mesmo número, com o vínculo anterior encerrado. Mover uma instância entre clientes, reconectar sem mudança de IDs ou apenas observar um telefone igual não cria histórico de substituição. Não derive banimento de pagamento, RED ou erro técnico. A categoria não altera vagas nem permissões: use allowed_actions e occupies_slot. Após desconexão concluída, status legado permanece canceled, connection_status é inactive e observation_scope é historical. Falha de callback ou de credencial, isoladamente, não é histórico de desconexão. meta_link distingue vínculo removido confirmado de acesso não confirmado; connection_history lista identidades antigas substituídas, sem duplicar a instância atual ou capacidade. Leia o significado de cada campo abaixo. Uma remoção assinada deixa a instância canceled, o vínculo inativo, envio unavailable e capacidade liberada localmente, sem declarar callback removido nem token global revogado. HTTP 202 com disconnect_status=awaiting_user e meta_disconnect.status=action_required pode aparecer em solicitações legadas. O campo status preserva o estado técnico real, por exemplo connected. Não marque concluído nem libere a vaga. Se safe_to_recheck=true e recheck_mode=resume_hookcloud_integration, ofereça Retomar desconexão automática, repetindo deactivate-partner-instance para a mesma instance_id/instance_key, operação e geração. Esse modo permite confirmar a rota e desativar o acesso local sem exigir o celular nem revogar um grant compartilhado. O nome legado action_required=disconnect_in_whatsapp_business_app não deve prevalecer sobre message/instructions e recheck_mode atuais. read_only continua significando conferência de uma intenção existente, sem repetir DELETE; retry_safe_preflight é compatibilidade com uma recusa anterior à intenção e pode iniciar as primeiras escritas autorizadas. Sem safe_to_recheck, acompanhe o GET local e os eventos; não repita automaticamente. No GET, disconnect_cleanup (também em connection_health) descreve a conclusão persistida. status=completed, scope=hookcloud_integration e proof_source=phone_callback_removed_local_access_disabled confirmam a retirada da rota do número e a desativação do acesso local. Confira connection_generation, operation_id, confirmed_at, callback.status=removed, local_authorization=disabled e token_revocation.status=local_disabled. remote_authorization=preserved_shared e token_revocation.remote_status=preserved_shared informam que a autorização Meta foi preservada para manter outras conexões; unknown/unconfirmed não afirmam revogação. commercial_relationship.status=unchanged separa a parceria comercial. O contrato anterior scope=app_authorization e proof_source=grant_revoked_readback continua válido quando houve revogação comprovada: token_revocation.status=confirmed_invalid. Campos ausentes ou null não confirmam essas ações. Não são expostos token, segredo ou titular do token.

Nesta consulta individual, os identificadores ficam na raiz da resposta. Os campos de saúde abaixo usam connection_health; parte deles também é retornada na raiz por compatibilidade.

Campos retornados que atualizam o painel

<a id="abrir-whatsapp-manager"
   target="_blank"
   rel="noopener noreferrer"
   hidden>
  Abrir WhatsApp Manager
</a>

function atualizarBotaoWhatsAppManager(dadosDaInstancia) {
  const botao = document.getElementById('abrir-whatsapp-manager');
  if (!botao) return;

  // Remova qualquer URL anterior ao trocar de cliente ou instância.
  botao.hidden = true;
  botao.removeAttribute('href');

  const endereco = dadosDaInstancia?.whatsapp_manager_url;
  if (typeof endereco !== 'string' || !endereco.trim()) return;

  try {
    const url = new URL(endereco);
    if (url.origin !== 'https://business.facebook.com') return;
    if (url.username || url.password) return;

    botao.href = url.href;
    botao.hidden = false;
  } catch {
    // URL indisponível ou inválida: mantenha o botão oculto.
  }
}

// Após seu backend devolver os dados autorizados da instância:
// atualizarBotaoWhatsAppManager(dadosDaInstancia);

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 missing_identifier: faltou seletor.
• 400 multiple_identifiers: enviou mais de uma alternativa.
• 400 invalid_instance_id: usou um código externo onde era necessário UUID.
• 404 instance_not_found: recurso não acessível à credencial.

Depois desta chamada

• Se os dados oficiais parecerem desatualizados, executar refresh-partner-instance-meta.
• Para operações Graph, obtenha o token autorizado pela rota reveal-partner-instance-meta-token.
• Usar whatsapp_manager_url no botão Abrir WhatsApp Manager do seu painel; consulte o exemplo HTML/JavaScript desta chamada.

Regras desta operação

• meta_access_token_available não é o token.
• phone_number_id identifica seu número comercial; não use esse ID como recipient das mensagens.
• Não trate uma URL de envio retornada como comprovação de entrega.
• O sistema externo é controlado pelo assinante. HookCloud confirma sua conexão/configuração e expõe evidências; callback ativo não garante recebimento/processamento no sistema externo. Não repetir POSTs para atualizar saúde. A atualização deve usar refresh-partner-instance-meta respeitando cooldown/retorno da API.
• Use os campos adicionais sem remover os campos antigos ao atualizar seu consumidor. Não trate UNKNOWN de qualidade como GREEN, nem pagamento desconhecido como sem cartão. Guia: https://developers.hookcloud.app/connection-health.html
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.
• Prefira webhooks e o GET local para atualizar o painel. Limite e username usam cache opcional de até 6 horas; refreshed_at da consulta geral não substitui checked_at de cada observação.
• As informações opcionais indisponíveis ficam neutras e não tornam a conexão bloqueada nem liberada. Não use valores antigos em metadata para preencher o que a Meta não confirmou na identidade atual.
• Não marque Desconectado, BAN ou Substituído a partir de erro Graph genérico, pagamento, qualidade RED ou coincidência do telefone. Aguarde o estado calculado e a evidência da identidade atual. Histórico substituído é somente leitura, sob a mesma instance_key.

Consulta as observações de saúde da instância, separadas por generation. Reconectar ou trocar o vínculo não transforma evidência antiga em estado atual. Esta consulta não chama a Graph API.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Chave do parceiro com instances.read ou JWT autorizado. A instância precisa pertencer ao parceiro autenticado.

Autenticação e permissão

Partner API Key ativa com instances.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-instance-history&instance_id=UUID_DA_INSTANCIA&page=1&page_size=25

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

HTTP 200: schema_version partner-health-v2, instance_id, connection_generation atual, items com id/generation/operation_id/health/created_at, total/page/page_size. history_complete é false; coverage observations_since_deployment informa que não existe backfill de todo o passado. health usa o mesmo contrato de estados separados do get-partner-instance.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 para identificador/paginação inválidos; 401/403 quando autenticação ou escopo não permitem; 404 quando a instância não está acessível.

Depois desta chamada

• Compare generation e created_at com a conexão atual. Leia get-partner-instance para a observação vigente.
• Para uma consulta externa recente use refresh-partner-instance-meta explicitamente, respeitando autorização e cooldown.

Regras desta operação

• Nenhuma alteração na Meta ou no sistema externo do assinante é feita por este GET. Não apresente RED/BAN antigo como restrição atual.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Consulta a saúde e os dados oficiais do número na Graph API com a credencial da instância e grava a observação no Partner. Dados opcionais de limite e username têm cache próprio e podem ser reutilizados nesta atualização; consulte checked_at de cada fato, sem tratar refreshed_at como nova leitura de todos os campos.

Referência oficial Meta: Números, registro e permissões · Webhooks da Cloud API · Limites compartilhados do portfólio Meta · BSUID e usernames comerciais

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Instância com credencial Meta utilizável e phone_number_id.
• Enviar exatamente um identificador; múltiplos seletores são rejeitados para evitar identidade ambígua.

Autenticação e permissão

Partner API Key ativa com instances.write ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=refresh-partner-instance-meta

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "instance_key": "cliente-001-whatsapp-principal"
}

O que preencher em cada campo

Como ler a resposta

Retorna instance_id, instance_key, instance_name, verified_name/meta_verified_name, effective_business_name, name_source, display_phone_number, quality_rating, name_status, code_verification_status, IDs Meta, whatsapp_manager_url, meta_phone_number_details e refreshed_at. Use refreshed_at para mostrar quando ocorreu a consulta e get-partner-instance para a visão operacional completa. Atualização de28/09/2026: leia connection_health e os campos separados connection_status, authorization_status, callback_status, inventory_state, meta_account_state, messaging_capability, business_verification, meta_payment, evidence, issues e allowed_actions. A fotografia deve trazer data/fonte/completude; unknown não equivale a false. ready_to_operate permanece conservador. Apenas 141006 com prova completa da WABA exata mantém inventory_state=active, mas messaging_capability.state=blocked e ready_to_operate=false podem continuar. Não recalcular esses estados no seu sistema. operation informa id,kind,status,started_at,finished_at,lease_until,result_code e steps; observation_scope separa current de historical. processing não confirma conclusão; needs_review pede reconciliação sem repetir a ação. request_id no JSON e X-Request-ID no cabeçalho permitem rastrear esta requisição; não são chaves de idempotência. instance_name acompanha o nome aprovado; name_status identifica a aprovação e evidence.checked_at informa a observação. Use o mesmo GET de instância para atualizar seu painel; não precisa de uma rota exclusiva de nome. A sincronização automática é eventual, com cadência controlada e backoff; não é uma leitura em tempo real a cada tela. meta_business_name e meta_waba_name identificam o portfólio e a WABA, quando informados pela Meta; meta_synced_at e os metadados meta_sync indicam a sincronização. Eventos hookcloud.instance.updated notificam mudanças desses dados. Pagamento: meta_payment.status confirmed exige fonte de pagamento identificada na WABA; no_issue_detected significa consulta completa sem pendência, sem confirmar método. action_required preserva pendências e unknown informa falta de evidência atual. method_presence pode ser identified, not_confirmed ou unknown; nenhuma destas respostas expõe cartão ou identificador financeiro. business_verification informa a verificação empresarial explícita e separada do nome aprovado. Confira checked_at/source e acompanhe hookcloud.instance.health_updated. Perfil opcional: meta_profile.messaging_limit e meta_profile.username trazem status, valor, fonte, checked_at, stale e unavailable_reason. O limite moderno é compartilhado pelo portfólio em 24 horas móveis, não saldo disponível. Username reserved não confirma uso ativo; estado ausente permanece null. O cache desses campos é de até 6 horas, independente da evidência de saúde. Mudanças materiais são enviadas em hookcloud.instance.health_updated; mudança apenas de timestamp não gera novo evento. first_connected_at informa a primeira conexão registrada da identidade de número dentro do parceiro; null significa histórico não confirmado. Reconexão e movimentação dentro do mesmo parceiro não reiniciam essa data. Consulte o significado completo nos campos de resposta. Registro do número: phone.status PENDING, PENDING_REGISTRATION ou UNVERIFIED na identidade atual não confirma disponibilidade de envio, mesmo que a WABA informe AVAILABLE. Sem bloqueio, limitação ou restrição real prioritária, connection_health.state e messaging_capability.state ficam unknown, messaging_capability.reason=meta_registration_not_confirmed, ready_to_operate=false e inventory_state=attention. O status técnico connected pode permanecer. issues mantém o código meta_phone_not_confirmed_connected. Exiba “Confirmação pendente na Meta”; não conclua banimento, não desconecte nem crie outro vínculo automaticamente. A regra financeira de 141006 não transforma registro pendente em inventário pronto. Essa classificação usa a evidência já armazenada e não acrescenta GET à Meta; acompanhe o webhook e as datas, sem polling extra. panel_category é a categoria de exibição calculada pela HookCloud: active, processing, verification_pending, account_alert, restricted, banned, callback_review, attention ou disconnected. O Portal reúne históricos confirmados em Substituídos, com o subtipo no próprio card; não há abas separadas de Transferidos ou Encerrados. connection_history registra trocas de identidade confirmadas, com status superseded e subtype meta_identity_replacement. Uma reconexão normal pode atualizar os IDs automaticamente quando a nova autorização e a consulta à Meta comprovam o mesmo número, com o vínculo anterior encerrado. Mover uma instância entre clientes, reconectar sem mudança de IDs ou apenas observar um telefone igual não cria histórico de substituição. Não derive banimento de pagamento, RED ou erro técnico. A categoria não altera vagas nem permissões: use allowed_actions e occupies_slot. Após desconexão concluída, status legado permanece canceled, connection_status é inactive e observation_scope é historical. Falha de callback ou de credencial, isoladamente, não é histórico de desconexão.

O retorno inclui a projeção atual da instância e connection_health. O perfil opcional aparece em ambos; seus timestamps são independentes de refreshed_at. Esta chamada produz uma consulta remota de saúde e escrita local, não apenas uma leitura do cache.

Campos retornados que atualizam o painel

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 single_identifier_required: informe exatamente um seletor de instância.
• 404 instance_not_found.
• 409 meta_phone_number_id_missing: conexão ainda não tem ID Meta.
• 409 health_observation_commit_failed: a observação não pôde ser gravada; releia o estado antes de repetir.
• Erros de credencial/Graph podem aparecer como unexpected_error com detalhes.
• 429 health_refresh_rate_limited: aguarde o cooldown de 30 segundos.
• 409 stale_connection_generation/instance_operation_in_progress/operation_lease_lost: houve operação concorrente ou geração mudou. Releia antes de repetir.
• 409 health_evidence_changed: evidência de risco mudou durante a consulta. Releia o estado e respeite o cooldown antes de nova atualização.

Depois desta chamada

• Atualizar o painel com os nomes/qualidade confirmados.
• Consultar o erro Meta antes de repetir uma chamada que falhou.

Regras desta operação

• É uma escrita local e uma chamada remota, apesar de parecer apenas atualização visual.
• Não altera oficialmente o nome da empresa na Meta nem realiza novo registro de número.
• O sistema externo é controlado pelo assinante. HookCloud confirma sua conexão/configuração e expõe evidências; callback ativo não garante recebimento/processamento no sistema externo. Não repetir POSTs para atualizar saúde. A atualização deve usar refresh-partner-instance-meta respeitando cooldown/retorno da API.
• Use os campos adicionais sem remover os campos antigos ao atualizar seu consumidor. Não trate UNKNOWN de qualidade como GREEN, nem pagamento desconhecido como sem cartão. Guia: https://developers.hookcloud.app/connection-health.html
• Prefira webhooks e o GET local para atualizar o painel. Limite e username usam cache opcional de até 6 horas; refreshed_at da consulta geral não substitui checked_at de cada observação.
• As informações opcionais indisponíveis ficam neutras e não tornam a conexão bloqueada nem liberada. Não use valores antigos em metadata para preencher o que a Meta não confirmou na identidade atual.
• Atualização manual não invalida todos os caches: dados empresariais são reutilizados por até 24 horas, pagamento por até 6 horas (24 horas após permission_error) e limite/username por até 6 horas. Eventos pertinentes afetam somente seu domínio, com piso de 15 minutos entre leituras desse domínio. Falhas transitórias podem ter reavaliação após 5 minutos, sempre sujeita ao backoff e ao orçamento global de leitura da Meta.

Ajusta o nome provisório antes da aprovação pela Meta. Depois da aprovação, instance_name acompanha o nome verificado e não pode divergir dele. Não muda o nome na Meta; solicite essa mudança no WhatsApp Manager.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Instância existente do parceiro.
• Nome interno não vazio de até 160 caracteres.

Autenticação e permissão

Partner API Key ativa com instances.write ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=update-partner-instance-label

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "instance_key": "cliente-001-whatsapp-principal",
  "instance_name": "Nome interno atualizado"
}

O que preencher em cada campo

Como ler a resposta

Retorna a instância e seu nome canônico. Se existir nome aprovado na Meta, esse nome prevalece. Guarde verified_name, name_status e name_source para explicar a origem no seu painel.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 missing_identifier/missing_instance_name: ausência de recurso ou nome.
• 400 instance_name_too_long: mais de 160 caracteres.
• 404 instance_not_found.
• 500 instance_label_update_failed: falha ao gravar a alteração.
• 409 instance_name_managed_by_meta: o nome aprovado da Meta é canônico; não pode ser substituído por um nome diferente no Partner.

Depois desta chamada

• Atualizar o nome interno no seu seletor de canais.
• Se precisar conferir o nome oficial, usar refresh-partner-instance-meta.

Regras desta operação

• Não altera username, perfil comercial nem display name aprovado pela Meta.
• Não renomeia a chave instance_key.
• Não use esta rota para substituir um nome já aprovado na Meta por um apelido local. O seu sistema pode manter um apelido próprio separado.

Retorna a credencial Meta em texto para uso autorizado no backend do assinante, junto aos IDs do número/WABA e à versão Graph. É a ponte entre a gestão de conexão do Partner e as chamadas diretas à Graph API. Use o meta_access_token retornado no header Authorization da chamada Graph seguinte.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Instância conectada com credencial disponível e acesso operacional permitido.
• Scope específico instances.credentials.read para API key, ou role JWT autorizada.
• Ambiente do backend deve tratar o retorno como segredo.

Autenticação e permissão

Partner API Key ativa com instances.credentials.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=reveal-partner-instance-meta-token

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "instance_key": "cliente-001-whatsapp-principal"
}

O que preencher em cada campo

Como ler a resposta

Retorna meta_access_token e access_token com a mesma credencial, além de instance_id/instance_key, phone_number_id/meta_phone_number_id, meta_waba_id/waba_id, app_id, graph_version, token_type, token_hint, expires_at, credential_updated_at, nomes e URLs de envio/gestão. Use meta_access_token somente no cabeçalho Bearer da Graph API. Confira se os IDs retornados pertencem à instância que você pretende usar antes de enviar.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 missing_identifier/multiple_identifiers/invalid_instance_id para seleção inválida.
• 403 para scope/role insuficiente ou bloqueio operacional.
• 404 instance_not_found.
• Ausência ou falha de credencial impede o retorno; não prossiga para a Graph com token vazio.
• 409 integration_disconnect_unconfirmed ou grant_disconnect_unconfirmed: desconexão em confirmação; a credencial não pode ser revelada. Após a conclusão, instance_not_connected impede revelação e o segredo local foi removido. Não faça retry automático nem use cópias antigas do token.

Depois desta chamada

• Executar a operação Meta pretendida com os IDs correspondentes à credencial.
• Descartar o token de saídas públicas e logs que não precisam dele.

Regras desta operação

• Nunca devolver o token ao cliente final em página pública.
• Não confundir token Meta com API key do Partner, JWT de login ou token do link de conexão.
• Os aliases reveal-meta-access-token e get-partner-instance-meta-token resolvem o mesmo handler; não são credenciais diferentes.
• Ao desconectar a integração, cesse o uso de qualquer token já copiado. Uma autorização Meta compartilhada pode continuar válida para outras instâncias; desativação e retirada do segredo na HookCloud não revogam essas cópias externas.
• Execute somente no servidor. Não grave credenciais no JavaScript entregue ao navegador, localStorage, banco de mensagens, exportação, prompt de IA ou telemetria. Confira partner_id, instance_id, phone_number_id e waba_id da resposta antes da chamada Graph; os escopos são exatos e instances.read não permite revelar credenciais.
• Antes de despachar uma fila antiga, confira status, cliente, IDs Meta e connection_generation pelo GET local. A geração é um UUID opaco: autorizações novas não devem reutilizar filas, janelas ou credenciais de uma conexão anterior.

Aliases aceitos: reveal-meta-access-token, get-partner-instance-meta-token. Prefira o nome do exemplo.

Solicita o desligamento de um único número, preservando os demais. Para número exclusivo da Cloud API, confirma callback e desregistro. Na coexistência com WhatsApp Business no celular, a Meta não permite /deregister. Quando o escopo da autorização for comprovadamente exclusivo e a Meta permitir a revogação, a HookCloud confirma a remoção do callback, da inscrição do app e a invalidação da autorização. Sem essa prova, não anuncia sucesso: mantém a vaga e apresenta confirmação pendente ou o passo manual no aplicativo.

Referência oficial Meta: Números, registro e permissões · Webhooks da Cloud API · Meta: coexistência e desconexão no aplicativo (Offboarding) · Meta: revogação de permissões e invalidação do token de usuário · Meta: Facebook Login for Business e tokens de integração empresarial · Meta: inscrição de aplicativos nos eventos da WABA

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Confirmar a instância correta antes de desligar.
• Ter acesso à credencial remota necessária para concluir a revogação/desconexão.
• Solicite primeiro na HookCloud. Aguarde o resultado e siga as instruções retornadas. Não remova previamente a parceria comercial, pois isso pode impedir a conferência do desligamento. O sistema não presume que um token funciona para apenas um número.

Autenticação e permissão

Partner API Key ativa com instances.write ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=deactivate-partner-instance

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "instance_key": "cliente-001-whatsapp-principal",
  "reason": "Encerramento de teste"
}

O que preencher em cada campo

Como ler a resposta

Em sucesso retorna ok, instance_id, instance_key, status=canceled, occupies_slot=false, slot_state=released, remote_callback, meta_disconnect, used_slots e slot_limit. A conclusão gera instance.canceled e notificação no sininho, deduplicadas. O cronômetro não confirma remoção nem libera capacidade. Para números coexistentes, meta_disconnect.status=completed, proof_source=phone_callback_removed_local_access_disabled, remote_cleanup_scope=hookcloud_integration e technical_disconnect_confirmed=true significam Desconectado da HookCloud. callback.status=removed confirma a retirada da rota; local_authorization=disabled e local_credential.status=disabled_and_purged confirmam que o acesso local foi desativado e o segredo removido do armazenamento da instância. No POST, token_revocation.status=not_attempted confirma que a revogação global não foi executada; remote_authorization=preserved_shared (ou unknown) distingue a autorização Meta remanescente. No GET, token_revocation.status=local_disabled é a leitura normalizada da desativação local; remote_status=preserved_shared (ou unconfirmed) não equivale a revoked. business_relationship.status=preserved significa que a parceria comercial pode continuar visível no portfólio Meta. remote_cleanup_confirmed=false é correto: esta prova não declara deregistro nem revogação global. Não é obrigatório desconectar o WhatsApp Business no celular para encerrar a integração HookCloud. A revogação global não é tentada quando pode afetar outros números. O caminho anterior grant_revoked_readback, com escopo app_authorization, continua representando revogação realmente confirmada; não transforme uma prova na outra. HTTP 202 com disconnect_status=confirming, safe_to_recheck=true e meta_disconnect.status=pending indica que ainda falta confirmação. O estado real e a capacidade permanecem; a mesma operação pode ser retomada sem repetir seus DELETEs ou outra escrita de resultado incerto. get-partner-instance apenas lê o estado armazenado; não realiza conferência remota. Em confirming, uma etapa posterior ainda não intentada pode ser executada pela primeira vez após as verificações de segurança. Não faça polling de POSTs. HTTP 202 com disconnect_status=awaiting_user e meta_disconnect.status=action_required pode aparecer em solicitações legadas. O campo status preserva o estado técnico real, por exemplo connected. Não marque concluído nem libere a vaga. Se safe_to_recheck=true e recheck_mode=resume_hookcloud_integration, ofereça Retomar desconexão automática, repetindo deactivate-partner-instance para a mesma instance_id/instance_key, operação e geração. Esse modo permite confirmar a rota e desativar o acesso local sem exigir o celular nem revogar um grant compartilhado. O nome legado action_required=disconnect_in_whatsapp_business_app não deve prevalecer sobre message/instructions e recheck_mode atuais. read_only continua significando conferência de uma intenção existente, sem repetir DELETE; retry_safe_preflight é compatibilidade com uma recusa anterior à intenção e pode iniciar as primeiras escritas autorizadas. Sem safe_to_recheck, acompanhe o GET local e os eventos; não repita automaticamente. No GET, disconnect_cleanup (também em connection_health) descreve a conclusão persistida. status=completed, scope=hookcloud_integration e proof_source=phone_callback_removed_local_access_disabled confirmam a retirada da rota do número e a desativação do acesso local. Confira connection_generation, operation_id, confirmed_at, callback.status=removed, local_authorization=disabled e token_revocation.status=local_disabled. remote_authorization=preserved_shared e token_revocation.remote_status=preserved_shared informam que a autorização Meta foi preservada para manter outras conexões; unknown/unconfirmed não afirmam revogação. commercial_relationship.status=unchanged separa a parceria comercial. O contrato anterior scope=app_authorization e proof_source=grant_revoked_readback continua válido quando houve revogação comprovada: token_revocation.status=confirmed_invalid. Campos ausentes ou null não confirmam essas ações. Não são expostos token, segredo ou titular do token. Após PARTNER_REMOVED assinado e validado, o contrato instance.meta_link_removed permanece separado: consulte meta_link.state=removed e a mesma geração. O GET pode não trazer operation depois de arquivada. Não confunda desligamento da integração com exclusão da conta WhatsApp, retirada de parceiros ou encerramento completo da coexistência na Meta.

Campos retornados que atualizam o painel

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 404 instance_not_found.
• 409 remote_callback_removal_failed: callback remoto não foi removido.
• 409 meta_send_access_revocation_failed / meta_waba_unsubscribe_failed / meta_access_token_revocation_failed: desligamento remoto incompleto.
• 409 meta_credential_missing_for_hard_disconnect: falta a credencial necessária; a vaga continua contando.

Depois desta chamada

• Se retornar HTTP 202, mantenha a capacidade ocupada e siga safe_to_recheck/recheck_mode e as instruções atuais, sem repetir automaticamente.
• Ofereça Retomar desconexão automática para resume_hookcloud_integration e Conferir desconexão para confirmação pendente. Use a mesma instância/operação/geração; uma resposta antiga não pode concluir uma nova conexão.
• Após status=canceled, occupies_slot=false e slot_state=released, mostre Desconectado da HookCloud e o alcance real de disconnect_cleanup. Confira o GET antes de reduzir pacotes.
• Se a operação continuar incerta sem ação permitida, encaminhe operation_id e o diagnóstico ao suporte, sem credenciais.

Regras desta operação

• DELETE precisa de corpo JSON e não apaga fisicamente o cadastro.
• Um erro não deve ser interpretado como autorização para reduzir a capacidade.
• Existe fallback legado por external_customer_id no código de mutação, mas o contrato do sistema usa instance_id/instance_key para evitar ambiguidade entre vários números.
• A remoção de parceria confirmada por webhook Meta assinado tem contrato próprio: instance.meta_link_removed. Ela desabilita a autorização local e libera a vaga do vínculo exato, mas não afirma callback removido ou deregistro executado. Erros Graph genéricos não acionam essa conclusão.
• Uma operação genericamente failed, needs_review ou stale não autoriza repetir uma mutação remota. Siga safe_to_recheck e recheck_mode quando explicitamente retornados: read_only consulta a intenção; retry_safe_preflight pode iniciar a primeira tentativa segura após recusa anterior ao registro de intenção. Um passo já intentado nunca recebe novo DELETE por essa conferência. Tempo decorrido nunca libera vaga.
• Callback, autorização do aplicativo e parceria comercial são vínculos distintos. A desconexão técnica não promete remover a empresa HookCloud do portfólio Meta. A retirada ampla de uma relação comercial pode afetar outros números ou ativos entre essas empresas.
• DELETE /me/permissions revoga uma autorização de aplicativo/usuário; a documentação genérica não garante suporte a todo BISU. A desconexão local da HookCloud não depende dessa revogação quando a autorização é compartilhada: preserve o grant e exponha a prova hookcloud_integration. Não declare revoked sem confirmação independente.
• A desconexão individual não remove a parceria comercial. O encerramento do cliente por deactivate-partner-customer avalia essa retirada separadamente, preservando relações compartilhadas. O endpoint comercial business/clients seleciona a relação inteira entre dois portfólios, sem seletor de telefone, e pode afetar outros ativos compartilhados entre essas empresas. Ele não é equivalente à revogação da autorização do app.

Corrige o vínculo de uma única instância para outro cliente do mesmo parceiro. A transferência preserva a instance_key e a conexão Meta; não dispara novo Embedded Signup nem altera o número comercial. É a opção adequada quando o cadastro foi associado à empresa errada.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Instância e cliente de destino pertencentes ao mesmo parceiro.
• Destino ativo e disponível para receber a instância.
• Conferir o vínculo atual antes de transferir.

Autenticação e permissão

Partner API Key ativa com instances.write ou *. Se optar por JWT, as funções permitidas são owner, admin.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=move-partner-instance-to-customer

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json",
  "Idempotency-Key": "UUID_UNICO_PARA_ESTA_ALTERACAO"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "instance_id": "UUID_DA_INSTANCIA",
  "target_customer_id": "TARGET_CUSTOMER_ID",
  "reason": "Teste de transferência"
}

O que preencher em cada campo

Como ler a resposta

Retorna ok, instance_id, instance_key, source_customer_id, target_customer_id, source_external_customer_id e target_external_customer_id, mais instance_key_unchanged=true e meta_connection_unchanged=true. O evento hookcloud.partner.instance.moved registra a mudança. Reaproveite target_customer_id no vínculo do seu sistema e consulte get-partner-instance para obter o customer final confirmado.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 invalid_instance_move_payload: IDs inválidos.
• 404 instance_not_found/target_customer_not_found.
• 409 instance_already_on_target_customer: vínculo já corresponde ao destino.
• 409 target_customer_unavailable/target_customer_inactive: cadastro não pode receber a instância.

Depois desta chamada

• Atualizar o vínculo no sistema externo.
• Conferir a instância e os históricos dos clientes envolvidos.

Regras desta operação

• Não transfere números entre parceiros diferentes.
• Preservar conexão Meta não significa trocar a titularidade empresarial da WABA; a operação reorganiza o cadastro interno.

Gera uma nova sessão temporária para conectar ou reconectar uma instância existente. O link contém um token exclusivo dessa jornada, diferente da API key do parceiro. Na reconexão normal, se a Meta devolver novos IDs para o mesmo número, a HookCloud verifica a autorização e atualiza o vínculo automaticamente, preservando instance_id e instance_key. O Portal não solicita IDs técnicos para essa atualização.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Webhook global habilitado, primário e com verificação GET salva. A HookCloud envia hub.mode=subscribe, hub.verify_token e hub.challenge=1234; seu servidor deve conferir o token e responder HTTP 200 com somente 1234 em texto puro. Testar sem salvar não libera cadastros. Ative também o POST na mesma URL para receber eventos.
• Instância existente, cliente ativo e controles de cobrança/risco/registro liberados.
• Para atualizar automaticamente IDs de uma conexão anterior, o vínculo antigo deve ter encerramento confirmado, capacidade liberada e nenhuma operação incerta em andamento.
• A nova autorização deve permitir que a HookCloud confirme diretamente na Meta o mesmo número completo, o vínculo com a WABA e o portfólio empresarial. Nome ou telefone enviados pelo navegador não são prova.
• O modo replace permanece como compatibilidade avançada da API: exige expected_connection_generation e replacement_target exatos. Não é necessário para a reconexão normal do mesmo número.

Autenticação e permissão

Partner API Key ativa com instances.write ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=create-connect-session

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "instance_key": "cliente-001-whatsapp-principal",
  "mode": "connect"
}

O que preencher em cada campo

Como ler a resposta

HTTP 201 com ok, instance_id, connect_session_id, connect_url e expires_at. Envie connect_url ao titular para concluir a autorização na Meta. Quando novos IDs são confirmados para o mesmo número, o backend preserva instance_id/instance_key, grava o histórico anterior e emite instance.identity_replaced com reason=automatic_same_phone_identity_replacement. O GET passa a trazer os novos IDs. No modo avançado replace, reason=explicit_meta_identity_replacement. Abrir ou gerar o link não confirma nenhuma troca; uma jornada incompleta não fabrica histórico.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 409 partner_webhook_verification_required: configure, valide e salve o webhook em Endpoints/update-partner-webhook-endpoint antes de tentar criar cliente, instância ou sessão. A validação avulsa não libera a operação. Consulte get-partner-onboarding-status.
• 400 missing_identifier.
• 404 instance_not_found.
• 429 meta_registration_rate_limited: aguarde a liberação indicada; gerar links repetidos não remove o bloqueio Meta.
• Bloqueios do cliente, de risco, cobrança ou capacidade podem impedir nova sessão.
• 423 meta_risk_customer_blocked: o cliente atingiu a política BAN/RED ou revisão manual; leia customer_risk. Vagas livres do parceiro não removem a trava. Não recadastre o cliente para contornar o histórico.
• 400 invalid_replacement_request: geração ausente/inválida ou IDs do destino inválidos.
• 409 replacement_requires_confirmed_disconnect: o vínculo anterior ainda não tem encerramento confirmado; desconecte e reconcilie antes de substituir.
• 409 stale_connection_generation ou replacement_authorization_stale: a identidade mudou; consulte a instância, sem reutilizar a autorização antiga.
• 409 replacement_identity_unchanged: o destino é a mesma identidade; utilize reconexão.
• 409 replacement_target_mismatch: a seleção Meta não corresponde à autorização. Não tente outro número silenciosamente.
• 409 instance_operation_in_progress: existe uma operação concorrente; aguarde e consulte seu resultado.
• 409 billing_sync_required: o período de cobrança ou trial confirmado expirou e precisa ser reconciliado. O proprietário deve abrir Assinatura no Portal e clicar em Atualizar para consultar a Stripe; se persistir, procurar o suporte. Não repita novas criações automaticamente. Isso não confirma recusa do cartão nem desconecta números já ativos.
• 400 invalid_ttl_hours: envie ttl_hours como número finito; se positivo, entre 1/60 de hora (1 minuto) e 168 horas (7 dias), nunca texto ou Infinity. Omissão, null ou valor não positivo usa o padrão configurado (fallback 24h). A rejeição ocorre antes de criar registros.
• 409 replacement_phone_mismatch: a Meta confirmou outro número. Use uma nova instância para outro número; a reconexão automática preserva a identidade do titular atual.
• 409 replacement_phone_unconfirmed ou replacement_business_unconfirmed: a nova autorização não forneceu prova suficiente do número ou portfólio. Confira as permissões e retome com uma nova sessão; não altere IDs manualmente para contornar a verificação.

Depois desta chamada

• Crie a sessão normal com instance_key e mode=reconnect e abra connect_url no navegador.
• Conclua a autorização do mesmo número na Meta. A HookCloud verifica novos IDs e aplica a atualização quando necessário.
• Reconcilie pelo get-partner-instance e atualize seu cache com os IDs retornados. Se houve troca de identidade, deduplique instance.identity_replaced por event_id e confira connection_generation.

Regras desta operação

• A geração de um link não valida o número nem conclui OAuth.
• Reconectar a mesma instância que já ocupa uma vaga não consome outra vaga. Uma instância desconectada que já liberou a capacidade só volta a ocupá-la se houver vaga disponível. A cobrança, o risco e a identidade continuam sendo verificados.
• Se a conclusão informar number_capacity_check_unavailable ou connection_update_in_progress, consulte o estado da instância e da sessão antes de tentar novamente. Esses erros não confirmam falta de vagas; não oriente a compra de outro pacote. Após etapas concluídas na Meta, não repita a autorização OAuth para tentar atualizar o resultado.
• Não compartilhe connect_url em logs públicos: ele contém uma capacidade temporária.
• URLs de retorno devem ser destinos controlados pela integração, sem dados sensíveis desnecessários na query.
• Reservas técnicas novas e seguras têm TTL de 15 minutos, com limpeza na próxima solicitação de reserva. GET e passagem do tempo não liberam a vaga por si só. Reservas legadas, números em uso, callback ativo/incerto, configuração parcial e operação remota processing/needs_review permanecem protegidos. Não é carência de cobrança.
• metadata não autoriza substituir nem escrever o histórico. A autorização é criada no servidor, vinculada ao parceiro, cliente, instância, sessão, geração anterior e destino exato. Erro ou timeout após uma escrita exige consultar o resultado antes de repetir.
• O estado autoritativo da configuração vem de get-partner-onboarding-status. URL presente ou token configurado, isoladamente, não confirmam GET validado. Atualizações de um cliente já existente não são tratadas como novo cadastro.
• A atualização automática não troca um número por outro, não retira números de outro cliente e não contorna BAN/RED, cobrança, capacidade ou desconexão remota incerta. O histórico permanece somente leitura.

Informa a confirmação da contratação, a conclusão do cadastro obrigatório do proprietário e a validação salva do webhook global. A resposta contém apenas estados de liberação, sem CPF, CNPJ, nome ou celular. Use os booleanos para orientar a ativação; a autorização final continua sendo conferida no servidor.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• Partner API Key com webhook.read ou login de membro owner/admin/developer do mesmo parceiro.

Autenticação e permissão

Partner API Key ativa com webhook.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-onboarding-status

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Esta operação não exige campos adicionais. A identidade do parceiro vem da autenticação.

Como ler a resposta

Retorna ok, partner_id, checkout_confirmed, registration_required, registration_complete, can_configure_webhook, webhook_required, webhook_validated, can_create_customer, can_create_instance e webhook. Use os booleanos explicitamente; em falha ou ausência de resposta, não considere a operação liberada. Contas existentes ou internas já habilitadas comercialmente não precisam de outro cartão, mas também devem preencher os dados obrigatórios.

Campos retornados que atualizam o painel

Erros e como agir

• 401/403: confira autenticação, escopo e vínculo com o parceiro.
• Falha na consulta não deve ser tratada como liberação; mantenha novos cadastros bloqueados e permita tentar a leitura novamente.

Depois desta chamada

• Se a contratação não estiver confirmada, abra Assinatura e aguarde a confirmação da Stripe.
• Se registration_complete=false, o proprietário deve entrar no Portal e concluir o cadastro: PF com nome completo, celular e CPF; PJ com razão social, CNPJ, nome completo do responsável e celular. Uma API key não pode substituir esse preenchimento.
• Se webhook_validated=false, abra Endpoints ou use update-partner-webhook-endpoint com o GET preparado e o token correto.
• Ative o POST na mesma URL e valide eventos reais no seu sistema; depois crie clientes e instâncias quando can_create_* permitir.

Regras desta operação

• Esta é uma consulta armazenada na HookCloud: não faz chamadas à Meta e não testa o webhook em cada leitura.
• Não use polling rápido. Releia ao abrir o painel, ao concluir uma etapa ou depois de uma alteração.
• Um token salvo ou teste GET avulso bem-sucedido não substitui a evidência de validação persistida para o endpoint atual.
• Não envie verify token, API key ou dados de cartão para o navegador do cliente final.

Define um callback próprio para uma única instância. O destino precisa passar pela verificação GET e ter o POST preparado. A configuração individual é preservada na conclusão e reconexão do Connect e nas migrações do webhook global; não troca a URL dos outros números nem do endpoint primário.

Referência oficial Meta: Webhooks da Cloud API · Números comerciais na Meta

Antes de começar

• Backend autenticado com Partner API Key e escopo exato webhook.write; membros do Portal precisam ser owner/admin. O acesso operacional e o cliente ativo são conferidos.
• A instância deve estar conectada/pausada, encerrada com vaga liberada ou ainda não autorizada sem phone_number_id; uma operação pendente ou estado incerto impede a mudança.
• Prepare HTTPS público com GET e POST, sem redirecionamento. O GET confere hub.mode=subscribe e hub.verify_token, e devolve somente hub.challenge em texto puro.
• Antes de aceitar POSTs, estabeleça com a HookCloud a autenticação disponível para sua integração. O callback recebe mensagens/status diretamente da Meta; esta rota não entrega o App Secret do app nem cria um relay público assinado com segredo do parceiro.

Autenticação e permissão

Partner API Key ativa com webhook.write ou *. Se optar por JWT, as funções permitidas são owner, admin.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=configure-partner-instance-webhook

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "instance_id": "UUID_DA_INSTANCIA",
  "webhook_url": "https://integracao.example.com/webhooks/whatsapp",
  "meta_verify_token": "TOKEN_DE_VERIFICACAO_FICTICIO"
}

O que preencher em cada campo

Como ler a resposta

HTTP 200 retorna {ok:true,instance_id,application_webhook:{scope:"instance",url,verified_at,configured_at,status,applied,applied_at}}; pode incluir unchanged:true quando a mesma configuração já estava válida. configured e applied:false significam destino preparado para uma conexão futura. active e applied:true confirmam aplicação à identidade atual. needs_review informa resultado remoto não confirmado. Não retorna partner_id na raiz, token de verificação ou segredo HMAC. Consulte get-partner-instance para conferir a identidade, connection_generation e application_webhook.

Campos retornados que atualizam o painel

Erros e como agir

• 400 invalid_instance_id ou invalid_meta_verify_token: confira UUID e token.
• 404 instance_not_found: a instância não pertence ao parceiro autorizado ou não existe.
• 409 instance_operation_in_progress, application_webhook_connection_uncertain ou stale_connection_generation: reconcilie a operação/identidade antes de tentar novamente.
• 409 application_webhook_remote_unconfirmed ou 503 application_webhook_configuration_failed: o resultado pode ser incerto; consulte a instância e a operação antes de repetir.
• 422 webhook_verification_failed: HTTPS ou desafio GET não confirmado. Erros específicos de URL também podem ser retornados.
• 403 webhook_management_forbidden: membro sem papel owner/admin; API Key requer webhook.write.

Depois desta chamada

• Leia get-partner-instance e confirme application_webhook.applied=true após a conclusão da conexão.
• Associe os eventos Meta por metadata.phone_number_id e, quando aplicável, entry.id/WABA; confira se pertencem à identidade atual.
• Persista os eventos com deduplicação antes de responder 2xx; não considere o GET bem-sucedido uma prova de entrega do POST.

Regras desta operação

• Não use esta rota para mudar o webhook global do parceiro. Para isso existe update-partner-webhook-endpoint.
• Idempotency-Key não é um contrato de repetição desta rota. A mesma configuração confirmada pode retornar unchanged:true; timeout, operação processing ou needs_review exige reconciliação, sem retry cego.
• As migrações globais ignoram instâncias que possuem configuração individual válida. Não existe nesta rota uma operação de remoção do override; não invente DELETE ou envie URL vazia para voltar ao global.
• O verify token é apenas do GET. X-Hub-Signature-256 é calculada pela Meta com o App Secret, que não é fornecido ao assinante. A presença desse cabeçalho não prova autenticidade para um receptor sem o verificador apropriado.
• Eventos normalizados HookCloud, como hookcloud.instance.health_updated e hookcloud.meta.template.updated, continuam seguindo as inscrições do endpoint global; configurar o callback individual não migra esses eventos para o novo receptor.

Consulta a configuração do endpoint primário do parceiro e o resumo da migração de callbacks. A resposta foi desenhada para leitura operacional e omite o token de verificação, o segredo de assinatura e cabeçalhos personalizados. Permite descobrir se falta configurar o destino antes de fornecer links de conexão aos clientes.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Credencial de leitura do endpoint do parceiro; não é preciso informar partner_id na operação normal.

Autenticação e permissão

Partner API Key ativa com webhook.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-webhook-endpoint

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Esta operação não exige campos adicionais. A identidade do parceiro vem da autenticação.

Como ler a resposta

Retorna ok, partner_id e endpoint. endpoint=null significa que não há endpoint disponível. Quando existe, inclui id, name, url, enabled, is_primary, migration_status, current_migration_id, previous_url, contagens total/concluída/falha/pendente, última migração/erro e meta_verify_token_configured. Guarde current_migration_id para consultar os itens detalhados.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 500 webhook_endpoint_lookup_failed: falha de leitura.
• Bloqueios de autenticação/scope não devem ser tratados como endpoint ausente.

Depois desta chamada

• Se endpoint=null, validar e cadastrar o endpoint.
• Se houver migração pendente/falha, consultar get-partner-webhook-migration antes de trocar a URL novamente.
• Para autorizar botões de novo cadastro, use get-partner-onboarding-status; não deduza autorização apenas da existência de URL ou meta_verify_token_configured.

Regras desta operação

• meta_verify_token_configured=true apenas confirma existência do segredo; não revela seu valor.
• Ter URL cadastrada não comprova que o sistema externo processa todos os tipos de eventos.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Executa um desafio HTTP GET contra a URL informada no padrão Meta: hub.mode=subscribe, hub.verify_token e hub.challenge=1234. O destino compara o token e devolve HTTP 200 com somente 1234 em texto puro. O servidor do assinante deve devolver qualquer hub.challenge válido recebido, não fixar sempre 1234. Essa rota não salva a configuração nem libera criação de clientes, instâncias ou novas sessões.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Endpoint público HTTPS que aceite GET de verificação.
• Implementar comparação de hub.verify_token com o segredo acordado e resposta textual do challenge.
• O destino precisa responder em até 10 segundos, com corpo limitado a 4096 bytes e sem redirect.

Autenticação e permissão

Partner API Key ativa com webhook.write ou *. Se optar por JWT, as funções permitidas são owner, admin.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=validate-partner-webhook-endpoint

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "webhook_url": "WEBHOOK_URL",
  "meta_verify_token": "WEBHOOK_VERIFY_TOKEN"
}

O que preencher em cada campo

Como ler a resposta

Retorna ok, partner_id, webhook_url normalizada, meta_verify_token e verification. verification contém ok, status_code, duration_ms e challenge_verified=true. Preserve o mesmo verify token para a etapa de atualização, principalmente se ele foi gerado automaticamente; sucesso aqui não persiste o endpoint. O diagnóstico identifica GET, challenge=1234, challenge_verified=true e post_delivery_verified=false: o GET não comprova que o POST esteja recebendo ou persistindo eventos.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 webhook_url_required: URL não informada.
• 400 meta_verify_token_required: foi fornecido token vazio.
• 422 webhook_endpoint_validation_failed: HTTPS/host inválido, timeout, redirect, status não bem-sucedido ou corpo diferente do challenge.

Depois desta chamada

• Corrigir o handshake no destino se necessário.
• Executar update-partner-webhook-endpoint com a mesma URL e o token confirmado.

Regras desta operação

• Um retorno JSON como {challenge:...} não corresponde ao texto puro esperado pelo verificador.
• Esta operação realiza um GET real no destino; não testa o consumo do POST de eventos.
• O valor meta_verify_token retornado é sensível.

Define o endpoint primário do parceiro e inicia a migração dos callbacks associados às instâncias já operacionais. Primeiro valida o handshake remoto; depois uma transação grava endpoint, migração, itens e fila juntos. A conclusão das chamadas Meta acontece por processamento de fila, portanto uma resposta aceita não significa que todos os números já trocaram de destino. Também persiste a evidência da validação GET da URL salva; isso é obrigatório antes de novos clientes, instâncias e sessões. A mesma URL pode ser revalidada sem obrigar a criação de outro endpoint.

Referência oficial Meta: Números, registro e permissões · Webhooks da Cloud API

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• A HookCloud envia hub.mode=subscribe, hub.verify_token e hub.challenge=1234; seu servidor deve conferir o token e responder HTTP 200 com somente 1234 em texto puro. Testar sem salvar não libera cadastros. Ative também o POST na mesma URL para receber eventos.
• Handshake HTTPS previamente implementado no destino.
• Não pode existir migração pending, processing, partial ou failed sem conclusão/retry.
• Avaliar as instâncias que já estão conectadas; elas podem precisar de reconfiguração remota.

Autenticação e permissão

Partner API Key ativa com webhook.write ou *. Se optar por JWT, as funções permitidas são owner, admin.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=update-partner-webhook-endpoint

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "webhook_url": "WEBHOOK_URL",
  "meta_verify_token": "WEBHOOK_VERIFY_TOKEN",
  "reason": "Teste de atualização do endpoint",
  "batch_size": 3
}

O que preencher em cada campo

Como ler a resposta

Retorna ok, changed, partner_id, endpoint_id, webhook_url, migration_id e meta_verify_token. Quando há alteração, inclui migration_status, total_instances e queue (id/status ou null). HTTP 202 com migration_status=pending indica trabalho remoto em andamento; HTTP 200 ocorre quando não há itens para migrar ou a URL/token já estavam iguais. changed=false pode vir com reason=webhook_url_unchanged. Reaproveite migration_id para acompanhamento.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 reason_required/invalid_batch_size/invalid_meta_verify_token: parâmetros fora do contrato.
• 400 webhook_verification_failed: a URL não passou no handshake HTTPS.
• 409 webhook_migration_in_progress: concluir ou repetir a migração existente antes de outra troca.
• 500 partner_webhook_endpoint_update_failed: não foi possível concluir o compromisso da configuração.

Depois desta chamada

• Consulte get-partner-onboarding-status e confira webhook_validated e can_create_customer/can_create_instance. GET válido não prova o recebimento de POST; mantenha o receptor POST ativo.
• Consultar get-partner-webhook-migration até a situação final.
• Se houver partial/failed, corrigir a causa e usar retry-partner-webhook-migration.
• Confirmar endpoint e contagens antes de desligar o destino anterior.

Regras desta operação

• Não enviar várias mudanças de URL em paralelo.
• Não interpretar HTTP 202 como migração concluída.
• O token retornado deve corresponder ao segredo aceito pelo endpoint; não confundir com a chave da API do Partner.
• Instâncias com application_webhook válido preservam seu destino individual durante a migração global. A troca do endpoint primário não remove esses overrides.
• Esta resposta fornece meta_verify_token, mas não webhook_secret. O segredo HMAC dos eventos HookCloud precisa estar provisionado separadamente; o GET do endpoint também não o revela. Não aceite eventos não autenticados enquanto essa etapa estiver pendente e não use o verify token no lugar do segredo.

Mostra o registro de uma migração e os itens de reconfiguração por instância, permitindo distinguir pendência de fila de uma falha concreta na Meta. Apesar de ser uma consulta, a rota utiliza a permissão de gestão webhook.write e a role de gestão de endpoint, porque devolve o contexto completo da migração.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Ter migration_id retornado pela atualização, ou aceitar consultar a migração mais recente do parceiro.

Autenticação e permissão

Partner API Key ativa com webhook.write ou *. Se optar por JWT, as funções permitidas são owner, admin.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-webhook-migration

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

Retorna ok, partner_id, migration e items. Sem migração, migration=null e items=[]. migration contém o registro completo, incluindo status, URLs, motivo, contagens, datas e token de verificação. items inclui id, partner_instance_id, meta_phone_number_id, URLs antiga/nova, status, attempt_count, max_attempts, next_retry_at, last_error e datas. A consulta limita os itens a 1000 e não oferece paginação neste contrato.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 invalid_migration_id: ID não é UUID.
• 500 partner_webhook_migration_lookup_failed: falha de leitura.
• Ausência de registro é retornada como migration=null; não é confirmação de que um ID arbitrário existiu.

Depois desta chamada

• Ler items[].last_error para resolver a causa das falhas.
• Usar retry apenas em migração partial/failed.
• Consultar a instância individual se o resumo da migração e o estado do callback exigirem diagnóstico adicional.

Regras desta operação

• A resposta contém dados sensíveis, incluindo meta_verify_token no registro da migração.
• Não exponha esse resultado em tela pública.
• Para parceiros com mais de 1000 itens na migração, esta rota não fornece sozinha a relação completa paginada.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Reabre os itens com falha de uma migração partial/failed, zera suas tentativas e agenda novo processamento. A ação usa a mesma intenção de destino registrada na migração; ela não é uma segunda troca independente de URL.

Referência oficial Meta: Números, registro e permissões · Webhooks da Cloud API

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Migração existente do próprio parceiro com status partial ou failed.
• Examinar last_error antes de repetir.
• Ter itens failed ou pending para processar.

Autenticação e permissão

Partner API Key ativa com webhook.write ou *. Se optar por JWT, as funções permitidas são owner, admin.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=retry-partner-webhook-migration

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "migration_id": "MIGRATION_ID",
  "batch_size": 3
}

O que preencher em cada campo

Como ler a resposta

HTTP 202 com ok, migration_id, reset_items e queue. reset_items é o número de itens failed redefinidos, não a quantidade já corrigida na Meta. queue contém id e status da tarefa agendada ou reaproveitada. Acompanhe a mesma migração até a situação final.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 invalid_migration_id.
• 404 webhook_migration_not_found.
• 409 webhook_migration_not_retryable: status não é partial/failed.
• 409 webhook_migration_no_failed_items: não há itens failed ou pending.
• 500 partner_webhook_migration_retry_failed: falha ao preparar o reprocessamento.

Depois desta chamada

• Consultar get-partner-webhook-migration e avaliar a evolução das contagens.
• Se a mesma causa reaparecer, tratar credencial/endpoint/número antes de nova repetição.

Regras desta operação

• Não use retry contínuo como substituto de corrigir um erro de autorização ou handshake.
• Uma resposta 202 apenas agenda; não libera automaticamente a possibilidade de trocar a URL novamente.

Consultar o catálogo de templates já conhecido pela HookCloud, com filtros e paginação, para alimentar seletores no sistema do assinante ou preparar um sistema de envio.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Ter uma WABA vinculada a uma instância ou credencial do parceiro para que existam dados de catálogo.
• Conhecer a WABA/instância do cliente quando a integração administrar mais de uma conta. Sem seletor, a listagem pode abranger todas as WABAs do parceiro.

Autenticação e permissão

Partner API Key ativa com meta_risk.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=list-partner-meta-templates&page=1&page_size=20

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

Retorna ok, partner_id, meta_waba_id, source="hookcloud_cache", sync e a paginação items, total, page, page_size e pages. meta_waba_id e sync podem ser nulos quando a consulta não escolhe uma única WABA. total refere-se ao conjunto filtrado, não à página atual. Registros marcados como missing_from_graph são excluídos desta listagem. Os registros de template incluem id (UUID local), meta_waba_id, template_id (ID Meta), template_name, template_language, template_status, quality_status, category, rejection_reason, is_risky, sendable, components, parameter_schema, sync_status, last_graph_sync_at, last_graph_error, last_event_at, missing_from_graph, graph_version e datas de criação/atualização. components contém os componentes reais sincronizados; parameter_schema resume os parâmetros identificados. Campos ainda não sincronizados podem estar vazios ou nulos. Leia sendable junto com o estado e a data de sincronização; ele não garante a aprovação de uma futura chamada de envio pela Meta.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 multiple_instance_identifiers: foi enviado mais de um entre instance_id, instance_key e phone_number_id; mantenha apenas um.
• 400 invalid_instance_id ou waba_instance_mismatch: revise o UUID ou a associação entre a instância e a WABA.
• 404 instance_not_found ou waba_not_found: o recurso não foi encontrado dentro do parceiro autenticado; confira ambiente e cadastro.
• 400 invalid_pagination: página ou tamanho fora dos limites; ajuste os parâmetros do cliente HTTP.
• 500 meta_template_list_failed: a consulta ao catálogo falhou; preserve o último catálogo válido e tente novamente com intervalo.

Depois desta chamada

• No da integração, processe items com Split Out/Loop Over Items e incremente page até alcançar pages ou items ficar vazio.
• Guarde template_id, template_name, template_language e meta_waba_id juntos. Um mesmo nome pode existir em WABAs ou idiomas diferentes.
• Para enviar, use o fluxo Graph correspondente; selecione components/parameter_schema do registro encontrado e confira os parâmetros exigidos.

Regras desta operação

• Guarde WABA ID e phone_number_id como texto no seu sistema. A conversão para Number pode perder precisão em identificadores longos.
• Com mais de uma WABA, informe o seletor explicitamente. Nunca escolha a primeira WABA de uma lista sem associá-la ao cliente correto.
• O catálogo desta API é uma cópia sincronizada pela HookCloud. Criar, editar, apagar ou enviar um template usa a Graph API autorizada; estas rotas não encaminham essas operações para a Meta.
• Não trate um array vazio como falha de transporte: pode ser resultado legítimo dos filtros ou de uma sincronização ainda não concluída.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Ler um template específico do catálogo, incluindo seus componentes e informações de sincronização, sem percorrer todas as páginas.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Ter template_id da Meta ou o par exato template_name + language.
• Na consulta por nome, identificar a WABA; o sistema só a deduz quando há exatamente uma WABA disponível.

Autenticação e permissão

Partner API Key ativa com meta_risk.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-meta-template&template_name=hello_world&language=en_US&instance_key=cliente-001-whatsapp-principal

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

Retorna ok, partner_id, meta_waba_id e template, um único registro. A ausência do template gera 404, não template vazio com ok=true. Os registros de template incluem id (UUID local), meta_waba_id, template_id (ID Meta), template_name, template_language, template_status, quality_status, category, rejection_reason, is_risky, sendable, components, parameter_schema, sync_status, last_graph_sync_at, last_graph_error, last_event_at, missing_from_graph, graph_version e datas de criação/atualização. components contém os componentes reais sincronizados; parameter_schema resume os parâmetros identificados. Campos ainda não sincronizados podem estar vazios ou nulos. Leia sendable junto com o estado e a data de sincronização; ele não garante a aprovação de uma futura chamada de envio pela Meta.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 multiple_instance_identifiers: foi enviado mais de um entre instance_id, instance_key e phone_number_id; mantenha apenas um.
• 400 invalid_instance_id ou waba_instance_mismatch: revise o UUID ou a associação entre a instância e a WABA.
• 404 instance_not_found ou waba_not_found: o recurso não foi encontrado dentro do parceiro autenticado; confira ambiente e cadastro.
• 400 template_identifier_required: faltou escolher uma forma de identificação.
• 400 multiple_template_identifiers: template_id e template_name foram enviados juntos.
• 400 template_language_required: a busca por nome não informou o idioma.
• 400 waba_id_required ou 409 waba_missing: não foi possível determinar uma única WABA para a busca por nome.
• 404 meta_template_not_found: registro não encontrado no catálogo do parceiro/WABA.
• 500 meta_template_lookup_failed: falha ao consultar o catálogo.

Depois desta chamada

• Use o registro retornado para mostrar status, idioma e parâmetros no sistema do cliente.
• Se o template acabou de ser criado na Meta, solicite refresh-partner-meta-templates, acompanhe o job e repita a consulta.

Regras desta operação

• Guarde WABA ID e phone_number_id como texto no seu sistema. A conversão para Number pode perder precisão em identificadores longos.
• Com mais de uma WABA, informe o seletor explicitamente. Nunca escolha a primeira WABA de uma lista sem associá-la ao cliente correto.
• O catálogo desta API é uma cópia sincronizada pela HookCloud. Criar, editar, apagar ou enviar um template usa a Graph API autorizada; estas rotas não encaminham essas operações para a Meta.
• Não use o UUID local id no lugar de template_id. Mantenha nomes claros nas variáveis do seu sistema, por exemplo template_meta_id e template_local_id.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Pedir uma nova sincronização do catálogo de uma WABA com a Graph API por meio da fila interna da HookCloud.

Referência oficial Meta: Números, registro e permissões · Webhooks da Cloud API

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Ter uma WABA pertencente ao parceiro e credenciais Meta válidas para ela.
• Quando houver várias WABAs, enviar um seletor explícito.
• Respeitar o intervalo de atualização manual informado pelo servidor.

Autenticação e permissão

Partner API Key ativa com instances.write ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=refresh-partner-meta-templates

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "instance_key": "cliente-001-whatsapp-principal"
}

O que preencher em cada campo

Como ler a resposta

HTTP 202 com ok=true, accepted=true, partner_id, meta_waba_id, sync_job_id, sync_status, next_allowed_at e poll. sync_job_id identifica o trabalho pendente/em processamento, que pode ter sido reutilizado em vez de duplicado. poll fornece a consulta para acompanhar a sincronização. next_allowed_at é a próxima oportunidade de solicitar atualização manual; não é uma promessa de horário de término.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 multiple_instance_identifiers: foi enviado mais de um entre instance_id, instance_key e phone_number_id; mantenha apenas um.
• 400 invalid_instance_id ou waba_instance_mismatch: revise o UUID ou a associação entre a instância e a WABA.
• 404 instance_not_found ou waba_not_found: o recurso não foi encontrado dentro do parceiro autenticado; confira ambiente e cadastro.
• 400 waba_id_required ou 409 waba_missing: informe a WABA/instância correta ou conclua a conexão.
• 403 force_refresh_admin_only: remova force=true da automação do assinante.
• 429 meta_template_refresh_rate_limited: respeite o header Retry-After e error.details.retry_after_seconds/next_allowed_at; cached_data_available indica que o catálogo anterior pode continuar sendo consultado.
• 500 meta_template_refresh_failed: falha ao solicitar atualização; não interprete como exclusão dos templates existentes.

Depois desta chamada

• No backend da integração, guarde sync_job_id e meta_waba_id, aguarde o intervalo informado e chame get-partner-meta-template-sync.
• Quando o job concluir com sucesso, chame list-partner-meta-templates ou get-partner-meta-template.
• Se o job falhar, registre last_error e mantenha a cópia anterior até corrigir credencial/permissão e pedir nova atualização dentro do intervalo permitido.

Regras desta operação

• Guarde WABA ID e phone_number_id como texto no seu sistema. A conversão para Number pode perder precisão em identificadores longos.
• Com mais de uma WABA, informe o seletor explicitamente. Nunca escolha a primeira WABA de uma lista sem associá-la ao cliente correto.
• O catálogo desta API é uma cópia sincronizada pela HookCloud. Criar, editar, apagar ou enviar um template usa a Graph API autorizada; estas rotas não encaminham essas operações para a Meta.
• Não faça polling disparando refresh repetidamente. Separe a ação de solicitar a atualização da consulta de status.
• O intervalo manual é configurável no servidor; o padrão usado pelo handler é 300 segundos, mas a resposta do ambiente é a referência para o sistema.
• Um evento novo ou force=true do Admin não reduz uma espera já registrada. A primeira solicitação pode iniciar o trabalho imediatamente; solicitações repetidas e limites Meta respeitam next_allowed_at e Retry-After. O guard de consumo pode adiar a leitura antes de consultar a Meta, mantendo o catálogo anterior.

Consultar o estado de sincronização de uma WABA e o trabalho mais recente de atualização do catálogo.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Escolher a mesma WABA usada no pedido de refresh.
• Ter uma única WABA disponível ou informar o seletor explicitamente.

Autenticação e permissão

Partner API Key ativa com meta_risk.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-meta-template-sync&instance_key=cliente-001-whatsapp-principal

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

Retorna ok, partner_id, meta_waba_id, sync e latest_job. sync é o registro do estado da WABA e latest_job é a linha mais recente da fila; ambos podem ser nulos se ainda não houver histórico. latest_job inclui id, status, reason, attempt_count, max_attempts, run_after, last_error e datas disponíveis no registro. Use status para distinguir um trabalho pendente/em processamento de um concluído ou com falha, e last_error para diagnóstico. Essa resposta não traz o array de templates.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 multiple_instance_identifiers: foi enviado mais de um entre instance_id, instance_key e phone_number_id; mantenha apenas um.
• 400 invalid_instance_id ou waba_instance_mismatch: revise o UUID ou a associação entre a instância e a WABA.
• 404 instance_not_found ou waba_not_found: o recurso não foi encontrado dentro do parceiro autenticado; confira ambiente e cadastro.
• 400 waba_id_required ou 409 waba_missing: faltou uma WABA unívoca.
• 500 meta_template_sync_lookup_failed: a consulta ao estado de sincronização falhou.

Depois desta chamada

• Implemente polling com intervalo e limite de tentativas, usando Wait entre consultas.
• Após sucesso, leia o catálogo; em falha persistente, encaminhe o diagnóstico ao suporte com WABA e sync_job_id, sem tokens Meta.

Regras desta operação

• Guarde WABA ID e phone_number_id como texto no seu sistema. A conversão para Number pode perder precisão em identificadores longos.
• Com mais de uma WABA, informe o seletor explicitamente. Nunca escolha a primeira WABA de uma lista sem associá-la ao cliente correto.
• O catálogo desta API é uma cópia sincronizada pela HookCloud. Criar, editar, apagar ou enviar um template usa a Graph API autorizada; estas rotas não encaminham essas operações para a Meta.
• latest_job é o trabalho mais recente da WABA, não necessariamente o único iniciado pelo seu sistema. Compare o id quando precisar acompanhar um pedido específico.
• Não substitua um catálogo existente por vazio apenas porque sync/latest_job veio nulo.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Obter um resumo operacional de templates e uma pequena lista de registros recentes do parceiro.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Ter dados de templates já recebidos/sincronizados no parceiro. Nenhum campo de filtro é necessário nesta rota.

Autenticação e permissão

Partner API Key ativa com meta_risk.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=get-meta-template-dashboard

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Esta operação não exige campos adicionais. A identidade do parceiro vem da autenticação.

Como ler a resposta

Retorna ok, partner_id, summary e latest_templates. summary contém total_templates, approved_templates, pending_templates, rejected_templates, risky_templates, low_quality_templates, sendable_templates, graph_synced_templates, stale_templates, wabas_count e languages_count. approved_templates conta APPROVED/REINSTATED; pending_templates agrega PENDING/IN_APPEAL/PENDING_DELETION; low_quality_templates considera RED/LOW/FLAGGED. stale_templates indica registros marcados como ausentes na Graph. latest_templates usa o formato items,total,page,page_size,pages e traz a primeira página de 10 registros recentes. O resumo é do parceiro, sem seletor por WABA nesta rota.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 500 meta_template_dashboard_failed: um dos componentes do painel não pôde ser carregado. Mantenha o estado anterior da interface e sinalize a falha da atualização.

Depois desta chamada

• Use summary para os indicadores e latest_templates.items para a tabela de destaque.
• Abra search-meta-templates com filtros apropriados para investigar um indicador; use list/get para selecionar um template para envio.

Regras desta operação

• total_templates conta registros não marcados como ausentes na Graph, incluindo templates ainda não enviáveis. Não exija que ele seja idêntico ao número de resultados de sendable_only=true.
• Esta chamada não solicita nova sincronização com a Meta.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Pesquisar o catálogo operacional de templates usando status, qualidade, risco e intervalo de tempo.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Ter os códigos de status/categoria/idioma usados pelos registros do catálogo. Não é necessário fornecer todos os filtros.

Autenticação e permissão

Partner API Key ativa com meta_risk.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=search-meta-templates&page=1&page_size=20

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

Retorna ok, partner_id, items, total, page, page_size e pages. Os itens incluem os campos do estado de template e as informações de parceiro adicionadas pela consulta (partner_name e partner_slug), além de effective_event_at. O período/ordenação considera effective_event_at, calculado priorizando last_graph_sync_at, depois last_event_at e updated_at. Registros missing_from_graph=true são excluídos desta busca. Os registros de template incluem id (UUID local), meta_waba_id, template_id (ID Meta), template_name, template_language, template_status, quality_status, category, rejection_reason, is_risky, sendable, components, parameter_schema, sync_status, last_graph_sync_at, last_graph_error, last_event_at, missing_from_graph, graph_version e datas de criação/atualização. components contém os componentes reais sincronizados; parameter_schema resume os parâmetros identificados. Campos ainda não sincronizados podem estar vazios ou nulos. Leia sendable junto com o estado e a data de sincronização; ele não garante a aprovação de uma futura chamada de envio pela Meta.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 500 meta_template_search_failed: falha na pesquisa, inclusive quando parâmetros não podem ser convertidos pelo banco. Envie datas ISO válidas e paginação dentro dos limites em vez de depender de coerções do servidor.

Depois desta chamada

• Use paginação até alcançar pages, mantendo os mesmos filtros em todas as páginas.
• Para investigar um registro, consulte get-partner-meta-template pelo template_id e pela WABA.

Regras desta operação

• O intervalo de data representa a atualização efetiva do catálogo, não o horário em que uma mensagem foi enviada ao destinatário.
• is_risky=false e sendable_only=false são filtros ativos; remova os campos quando quiser incluir todos os estados.
• No da integração, envie booleanos reais em JSON e as strings true/false nos parâmetros de consulta, sem expressões que produzam texto vazio.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Registrar um estado de entrega observado pelo sistema do assinante e atualizar os indicadores internos de saúde da HookCloud.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Ter instância cadastrada no Partner e relacioná-la ao metadata.phone_number_id recebido da Meta.
• Extrair cada status individual do envelope entry[].changes[].value.statuses[]; o endpoint não processa o envelope completo automaticamente.
• Conservar o ID e o instante real do evento para deduplicação.

Autenticação e permissão

Partner API Key ativa com instances.write ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=report-partner-message-status

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "instance_key": "cliente-001-whatsapp-principal",
  "message_id": "MESSAGE_ID",
  "status": "delivered",
  "recipient_user_id": "BR.BSUID_RECEBIDO_NO_WEBHOOK",
  "occurred_at": "OCCURRED_AT"
}

O que preencher em cada campo

Como ler a resposta

HTTP 201 com ok=true, report, classification, message_id, message_id_source e privacy. report contém ok, duplicate, event_id, state_id e message_id; quando o evento não é uma repetição também retorna current_status, bucket_start e state_advanced na versão atual. duplicate=true significa que o evento já foi registrado, não que deva ser reenviado ao WhatsApp. state_advanced=false indica que o evento foi guardado no histórico sem fazer o estado atual retroceder. classification é nulo para estados não falhos; para falha contém code, type, category, severity, retry_advice, is_retryable e retry_after. privacy informa recipient_stored_as_hash e raw_recipient_stored=false. message_id_source distingue meta_wamid, partner_client_message_id e partner_request_id. Mesmo uma repetição aceita responde 201; decida pelo conteúdo de report, não apenas pelo código HTTP.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 multiple_instance_identifiers/instance_identifier_required ou invalid_instance_id: forneça exatamente um identificador de instância válido.
• 404 instance_not_found: a instância informada não existe no parceiro autenticado.
• 400 message_id_required: faltou uma referência estável da mensagem/requisição.
• 400 invalid_occurred_at: envie data/hora ISO com fuso ou timestamp Unix em segundos válido.
• 400 invalid_recipient_hash, invalid_recipient_user_id, invalid_recipient ou conflicting_recipient_identifiers: revise o formato e a consistência da identidade; não use username como BSUID.
• 403 delivery_report_forbidden: o membro não tem permissão para registrar a operação.
• 500 delivery_status_report_failed: falha ao persistir o relato. Repita o mesmo evento com o mesmo identificador/idempotência, sem disparar outro envio de mensagem por causa deste erro.
• 400 invalid_delivery_status: use um dos seis estados suportados.

Depois desta chamada

• Mapeie o retorno de report em um log técnico mínimo com event_id, message_id e duplicate.
• Em failed, avalie classification.retry_advice, is_retryable e retry_after antes de qualquer política de reenvio; o relatório não faz o reenvio por você.
• Consulte get-partner-delivery-health e search-partner-delivery-events para confirmar os indicadores e o histórico.

Regras desta operação

• Estas rotas registram observabilidade; não enviam mensagens, não chamam o destinatário e não reproduzem o webhook da Meta para o sistema do cliente.
• O destinatário bruto e status_payload bruto não são armazenados. Ainda assim, revise error_details: é um objeto persistido e não deve conter tokens nem conteúdo pessoal desnecessário.
• Use Idempotency-Key estável no header para repetir o mesmo evento com segurança. Na ausência dele, o servidor deriva uma chave da instância, mensagem, status, erro e instante. Um novo status da mesma mensagem é outro evento e precisa de uma identidade de evento distinta.
• Não use o mesmo Idempotency-Key para sent e delivered. Conserve o timestamp original ao repetir o mesmo status; alterar o horário pode transformar a repetição em outro evento.
• O estado consolidado respeita progressão e eventos fora de ordem. Um failed antigo não deve rebaixar uma mensagem já delivered/read. O histórico pode conter ambos, e não representa duas mensagens enviadas.
• O relatório de saúde representa o que o assinante reportou. Se a Meta entrega os webhooks diretamente ao endpoint do cliente, a HookCloud não passa a conhecer esses status sem este fluxo de reporte.
• Um BSUID é opaco e tem contexto de negócio. Não remova o prefixo BR., não tente derivar o telefone e não trate username reservado como destinatário endereçável.

Registrar uma falha real de envio/entrega e acionar sua classificação no acompanhamento da HookCloud.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Ter a instância associada ao envio e o erro real da Meta.
• Separar falha de entrega de falha do próprio sistema. Um timeout do seu sistema sem confirmação da Meta não prova, sozinho, que a mensagem não foi aceita.
• Configurar o ramo de erro para relatar a falha sem entrar num loop de reenvios.

Autenticação e permissão

Partner API Key ativa com instances.write ou *. Se optar por JWT, as funções permitidas são owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=report-partner-message-delivery-failure

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "instance_key": "cliente-001-whatsapp-principal",
  "message_id": "MESSAGE_ID",
  "error_code": "131047",
  "error_message": "Falha informada pelo integrador"
}

O que preencher em cada campo

Como ler a resposta

HTTP 201 com ok=true, report, classification, message_id, message_id_source e privacy. report contém ok, duplicate, event_id, state_id e message_id; quando o evento não é uma repetição também retorna current_status, bucket_start e state_advanced na versão atual. duplicate=true significa que o evento já foi registrado, não que deva ser reenviado ao WhatsApp. state_advanced=false indica que o evento foi guardado no histórico sem fazer o estado atual retroceder. classification é nulo para estados não falhos; para falha contém code, type, category, severity, retry_advice, is_retryable e retry_after. privacy informa recipient_stored_as_hash e raw_recipient_stored=false. message_id_source distingue meta_wamid, partner_client_message_id e partner_request_id. Mesmo uma repetição aceita responde 201; decida pelo conteúdo de report, não apenas pelo código HTTP. Esta rota força o status failed no servidor; não depende de um campo status no body.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 multiple_instance_identifiers/instance_identifier_required ou invalid_instance_id: forneça exatamente um identificador de instância válido.
• 404 instance_not_found: a instância informada não existe no parceiro autenticado.
• 400 message_id_required: faltou uma referência estável da mensagem/requisição.
• 400 invalid_occurred_at: envie data/hora ISO com fuso ou timestamp Unix em segundos válido.
• 400 invalid_recipient_hash, invalid_recipient_user_id, invalid_recipient ou conflicting_recipient_identifiers: revise o formato e a consistência da identidade; não use username como BSUID.
• 403 delivery_report_forbidden: o membro não tem permissão para registrar a operação.
• 500 delivery_status_report_failed: falha ao persistir o relato. Repita o mesmo evento com o mesmo identificador/idempotência, sem disparar outro envio de mensagem por causa deste erro.

Depois desta chamada

• Guarde a classificação e apresente a orientação adequada ao operador.
• Se is_retryable=false, corrija a causa antes de tentar enviar novamente. Se houver retry_after, respeite-o.
• Use a consulta de saúde para investigar recorrência por instância, template e campanha.

Regras desta operação

• Estas rotas registram observabilidade; não enviam mensagens, não chamam o destinatário e não reproduzem o webhook da Meta para o sistema do cliente.
• O destinatário bruto e status_payload bruto não são armazenados. Ainda assim, revise error_details: é um objeto persistido e não deve conter tokens nem conteúdo pessoal desnecessário.
• Use Idempotency-Key estável no header para repetir o mesmo evento com segurança. Na ausência dele, o servidor deriva uma chave da instância, mensagem, status, erro e instante. Um novo status da mesma mensagem é outro evento e precisa de uma identidade de evento distinta.
• Não use o mesmo Idempotency-Key para sent e delivered. Conserve o timestamp original ao repetir o mesmo status; alterar o horário pode transformar a repetição em outro evento.
• O estado consolidado respeita progressão e eventos fora de ordem. Um failed antigo não deve rebaixar uma mensagem já delivered/read. O histórico pode conter ambos, e não representa duas mensagens enviadas.
• O relatório de saúde representa o que o assinante reportou. Se a Meta entrega os webhooks diretamente ao endpoint do cliente, a HookCloud não passa a conhecer esses status sem este fluxo de reporte.
• Um BSUID é opaco e tem contexto de negócio. Não remova o prefixo BR., não tente derivar o telefone e não trate username reservado como destinatário endereçável.
• Não envie erros simulados para a operação real: eles alimentam alertas, histórico e indicadores.
• Relatar a falha não debita nem estorna cobrança do pacote e não desconecta o número.

Consultar contagens e taxas de entrega/falha dos relatos recebidos pela HookCloud em uma janela de tempo.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Ter relatórios enviados pelas rotas report-partner-message-status/failure. A ausência de relatórios pode produzir totais zero mesmo que o sistema externo esteja enviando mensagens.
• Escolher uma janela temporal adequada ao volume monitorado.

Autenticação e permissão

Partner API Key ativa com meta_risk.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-delivery-health&window_hours=24

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

Retorna ok, partner_id, summary e alerts. summary inclui window_hours, from, total_messages, accepted, sent, delivered, read, failed, deleted, error_131049, error_131042, error_131026, error_other, failure_rate, open_alerts, critical_alerts, top_errors e top_templates. failure_rate é uma fração entre 0 e 1; multiplique por 100 somente para exibir percentagem. top_errors agrupa códigos/títulos e contagens; top_templates inclui template_name, failed_count e total_count. Os contadores são calculados a partir dos estados consolidados, não da quantidade bruta de eventos sent/delivered/read. alerts é uma página com items,total,page,page_size,pages, limitada a 20 itens na chamada padrão. Atenção: os filtros customer_id/instance_id são passados ao resumo, mas a consulta de alerts nesta implementação é do parceiro inteiro; não atribua automaticamente todos esses alertas ao cliente filtrado. alerts contém items,total,page,page_size,pages e respeita o filtro de cliente/instância. Use alert_page/alert_page_size para navegar e alert_search/alert_status para pesquisar os incidentes; a janela de mensagens não é um corte temporal dos alertas.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 invalid_window_hours: use um inteiro entre 1 e 2160.
• 400 invalid_customer_id/invalid_partner_customer_id/invalid_instance_id/invalid_partner_instance_id: um filtro não é UUID.
• 400 conflicting_identifiers: aliases do mesmo recurso contêm UUIDs diferentes.
• 500 delivery_health_failed: a agregação ou a busca de alertas falhou.

Depois desta chamada

• Mostre a janela junto aos indicadores e identifique quando a atualização falhar.
• Use search-partner-delivery-events para abrir os eventos de uma instância/campanha antes de tirar conclusões sobre a causa.
• Para triagem humana, reconheça um alerta pela rota acknowledge; para registrar a correção efetiva, use resolve com uma nota.

Regras desta operação

• Taxa de falha baixa não comprova ausência de problemas quando parte dos status não está sendo reportada.
• Não some sent + delivered + read como mensagens diferentes: o estado consolidado de cada mensagem avança.
• A lista alerts não herda os filtros de cliente e instância do resumo; filtre a apresentação pelos IDs dos alertas se precisar de um painel estritamente individual.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Pesquisar o histórico dos eventos de entrega relatados, com filtros por mensagem, erro, template, campanha, cliente e instância.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Ter eventos previamente reportados.
• Distinguir eventos individuais do estado consolidado: uma mesma mensagem pode ter vários eventos válidos.

Autenticação e permissão

Partner API Key ativa com meta_risk.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=search-partner-delivery-events&page=1&page_size=20

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

Retorna ok, partner_id, items,total,page,page_size,pages. Cada item corresponde a uma linha de evento, com os identificadores, delivery_status, occurred_at, message_id, campos de erro/classificação, referência de template/campanha e metadados sanitizados gravados pelo relatório. A consulta acrescenta customer_name, external_customer_id, instance_key, instance_name e partner_name. Não espere o destinatário bruto ou o texto completo da mensagem: esses dados não fazem parte do relatório de saúde. Para decidir o estado final de uma mensagem, não basta contar eventos ou escolher um evento antigo isolado.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 invalid_pagination: page/page_size fora dos limites.
• 400 invalid_date_from/invalid_date_to: data inválida ou sem fuso quando exigido; prefira ISO completo.
• 400 invalid_date_range: date_from posterior a date_to.
• 400 conflicting_identifiers ou invalid_<campo>: revise aliases e UUIDs dos filtros.
• 500 delivery_event_search_failed: falha ao pesquisar o histórico.

Depois desta chamada

• No da integração, percorra pages mantendo os filtros constantes e guarde o ponto de retomada se a exportação for longa.
• Agrupe por message_id e instância para investigar a sequência de status.
• Inclua IDs técnicos e código de erro no chamado de suporte; evite exportar informações que não sejam necessárias à investigação.

Regras desta operação

• O total desta rota conta eventos, não mensagens únicas; não o use diretamente como denominador da taxa de entrega.
• Um filtro até YYYY-MM-DD termina à meia-noite. Use data/hora explícita para incluir o restante do dia.
• O Partner armazena metadados de diagnóstico; o conteúdo da mensagem e o processamento externo do cliente permanecem sob responsabilidade do sistema dele.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Marcar um alerta de saúde de entrega como reconhecido por um operador responsável.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal antes de acessar os recursos operacionais. O perfil do membro e suas permissões continuam sendo conferidos.
• Obter alert_id de um alerta do parceiro.
• Usar a sessão de membro autorizado para a triagem. Uma chave de API de integração não substitui o papel humano exigido nesta operação.

Autenticação e permissão

Exige access_token obtido no login de membro. A Partner API Key não é aceita nesta operação. Funções permitidas: owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=acknowledge-partner-delivery-alert

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer ACCESS_TOKEN_DO_MEMBRO",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "alert_id": "ALERT_ID",
  "notes": "Alerta em análise"
}

O que preencher em cada campo

Como ler a resposta

Retorna ok=true e alert com a linha atualizada. O status passa para acknowledged, com acknowledged_at, acknowledged_by e a nota de reconhecimento em metadata.acknowledgement_notes. O alerta continua sendo um problema acompanhado; não é encerrado por este reconhecimento.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal. Não faça retry automático.
• 400 invalid_alert_id: o identificador não é UUID.
• 404 delivery_alert_not_found: alerta inexistente.
• 403 delivery_alert_access_denied ou delivery_alert_acknowledge_forbidden: recurso de outro parceiro ou sessão sem permissão.
• 500 delivery_alert_acknowledge_failed: atualização não concluída.

Depois desta chamada

• Atualize a interface usando o alert retornado.
• Investigue os eventos relacionados; depois da correção efetiva, use resolve-partner-delivery-alert com uma explicação do que foi feito.

Regras desta operação

• Não reconheça todos os alertas automaticamente apenas para zerar indicadores: a ação registra responsabilidade de atendimento.
• Reconhecer não muda credenciais Meta, não regulariza pagamento e não reenviará mensagens.

Registrar o encerramento manual de um alerta de entrega, com a justificativa da resolução.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal antes de acessar os recursos operacionais. O perfil do membro e suas permissões continuam sendo conferidos.
• Ter o ID do alerta de entrega e a conclusão da análise.
• Usar uma sessão de membro com permissão de triagem/resolução.

Autenticação e permissão

Exige access_token obtido no login de membro. A Partner API Key não é aceita nesta operação. Funções permitidas: owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=resolve-partner-delivery-alert

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer ACCESS_TOKEN_DO_MEMBRO",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "alert_id": "ALERT_ID",
  "resolution_notes": "Causa revisada pelo responsável"
}

O que preencher em cada campo

Como ler a resposta

Retorna ok=true e alert atualizado: status=resolved, resolved_at, resolved_by, resolution_notes e metadata.resolved_by_source. O histórico do alerta permanece; a ação não apaga eventos de falha anteriores.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal. Não faça retry automático.
• 400 invalid_alert_id: informe UUID válido.
• 400 resolution_notes_required: notes/resolution_notes ausente ou vazio.
• 404 delivery_alert_not_found: alerta não encontrado.
• 403 delivery_alert_access_denied ou delivery_alert_resolve_forbidden: acesso recusado.
• 500 delivery_alert_resolve_failed: falha ao registrar o encerramento.

Depois desta chamada

• Mostre a nota e o horário de resolução no histórico do atendimento.
• Continue monitorando novos relatórios de entrega para identificar recorrências.

Regras desta operação

• Encerrar manualmente o alerta não corrige a causa técnica por si só.
• Novas falhas podem gerar ou reabrir um acompanhamento; a resolução não funciona como bloqueio permanente de novos alertas.

Consultar o panorama de risco Meta do parceiro, incluindo alertas e clientes com restrições para novas conexões.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Ter a integração Meta e o recebimento/processamento de eventos de gestão configurados.
• Entender que o painel reflete os eventos e estados conhecidos pela HookCloud, não uma auditoria em tempo real de toda a conta Meta.

Autenticação e permissão

Partner API Key ativa com meta_risk.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=get-meta-risk-dashboard

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

Retorna ok, partner_id, summary, settings, customer_states e latest_alerts. summary traz open_alerts, critical_alerts, high_alerts, unacknowledged_alerts, blocked_customers, risky_instances, disabled_wabas, risky_templates e latest_alert_at. open_alerts inclui os abertos e reconhecidos. settings contém a configuração de monitoramento consultada, sem oferecer alteração por esta rota. customer_states contém até 100 estados, priorizados por quantidade de instâncias em risco, com partner_customer_id, risky_instances_count, flagged_instances_count, red_instances_count, disabled_instances_count, risk_level, block_new_connections, manual_block_override, manual_block_reason, threshold_reached_at, last_event_at, reviewed_at, review_notes e dados do customer/partner associados. latest_alerts é a primeira página de 10 alertas no formato items,total,page,page_size,pages. incident_history traz incidentes BAN/RED separados dos alertas operacionais e sua cobertura histórica. current_state_coverage.limit=100 e truncated indicam o limite dos destaques atuais. A paginação solicitada aplica-se a incident_history, não a customer_states/latest_alerts. customer_risk contém a política individual do cliente: ban_count_30d, red_count_30d, limits={ban:20,red:5}, window_days=30, block_new_connections, reasons, next_exit_at, next_unlock_at e a cobertura histórica. Os limites bloqueiam novas conexões desse cliente, mesmo com vagas no pacote, sem desligar números existentes. Atualize seu cache com hookcloud.customer.risk_updated e reconcilie pela Partner API.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 500 meta_risk_dashboard_failed: falha ao carregar algum componente do painel. Não converta ausência de resposta em "sem riscos".

Depois desta chamada

• Apresente primeiro clientes com block_new_connections=true e alertas de maior severidade.
• Use search-meta-risk-alerts para investigar os alertas e acknowledge-meta-risk-alert quando um responsável assumir a análise.
• Associe os registros ao partner_customer_id correto antes de mostrar risco a um cliente do assinante.

Regras desta operação

• block_new_connections impede novas conexões conforme a política de risco; esse indicador não significa que o sistema desconectou automaticamente todos os números existentes.
• O limite de 100 customer_states é uma lista de destaque, não uma exportação completa de todos os clientes do parceiro.
• Não crie uma automação para contornar um bloqueio de risco com outro cadastro de cliente; investigue e regularize a origem.
• Reconhecer um alerta não elimina um episódio de BAN/RED. Um evento genérico de conta ativa não prova que a Meta removeu um banimento. O histórico começa na implantação desta coleta, sem preenchimento retroativo fictício.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Pesquisar alertas de risco Meta por texto, estado, severidade, categoria e período.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Conhecer os estados e categorias dos alertas retornados no próprio ambiente. Não é necessário aplicar todos os filtros.

Autenticação e permissão

Partner API Key ativa com meta_risk.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=search-meta-risk-alerts&page=1&page_size=20

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

Retorna ok, partner_id e a página items,total,page,page_size,pages. items contém os registros de meta_risk_alerts enriquecidos pela consulta, com id, status, severity, category, title, description, referências de parceiro/cliente/instância/WABA quando disponíveis, metadata e datas de reconhecimento/resolução. Use id como alert_id para reconhecimento. total corresponde ao conjunto filtrado; um array vazio é resultado válido.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 500 meta_risk_alert_search_failed: erro na pesquisa. Valide na sua integração datas ISO e paginação; esta família de consultas não deve ser usada para testar coerções de tipos do banco.

Depois desta chamada

• Percorra pages caso precise de todos os registros; mantenha os filtros nas páginas seguintes.
• Abra o contexto do cliente/instância antes de acionar uma correção.
• Ao assumir um caso, chame acknowledge-meta-risk-alert com uma nota objetiva.

Regras desta operação

• Esta rota consulta risco de gestão Meta. Para pesquisar estados sent/delivered/read de mensagens, use search-partner-delivery-events.
• Alertas não são provas de indisponibilidade global da Meta: leia a categoria, a descrição e a origem concreta de cada ocorrência.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Registrar que um operador reconheceu um alerta de risco Meta e assumiu sua análise.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal antes de acessar os recursos operacionais. O perfil do membro e suas permissões continuam sendo conferidos.
• Ter alert_id de search-meta-risk-alerts ou do painel de risco.
• Autenticar um membro com papel permitido; esta mutação de triagem não é liberada apenas por usar uma chave de API do parceiro.

Autenticação e permissão

Exige access_token obtido no login de membro. A Partner API Key não é aceita nesta operação. Funções permitidas: owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=acknowledge-meta-risk-alert

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer ACCESS_TOKEN_DO_MEMBRO",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "alert_id": "ALERT_ID",
  "notes": "Alerta em análise"
}

O que preencher em cada campo

Como ler a resposta

Retorna ok e alert com status=acknowledged, acknowledged_at, acknowledged_by e a nota em metadata.acknowledgement_notes. Os demais dados do alerta permanecem disponíveis para investigação.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal. Não faça retry automático.
• 400 invalid_alert_id: identificador inválido.
• 404 meta_risk_alert_not_found: alerta não encontrado.
• 403 meta_risk_alert_access_denied: alerta fora do parceiro autorizado.
• 403 meta_risk_acknowledge_forbidden: sessão/papel não autorizado a reconhecer.
• 500 meta_risk_alert_acknowledge_failed: reconhecimento não registrado.

Depois desta chamada

• Atualize a fila de atendimento usando o alert retornado.
• Investigue o motivo na conta, instância ou template indicado. A regularização da causa pode exigir ação na Meta ou análise administrativa da HookCloud.

Regras desta operação

• Reconhecer não remove block_new_connections, não aprova nome de exibição e não conclui verificações da Meta.
• Não existe, entre as rotas de assinante desta ficha, um comando genérico para encerrar qualquer risco administrativo. Não reutilize resolve-partner-delivery-alert com um ID de risco Meta.

Consultar a assinatura, o catálogo de pacotes, a capacidade ocupada e as pendências de cobrança do parceiro autenticado.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• Usar a credencial do parceiro correto e conferir environment na resposta.
• Não é necessário fornecer partner_id, subscription_id ou customer_id Stripe no corpo: o vínculo é resolvido pelo servidor.

Autenticação e permissão

Partner API Key ativa com billing.read ou *. Se optar por JWT, as funções permitidas são owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-billing-summary

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Esta operação não exige campos adicionais. A identidade do parceiro vem da autenticação.

Como ler a resposta

Retorna ok, billing_model="number_packs_v2", environment, catalog, packs, status, number_limit, used_numbers, available_numbers, monthly_price_cents, period_end, cancel_at_period_end, pending_change, checkout_url, payment_pending, payment_url, trial e trial_days. catalog lista os pacotes suportados; packs representa o total contratado. Os códigos atuais são partner_numbers_4 (4 números; 9990 centavos/mês), partner_numbers_25 (25; 49990 centavos/mês) e partner_numbers_100 (100; 150000 centavos/mês). status vem do estado reconciliado da assinatura ou unsubscribed. pending_change, quando existe, contém id,packs,number_limit,recurring_cents,status. available_numbers desconta used_numbers do menor limite entre o vigente e uma redução já agendada. trial, quando disponível, contém started_at e ends_at; trial_days=3 indica elegibilidade para um trial ainda não usado e 0 indica que ele já foi usado, não quantos dias restam do trial atual. checkout_url e payment_url podem ser nulos. Campos adicionais: paid_capacity_current_period é null sem pagamento comprovado; used_slots são números em uso; reserved_slots são reservas não consumidas; available_slots respeita o menor limite atual/futuro; renewal_capacity é a capacidade programada. paid_period{start,end,invoice_id,subscription_id}, observed_period, original_contract_started_at, next_billing_at, latest_invoice{id,status,due_at,paid_at,amount_due_cents,amount_remaining_cents,billing_reason}, payment_evidence{status,source}. Campos ausentes continuam null; não inferir mensalidade paga por status active ou trialing.

Erros e como agir

• 409 billing_change_in_progress: outra operação de assinatura está em curso; aguarde e consulte novamente.
• 503 number_pack_billing_unavailable, billing_storage_unavailable ou capacity_unavailable: o serviço não conseguiu reconciliar cobrança/capacidade. Não invente limites na sua integração.

Depois desta chamada

• Mostre capacidade vigente, ocupação e mudança agendada separadamente.
• Se houver checkout_url ou payment_url, ofereça o link ao responsável autorizado.
• Para alteração de pacotes, monte o total desejado e chame preview-number-pack-change.

Regras desta operação

• Em produção, operações de aplicação e gestão de assinatura podem alterar uma cobrança real. No da integração, deixe essas ações atrás de uma decisão explícita do assinante; não execute toda a coleção de nós em sequência.
• Os valores monetários são inteiros em centavos de real. 9990 significa R$ 99,90. Não envie números de ponto flutuante nem formate valores como "99,90" na API.
• O modelo ativo é number_packs_v2, com capacidade compartilhada por números entre os clientes do parceiro. Não é o antigo pacote de quantidade de clientes.
• Esta consulta pode conferir a Stripe e reconciliar o estado local. Não cria uma cobrança nova, mas também não é apenas uma leitura estática do banco.
• Nunca calcule a disponibilidade apenas por number_limit-used_numbers quando existir pending_change: use available_numbers retornado.
• Um status de pagamento pendente não autoriza liberar capacidade adicional no seu sistema.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Aliases aceitos: get-partner-stripe-billing-summary. Prefira o nome do exemplo.

Calcular e registrar uma proposta de alteração do conjunto total de pacotes, com valor imediato, recorrência e momento de aplicação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Consultar o resumo atual e a ocupação antes de montar a proposta.
• Decidir o total final desejado, incluindo os pacotes que continuarão contratados.
• Usar a mesma identidade de autenticação na prévia e na aplicação: a proposta é vinculada ao parceiro e ao ator (chave ou usuário).

Autenticação e permissão

Partner API Key ativa com billing.write ou *. Se optar por JWT, as funções permitidas são owner, admin.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=preview-number-pack-change

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "packs": [
    {
      "code": "OAUTH_CODE",
      "quantity": 1
    }
  ]
}

O que preencher em cada campo

Como ler a resposta

Retorna ok e a proposta: id, packs, timing, amount_due_cents, recurring_cents, number_limit, expires_at, trial_days e effective_at. timing pode ser checkout para nova contratação, immediate para aumento aplicável agora ou renewal para redução na renovação. amount_due_cents é o valor previsto para cobrança imediata; recurring_cents é a mensalidade resultante. Uma contratação elegível ao trial de 3 dias pode ter amount_due_cents=0 sem ser um plano gratuito. A prévia é salva no servidor; ela não cobra nem libera capacidade. expires_at deve ser respeitado; use o id retornado como quote_id na aplicação.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 400 invalid_packs: packs não é um array válido de 1 a 3 entradas.
• 400 invalid_pack_quantity: código desconhecido/duplicado ou quantidade não inteira/fora de 0 a 100.
• 400 use_subscription_cancellation: todas as quantidades são zero; use a rota de cancelamento da assinatura.
• 409 numbers_in_use_exceed_target: o total pretendido não comporta os números em uso. Exemplo: 7 números ocupados impedem reduzir para 4.
• 409 packs_unchanged: o conjunto desejado já é o atual.
• 409 cancel_scheduled_change_first ou scheduled_change_exists: existe mudança futura; resolva-a antes de criar outra.
• 409 billing_payment_required, payment_update_pending, subscription_cancellation_pending, automatic_collection_required ou outstanding_invoice: a situação da assinatura precisa ser regularizada antes da alteração.
• 409 billing_change_in_progress: outra alteração está sendo processada.

Depois desta chamada

• Apresente amount_due_cents, recurring_cents, number_limit, timing, effective_at e trial_days ao assinante.
• Após decisão explícita, aplique exatamente esse id por apply-number-pack-change.
• Se o usuário mudar a escolha ou a proposta expirar, faça uma nova prévia e mostre novamente os valores.

Regras desta operação

• Em produção, operações de aplicação e gestão de assinatura podem alterar uma cobrança real. No da integração, deixe essas ações atrás de uma decisão explícita do assinante; não execute toda a coleção de nós em sequência.
• Os valores monetários são inteiros em centavos de real. 9990 significa R$ 99,90. Não envie números de ponto flutuante nem formate valores como "99,90" na API.
• O modelo ativo é number_packs_v2, com capacidade compartilhada por números entre os clientes do parceiro. Não é o antigo pacote de quantidade de clientes.
• Exemplo: quem já possui 1 pacote de 4 e quer terminar com 8 números envia quantity=2 para partner_numbers_4; enviar quantity=1 não adiciona outro pacote.
• Qualquer redução de capacidade OU mensalidade é tratada para a renovação, conforme as regras do serviço. Não suponha aplicação imediata de uma redução.
• A trava de downgrade não desconecta números automaticamente. É necessário reduzir a ocupação por uma decisão separada do assinante antes de propor um limite menor.
• Não aplique automaticamente uma prévia só porque o HTTP retornou 200. A prévia é uma etapa de revisão comercial.

Aplicar uma proposta de pacotes previamente calculada e aceita, iniciando checkout, atualização de assinatura ou redução agendada conforme a proposta.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal. A API Key não pode enviar esse cadastro; consulte get-partner-onboarding-status para identificar registration_complete=false.
• Ter quote_id retornado por preview-number-pack-change, ainda válido.
• Usar o mesmo parceiro e ator que criaram a prévia.
• Preservar o mesmo quote_id em uma repetição após timeout; não criar uma nova compra automaticamente.

Autenticação e permissão

Partner API Key ativa com billing.write ou *. Se optar por JWT, as funções permitidas são owner, admin.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=apply-number-pack-change

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "quote_id": "UUID_DA_PROPOSTA"
}

O que preencher em cada campo

Como ler a resposta

Retorna ok e um resultado de fluxo. status=checkout vem com url para o assinante concluir a contratação. status=payment_pending ou applied pode vir com url de fatura ou null, conforme a atualização imediata. status=scheduled vem com effective_at para a redução na renovação. Um pedido repetido com a mesma proposta pode devolver o resultado já armazenado. A capacidade só é liberada após a confirmação aplicável da Stripe; payment_pending não equivale a pagamento concluído. Leia o resumo de cobrança para confirmar o estado reconciliado.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal antes desta operação. Não faça retry automático nem envie documentos nos campos de clientes.
• 404 quote_not_found: a proposta não existe para o parceiro/ator atual; confira a credencial usada na prévia.
• 409 quote_expired ou quote_not_available: a proposta expirou ou não está em estado aplicável.
• 409 quote_stale ou quote_amount_changed: a assinatura/valor mudou desde a prévia; refaça a proposta e obtenha nova decisão.
• 409 numbers_in_use_exceed_target: a ocupação mudou e já não cabe no limite pretendido.
• 409 checkout_already_open: existe checkout aberto; consulte o resumo em vez de criar uma duplicata.
• 409 checkout_pending_reconciliation ou billing_reconciliation_required: o resultado anterior exige reconciliação; não contorne com uma compra nova.
• 409 billing_change_in_progress: operação concorrente em andamento.
• Falha de pagamento/Stripe: preserve o diagnóstico e use payment_url/checkout_url quando disponibilizados. Uma recusa de cartão não deve ser tratada como capacidade liberada.

Depois desta chamada

• Se checkout, entregue a url ao assinante em um navegador; o cliente HTTP da integração não substitui a interação de pagamento.
• Se scheduled, apresente a data efetiva e o futuro limite. Se payment_pending, aguarde a regularização.
• Depois, consulte get-partner-billing-summary e atualize a interface com o estado real.

Regras desta operação

• Em produção, operações de aplicação e gestão de assinatura podem alterar uma cobrança real. No da integração, deixe essas ações atrás de uma decisão explícita do assinante; não execute toda a coleção de nós em sequência.
• Os valores monetários são inteiros em centavos de real. 9990 significa R$ 99,90. Não envie números de ponto flutuante nem formate valores como "99,90" na API.
• O modelo ativo é number_packs_v2, com capacidade compartilhada por números entre os clientes do parceiro. Não é o antigo pacote de quantidade de clientes.
• A idempotência é vinculada à proposta. Em timeout, repita o mesmo quote_id com a mesma identidade, em vez de gerar outra proposta sem saber o resultado anterior.
• A redução agendada reserva o limite futuro para impedir novas conexões que tornariam a redução impossível. available_numbers pode diminuir antes da renovação.
• Não publique links de checkout/fatura em logs acessíveis a todos os clientes do assinante.

Cancelar a mudança de pacotes que está agendada para uma renovação futura.

Antes de começar

• Ter uma mudança agendada no resumo de cobrança.
• Obter a decisão do responsável de cancelar essa mudança específica.

Autenticação e permissão

Partner API Key ativa com billing.write ou *. Se optar por JWT, as funções permitidas são owner, admin.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=cancel-number-pack-change

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{}

O que preencher em cada campo

Esta operação não exige campos adicionais. A identidade do parceiro vem da autenticação.

Como ler a resposta

Retorna ok=true e status="canceled" quando a mudança futura é cancelada. O serviço libera o agendamento na Stripe e remove a referência/limite pendente no estado interno. Esta resposta diz respeito à mudança de pacotes, não ao cancelamento da assinatura vigente.

Erros e como agir

• 404 scheduled_change_not_found: não existe mudança futura para cancelar.
• 409 scheduled_change_already_effective: a alteração já foi efetivada; não pode ser desfeita como agendamento.
• 409 schedule_reconciliation_required: o estado do agendamento exige reconciliação antes de nova ação.
• 409 billing_change_in_progress: aguarde a operação em curso.

Depois desta chamada

• Consulte novamente o resumo e confirme pending_change=null.
• Se o assinante desejar outra composição, crie uma nova prévia usando o total final pretendido.

Regras desta operação

• Em produção, operações de aplicação e gestão de assinatura podem alterar uma cobrança real. No da integração, deixe essas ações atrás de uma decisão explícita do assinante; não execute toda a coleção de nós em sequência.
• Os valores monetários são inteiros em centavos de real. 9990 significa R$ 99,90. Não envie números de ponto flutuante nem formate valores como "99,90" na API.
• O modelo ativo é number_packs_v2, com capacidade compartilhada por números entre os clientes do parceiro. Não é o antigo pacote de quantidade de clientes.
• Não use esta rota para cancelar a assinatura. Para isso existe cancel-stripe-subscription.
• Cancelar a mudança futura não estorna automaticamente cobranças que já ocorreram.
• A rota de recuperação/cancelamento de cobrança continua acessível com as permissões existentes mesmo enquanto o cadastro obrigatório do proprietário estiver pendente.

Gerar uma sessão temporária do portal de cobrança Stripe associado ao parceiro.

Antes de começar

• Ter uma assinatura vinculada ao parceiro e a configuração do portal disponível no ambiente.
• Entregar o link apenas ao responsável autorizado pela cobrança.

Autenticação e permissão

Partner API Key ativa com billing.write ou *. Se optar por JWT, as funções permitidas são owner, admin.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=create-billing-portal-session

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{}

O que preencher em cada campo

Esta operação não exige campos adicionais. A identidade do parceiro vem da autenticação.

Como ler a resposta

Retorna ok=true e url da sessão de portal Stripe. A criação da sessão não representa, por si só, pagamento ou alteração de plano. As ações disponíveis dentro do portal dependem da configuração da HookCloud na Stripe.

Erros e como agir

• 404 subscription_not_found: não há assinatura vinculada para abrir o portal.
• 503 billing_portal_not_configured: o portal não está configurado no ambiente.
• 503 number_pack_billing_unavailable: falha de integração ao gerar a sessão.

Depois desta chamada

• Abra/entregue a url ao assinante no navegador.
• Depois de uma ação no portal, consulte get-partner-billing-summary para atualizar o estado mostrado no sistema.

Regras desta operação

• Em produção, operações de aplicação e gestão de assinatura podem alterar uma cobrança real. No da integração, deixe essas ações atrás de uma decisão explícita do assinante; não execute toda a coleção de nós em sequência.
• Os valores monetários são inteiros em centavos de real. 9990 significa R$ 99,90. Não envie números de ponto flutuante nem formate valores como "99,90" na API.
• O modelo ativo é number_packs_v2, com capacidade compartilhada por números entre os clientes do parceiro. Não é o antigo pacote de quantidade de clientes.
• A url é uma sessão temporária de acesso à cobrança; não a trate como um link público permanente.
• Não prometa que todos os tipos de alteração estão disponíveis no portal. Para mudar os pacotes pelo fluxo Partner, utilize prévia e aplicação.
• A rota de recuperação/cancelamento de cobrança continua acessível com as permissões existentes mesmo enquanto o cadastro obrigatório do proprietário estiver pendente.

Aliases aceitos: create-stripe-customer-portal-session. Prefira o nome do exemplo.

Agendar o cancelamento da assinatura do parceiro para o fim do período vigente.

Antes de começar

• Ter assinatura em estado compatível (active, trialing ou past_due).
• Resolver primeiro uma mudança de pacotes futura ou um pagamento pendente que impeça o cancelamento.
• Mostrar a data de fim do período retornada pelo resumo antes de confirmar.

Autenticação e permissão

Partner API Key ativa com billing.write ou *. Se optar por JWT, as funções permitidas são owner, admin.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=cancel-stripe-subscription

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{}

O que preencher em cada campo

Esta operação não exige campos adicionais. A identidade do parceiro vem da autenticação.

Como ler a resposta

Retorna ok=true e status="cancellation_scheduled". O serviço configura cancel_at_period_end=true na Stripe e reconcilia a assinatura. Consulte o resumo para obter period_end e confirmar o agendamento. No modelo v2 desta API, esta chamada não solicita cancelamento imediato.

Erros e como agir

• 404 subscription_not_found: não existe assinatura vinculada.
• 409 cancel_scheduled_change_first: há uma mudança de pacotes futura para resolver antes.
• 409 payment_pending: existe uma atualização/pagamento pendente.
• 409 subscription_not_changeable: o estado da assinatura não permite esta operação.
• 409 billing_change_in_progress: outra operação está em andamento.

Depois desta chamada

• Releia o resumo e mostre cancel_at_period_end=true e period_end.
• Se o assinante desistir antes do encerramento efetivo, use resume-stripe-subscription.

Regras desta operação

• Em produção, operações de aplicação e gestão de assinatura podem alterar uma cobrança real. No da integração, deixe essas ações atrás de uma decisão explícita do assinante; não execute toda a coleção de nós em sequência.
• Os valores monetários são inteiros em centavos de real. 9990 significa R$ 99,90. Não envie números de ponto flutuante nem formate valores como "99,90" na API.
• O modelo ativo é number_packs_v2, com capacidade compartilhada por números entre os clientes do parceiro. Não é o antigo pacote de quantidade de clientes.
• Não envie immediate=true, reason ou parâmetros herdados do fluxo antigo esperando cancelamento imediato; o handler v2 ativo não usa esses campos.
• O agendamento não desconecta imediatamente os números para forçar um downgrade. A política após o encerramento deve ser apresentada pelo estado vigente do serviço.
• A operação não é um pedido de reembolso.
• A rota de recuperação/cancelamento de cobrança continua acessível com as permissões existentes mesmo enquanto o cadastro obrigatório do proprietário estiver pendente.

Retirar o cancelamento agendado e permitir a continuidade da assinatura ainda existente.

Antes de começar

• Ter assinatura ainda em estado alterável e decisão explícita de continuar as renovações.
• Consultar o resumo para verificar cancel_at_period_end e eventual pendência de pagamento.

Autenticação e permissão

Partner API Key ativa com billing.write ou *. Se optar por JWT, as funções permitidas são owner, admin.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=resume-stripe-subscription

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer SUA_PARTNER_API_KEY_COMPLETA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{}

O que preencher em cada campo

Esta operação não exige campos adicionais. A identidade do parceiro vem da autenticação.

Como ler a resposta

Retorna ok=true e status="active" como resultado da ação de retomada. O serviço configura cancel_at_period_end=false e reconcilia a assinatura. Esse rótulo de resultado não substitui o status financeiro real: uma assinatura trialing ou past_due precisa ser lida no resumo depois da operação.

Erros e como agir

• 404 subscription_not_found: assinatura inexistente.
• 409 subscription_not_changeable: assinatura já encerrada ou em estado que não permite a alteração.
• 409 cancel_scheduled_change_first ou payment_pending: resolva a pendência indicada.
• 409 billing_change_in_progress: aguarde a operação em curso.

Depois desta chamada

• Consulte get-partner-billing-summary e confirme cancel_at_period_end=false.
• Mostre o estado financeiro real e a próxima data de período ao assinante.
• Se a assinatura já estiver cancelada, use uma nova proposta/checkout permitido pelo serviço, em vez de repetir indefinidamente a retomada.

Regras desta operação

• Em produção, operações de aplicação e gestão de assinatura podem alterar uma cobrança real. No da integração, deixe essas ações atrás de uma decisão explícita do assinante; não execute toda a coleção de nós em sequência.
• Os valores monetários são inteiros em centavos de real. 9990 significa R$ 99,90. Não envie números de ponto flutuante nem formate valores como "99,90" na API.
• O modelo ativo é number_packs_v2, com capacidade compartilhada por números entre os clientes do parceiro. Não é o antigo pacote de quantidade de clientes.
• Esta rota não recria uma assinatura já encerrada e não confirma pagamento de uma fatura pendente.
• Continuar a assinatura implica renovação/cobrança futura; não execute como recuperação automática de erro sem decisão do assinante.
• A rota de recuperação/cancelamento de cobrança continua acessível com as permissões existentes mesmo enquanto o cadastro obrigatório do proprietário estiver pendente.

Convidar um colaborador para a equipe do parceiro e associar seu usuário ao papel definido.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal antes de acessar os recursos operacionais. O perfil do membro e suas permissões continuam sendo conferidos.
• Ter o e-mail correto do colaborador e decisão de conceder acesso.
• Respeitar a hierarquia: owner pode convidar admin/member; admin pode convidar member.
• Haver vaga no limite de 5 colaboradores não proprietários aplicado pelo sistema.

Autenticação e permissão

Exige access_token obtido no login de membro. A Partner API Key não é aceita nesta operação. Funções permitidas: owner, admin.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=invite-partner-member

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer ACCESS_TOKEN_DO_MEMBRO",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "email": "INVITE_EMAIL",
  "role": "member"
}

O que preencher em cada campo

Como ler a resposta

Retorna ok e member com id,partner_id,user_id,email,role,status,joined_at,created_at, além de invite_sent, password_email_sent, auth_user_creation_mode, auth_user_source, collaborator_limit, collaborator_count_before, redirect_to, warning e message. auth_user_creation_mode diferencia invited_new_user de existing_user. status será active se a conta já estiver confirmada, ou invited quando depender do primeiro acesso. Para usuário novo, o fluxo usa convite; para um usuário já existente, pode enviar recuperação de senha. warning pode conter code=password_email_not_sent: nesse caso, a associação foi realizada, mas o e-mail complementar não foi enviado. Não interprete esse aviso como convite inteiramente desfeito.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal. Não faça retry automático.
• 400 invalid_email: endereço inválido ou acima do limite.
• 400 invalid_role: papel fora de admin/member.
• 403 insufficient_role: quem convida não pode atribuir o papel pedido.
• 409 member_already_active: o usuário já é membro ativo do parceiro.
• 409 collaborator_limit_reached: limite de colaboradores atingido.
• 503 invite_delivery_unavailable: o serviço de convite não conseguiu enviar para o novo usuário; a integração não deve informar falsamente que o convite chegou.
• 500 member_lookup_failed, member_upsert_failed ou auth_user_missing_after_invite: falha ao localizar/vincular o membro. Verifique o estado antes de repetir convites em sequência.

Depois desta chamada

• Guarde member.id para futuras operações de equipe; esse ID é diferente de user_id do Auth.
• Mostre se o acesso ficou active/invited e se houve warning no envio.
• Oriente o colaborador a abrir o e-mail de convite/recuperação mais recente e concluir a definição de senha no endereço correto do ambiente.

Regras desta operação

• Esta rota envia e-mail de acesso e concede permissão; mantenha-a fora de loops automáticos e use destinatários realmente autorizados.
• Repetir a operação com novos e-mails não é um teste inofensivo: cria associações de equipe reais.
• Não peça nem transporte a senha do colaborador no body do convite. A definição de senha ocorre pelo fluxo de acesso apropriado.
• Um convite de equipe não cria uma empresa cliente nem reserva um número do pacote.

Alterar o papel de um membro já associado à equipe do parceiro.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal antes de acessar os recursos operacionais. O perfil do membro e suas permissões continuam sendo conferidos.
• Usar a sessão de owner: esta rota exige proprietário mesmo para mudar admin para member.
• Ter member_id da associação ao parceiro, não user_id do Auth.
• Revisar o impacto de conceder owner, que amplia o controle sobre equipe e operação.

Autenticação e permissão

Exige access_token obtido no login de membro. A Partner API Key não é aceita nesta operação. Funções permitidas: owner.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=update-partner-member-role

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer ACCESS_TOKEN_DO_MEMBRO",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "member_id": "MEMBER_ID",
  "role": "member"
}

O que preencher em cada campo

Como ler a resposta

Retorna ok=true e member com id,partner_id,user_id,email,role,status,joined_at. O campo role retornado é o novo papel persistido. status do membro não é reativado automaticamente por esta mudança de papel.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal. Não faça retry automático.
• 400 invalid_payload: member_id ou papel ausente/inválido.
• 403 owner_required: sessão não pertence a um owner autorizado.
• 404 member_not_found: associação não encontrada no parceiro.
• 400 cannot_demote_self: o owner não pode rebaixar o próprio papel por esta operação.
• 409 last_owner_protected: a alteração deixaria o parceiro sem proprietário.
• 409 collaborator_limit_reached: rebaixar um owner para colaborador excederia o limite de colaboradores.
• 500 member_role_update_failed: a mudança não foi concluída.

Depois desta chamada

• Atualize a lista de equipe com o member retornado.
• Se a interface mantiver permissões em cache, atualize a sessão/contexto antes de mostrar ações autorizadas.

Regras desta operação

• role=owner é uma concessão de controle sensível, não apenas um rótulo visual.
• Não use a mudança de papel para tentar contornar o limite de colaboradores.
• A proteção de último owner e a proibição de rebaixar a si próprio devem ser respeitadas na sua integração, não escondidas em repetição automática.

Desativar a associação de um colaborador à equipe do parceiro.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal antes de acessar os recursos operacionais. O perfil do membro e suas permissões continuam sendo conferidos.
• Ter member_id correto e confirmar a pessoa que perderá acesso.
• Respeitar a hierarquia: owner gerencia membros não owner; admin remove apenas member.
• Não apontar a chamada para o próprio usuário autenticado.

Autenticação e permissão

Exige access_token obtido no login de membro. A Partner API Key não é aceita nesta operação. Funções permitidas: owner, admin.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=remove-partner-member

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer ACCESS_TOKEN_DO_MEMBRO",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "member_id": "MEMBER_ID"
}

O que preencher em cada campo

Como ler a resposta

Retorna ok=true e member com id,partner_id,user_id,email,role,status,joined_at; status passa para inactive. A operação mantém o registro de equipe e não apaga a conta global do usuário no Auth.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal. Não faça retry automático.
• 400 cannot_remove_self: não é permitido remover a própria associação.
• 404 member_not_found: membro não encontrado no parceiro.
• 403 insufficient_role: a hierarquia não permite remover esse alvo; um owner não é removido diretamente por esta regra de gestão.
• 409 last_owner_protected: proteção contra ausência de proprietário.
• 500 member_remove_failed: não foi possível desativar a associação.

Depois desta chamada

• Confirme member.status=inactive e atualize a lista de equipe.
• Revise separadamente as credenciais de integração que a pessoa administrava, quando isso fizer parte do procedimento do assinante.

Regras desta operação

• Desativar um membro não elimina seus registros de auditoria nem a conta global de login.
• A remoção de equipe não apaga empresas clientes, instâncias ou mensagens.
• Não prometa uma transferência automática de propriedade. Se for necessário substituir owner, planeje os papéis e proteções antes desta ação.

Revelar a cópia recuperável de uma chave de API do parceiro para configuração autorizada de uma integração.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal antes de acessar os recursos operacionais. O perfil do membro e suas permissões continuam sendo conferidos.
• Usar uma sessão de membro autorizada a revelar a chave; uma chave de API não pode chamar esta rota para revelar outra chave.
• Ter api_key_id do registro correto, ativo, não expirado e com material criptografado recuperável.
• Preparar o armazenamento de credencial antes de revelar, evitando que o segredo fique em históricos compartilhados.

Autenticação e permissão

Exige access_token obtido no login de membro. A Partner API Key não é aceita nesta operação. Funções permitidas: owner, admin, developer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=reveal-partner-api-key

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer ACCESS_TOKEN_DO_MEMBRO",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "api_key_id": "API_KEY_ID"
}

O que preencher em cada campo

Como ler a resposta

Retorna ok, api_key_id, partner_id, name, key_prefix, key_hint, api_key, scopes, status, last_used_at e created_at. api_key contém o segredo em texto para a configuração; key_prefix/key_hint servem apenas para identificação e não autenticam. A revelação é auditada e atualiza a informação de revelação. Não inclua esse resultado em exemplos públicos, PDFs, capturas ou mensagens de suporte.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal. Não faça retry automático.
• 403 forbidden: autenticação por chave de API não pode revelar o segredo.
• 403 insufficient_role: membro não autorizado para a revelação.
• 404 api_key_not_found: registro não encontrado no parceiro.
• 409 api_key_inactive ou api_key_expired: a chave não pode ser usada/revelada nessa condição.
• 409 api_key_not_recoverable: chave antiga sem cópia criptografada recuperável; não existe como reconstruí-la a partir do hash.
• 500 api_key_decrypt_failed: falha ao abrir a cópia criptografada; acione suporte sem enviar o segredo.

Depois desta chamada

• Armazene api_key diretamente na credencial segura do seu sistema e aplique-a em Authorization conforme a seção de autenticação do manual.
• Use scopes para conferir se a chave atende somente às operações necessárias.
• Finalize a configuração evitando salvar o resultado de revelação como dado fixo de um sistema exportável.

Regras desta operação

• Uma execução de da integração que grava todo o JSON de resposta pode persistir o segredo no histórico. Prefira configuração manual controlada de credencial, com política apropriada de retenção/acesso.
• Nunca use key_prefix ou key_hint no lugar de api_key.
• A revelação não amplia scopes, não reativa uma chave e não prorroga sua expiração.
• Não repita a revelação em agendamentos. Os nós de operação devem reutilizar a credencial já armazenada.

Carregar a lista de notificações visíveis para o membro e sua contagem de não lidas.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal antes de acessar os recursos operacionais. O perfil do membro e suas permissões continuam sendo conferidos.
• Usar a sessão de membro; o contexto individual é obrigatório para aplicar destino e leitura.
• Ter em mente que categorias desabilitadas nas preferências são filtradas da lista.

Autenticação e permissão

Exige access_token obtido no login de membro. A Partner API Key não é aceita nesta operação. Funções permitidas: owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=list-partner-notifications&limit=30

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer ACCESS_TOKEN_DO_MEMBRO"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Como ler a resposta

Retorna ok, items, unread e preferences. Cada item contém os campos da notificação: id,partner_id,target_user_id,category,event_type,severity,title,body,target_url,source_table,source_id,dedupe_key,metadata,expires_at,created_at,updated_at e read_at obtido da leitura pessoal. read_at=null indica que o membro ainda não a marcou como lida. Não há campo is_read calculado nesta resposta; derive-o a partir de read_at. unread conta todas as notificações não lidas visíveis nas preferências, independentemente do limite/cursor da página. preferences contém notify_academy, notify_meta_alerts, notify_templates, notify_delivery_health, notify_billing, notify_billing_reminders, notify_system e popup_enabled. São preferências pessoais do membro autenticado dentro do parceiro. Os valores padrão do serviço são true quando não há escolha gravada.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal. Não faça retry automático.
• 500 notification_list_failed: falha ao carregar notificações. Não zere unread na interface como se não houvesse pendências.
• Falha de autenticação de membro: renove a sessão pelo fluxo previsto; não tente substituir o JWT por uma chave de API.

Depois desta chamada

• Mostre title/body/severity e trate target_url como destino de navegação, não como comando a executar.
• Para paginação, conserve o cursor do último created_at e interrompa quando não vierem itens.
• Ao usuário abrir um aviso, envie seu id para mark-partner-notification-read.

Regras desta operação

• Notificações são pessoais: o usuário autenticado determina os destinatários visíveis, as preferências e as confirmações de leitura. Uma automação com uma única sessão não atua por todos os membros.
• Silenciar uma categoria de notificação não desliga a integração Meta, o webhook, a cobrança nem o cálculo de risco/saúde.
• Notificações expiradas e destinadas a outro usuário não entram na lista.
• A paginação usa timestamp com comparação estrita antes de before; não é uma exportação transacional com cursor único por ID. Evite usar esta central como arquivo completo de eventos de negócio.
• Se usar POST, parâmetros limit/before presentes na query têm precedência sobre o body; mantenha uma única fonte para evitar divergências.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Consultar as preferências de notificação do membro autenticado.

Leitura na HookCloud: retorna dados armazenados e não consulta a Meta a cada acesso. Confira a data da observação.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal antes de acessar os recursos operacionais. O perfil do membro e suas permissões continuam sendo conferidos.
• Ter sessão de membro válida no parceiro. Não há user_id alvo ou partner_id para editar as preferências de outra pessoa.

Autenticação e permissão

Exige access_token obtido no login de membro. A Partner API Key não é aceita nesta operação. Funções permitidas: owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método GET com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-notification-preferences

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer ACCESS_TOKEN_DO_MEMBRO"
}

Sem body. Os filtros e identificadores ficam nos parâmetros da URL. Não acrescente um corpo JSON nesta chamada.

O que preencher em cada campo

Esta operação não exige campos adicionais. A identidade do parceiro vem da autenticação.

Como ler a resposta

Retorna ok=true e preferences. preferences contém notify_academy, notify_meta_alerts, notify_templates, notify_delivery_health, notify_billing, notify_billing_reminders, notify_system e popup_enabled. São preferências pessoais do membro autenticado dentro do parceiro. Os valores padrão do serviço são true quando não há escolha gravada.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal. Não faça retry automático.
• 500 notification_preferences_failed: o serviço não conseguiu consultar as preferências atuais.

Depois desta chamada

• Preencha os controles da interface com os booleanos retornados.
• Envie somente os campos realmente alterados a update-partner-notification-preferences.

Regras desta operação

• Notificações são pessoais: o usuário autenticado determina os destinatários visíveis, as preferências e as confirmações de leitura. Uma automação com uma única sessão não atua por todos os membros.
• Silenciar uma categoria de notificação não desliga a integração Meta, o webhook, a cobrança nem o cálculo de risco/saúde.
• Esta leitura consulta dados armazenados na HookCloud; não dispara um GET à Meta a cada item. Confira as datas da evidência e use atualização explícita apenas quando necessário.

Salvar escolhas pessoais de categorias de notificação e de exibição de popup.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal antes de acessar os recursos operacionais. O perfil do membro e suas permissões continuam sendo conferidos.
• Ter sessão do membro que está alterando suas próprias preferências.
• Produzir booleanos JSON reais no seu sistema; a string "false" não desliga uma opção.

Autenticação e permissão

Exige access_token obtido no login de membro. A Partner API Key não é aceita nesta operação. Funções permitidas: owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=update-partner-notification-preferences

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer ACCESS_TOKEN_DO_MEMBRO",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "preferences": {
    "notify_delivery_health": true
  }
}

O que preencher em cada campo

Como ler a resposta

Retorna ok=true e preferences com o resultado completo após mesclar os campos aceitos com o estado anterior. preferences contém notify_academy, notify_meta_alerts, notify_templates, notify_delivery_health, notify_billing, notify_billing_reminders, notify_system e popup_enabled. São preferências pessoais do membro autenticado dentro do parceiro. Os valores padrão do serviço são true quando não há escolha gravada. Campos desconhecidos e valores que não sejam booleanos não são aplicados; um body vazio não redefine tudo. O serviço registra a alteração em auditoria.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal. Não faça retry automático.
• 500 notification_preferences_failed: não foi possível carregar o estado atual antes da mesclagem.
• 500 notification_preferences_update_failed: não foi possível salvar a alteração.

Depois desta chamada

• Leia a resposta e atualize os controles com os valores efetivamente gravados.
• Consulte a lista novamente se quiser refletir imediatamente as categorias agora visíveis.

Regras desta operação

• Notificações são pessoais: o usuário autenticado determina os destinatários visíveis, as preferências e as confirmações de leitura. Uma automação com uma única sessão não atua por todos os membros.
• Silenciar uma categoria de notificação não desliga a integração Meta, o webhook, a cobrança nem o cálculo de risco/saúde.
• notify_billing e notify_billing_reminders são escolhas distintas. Os lembretes billing.payment_retry_tomorrow, billing.trial_ends_tomorrow e billing.charge_tomorrow seguem a preferência de lembretes.
• Não interprete uma resposta de sucesso como prova de que uma string "false" foi convertida; confira o booleano retornado.
• Evite enviar o objeto completo antigo após muito tempo aberto na tela, pois isso pode sobrescrever uma escolha mais recente do próprio usuário. Prefira atualização parcial.

Registrar que o membro autenticado leu uma notificação específica.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal antes de acessar os recursos operacionais. O perfil do membro e suas permissões continuam sendo conferidos.
• Ter notification_id obtido da lista do mesmo membro/parceiro.

Autenticação e permissão

Exige access_token obtido no login de membro. A Partner API Key não é aceita nesta operação. Funções permitidas: owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=mark-partner-notification-read

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer ACCESS_TOKEN_DO_MEMBRO",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "notification_id": "NOTIFICATION_ID"
}

O que preencher em cada campo

Como ler a resposta

Retorna ok, notification_id e read_at. A leitura é registrada para o usuário autenticado; o conteúdo da notificação original permanece e as leituras de outros membros não são alteradas.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal. Não faça retry automático.
• 400 invalid_notification_id: o ID não é UUID válido.
• 404 notification_not_found: o serviço não conseguiu marcar uma notificação válida para esse membro/parceiro. O handler também usa esse erro quando a operação de leitura no banco falha.

Depois desta chamada

• Atualize read_at do item local e consulte unread novamente quando necessário.
• Se o aviso apontar para um alerta ainda aberto, investigue-o pela rota adequada; marcar leitura não reconhece nem resolve o alerta.

Regras desta operação

• Notificações são pessoais: o usuário autenticado determina os destinatários visíveis, as preferências e as confirmações de leitura. Uma automação com uma única sessão não atua por todos os membros.
• Silenciar uma categoria de notificação não desliga a integração Meta, o webhook, a cobrança nem o cálculo de risco/saúde.
• Não marque como lido antes de exibir o conteúdo apenas para esconder o contador.
• Leitura de notificação, reconhecimento de alerta e resolução de problema são três ações distintas.

Marcar em lote as notificações do membro como lidas.

Antes de começar

• O proprietário deve concluir o cadastro obrigatório CPF/CNPJ no Portal antes de acessar os recursos operacionais. O perfil do membro e suas permissões continuam sendo conferidos.
• Ter sessão do membro que pediu a ação.
• Esclarecer que a operação vai além da página atualmente exibida.

Autenticação e permissão

Exige access_token obtido no login de membro. A Partner API Key não é aceita nesta operação. Funções permitidas: owner, admin, developer, member, viewer.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/functions/v1/swift-worker?route=mark-all-partner-notifications-read

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Authorization": "Bearer ACCESS_TOKEN_DO_MEMBRO",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{}

O que preencher em cada campo

Esta operação não exige campos adicionais. A identidade do parceiro vem da autenticação.

Como ler a resposta

Retorna ok=true e marked, a quantidade de linhas processadas pela gravação em lote. A função usa upsert e pode incluir notificações já marcadas; marked não é necessariamente a quantidade que estava não lida antes da operação. Atua sobre notificações não expiradas do parceiro visíveis pelo destinatário (gerais ou destinadas ao membro), sem limitar à página corrente. A preferência de categoria da lista não funciona como limitador deste lote.

Erros e como agir

• 409 partner_registration_required: o proprietário precisa concluir seu cadastro pessoal ou empresarial no Portal. Não faça retry automático.
• 500 notification_mark_all_failed: falha ao marcar o conjunto de notificações.

Depois desta chamada

• Recarregue list-partner-notifications para obter unread e read_at atualizados.
• Mantenha os alertas operacionais abertos até sua própria triagem/resolução, mesmo após a leitura em lote.

Regras desta operação

• Notificações são pessoais: o usuário autenticado determina os destinatários visíveis, as preferências e as confirmações de leitura. Uma automação com uma única sessão não atua por todos os membros.
• Silenciar uma categoria de notificação não desliga a integração Meta, o webhook, a cobrança nem o cálculo de risco/saúde.
• Não use marked como contador de incidentes resolvidos.
• A ação não apaga notificações e não muda a leitura de outros membros.
• Não a execute automaticamente a cada login, pois isso elimina o sinal de avisos ainda não vistos.

Entrar como usuário já cadastrado no Partner e obter o JWT de membro usado nas operações que dependem da identidade e da função da pessoa.

Antes de começar

• Conta do Partner confirmada, convite aceito e senha definida.
• Esta etapa só é necessária para chamadas identificadas como JWT de membro. O cadastro de clientes e a conexão de números aceitam a Partner API Key.

Autenticação e permissão

Use seu e-mail e senha no JSON. O login devolve access_token para as rotas de membro. Não é necessário fazer login para cada chamada com Partner API Key.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://api.hookcloud.app/auth/v1/token?grant_type=password

{
  "apikey": "sb_publishable_vcEqaz4bqRNm3Oh7POfznA_SfWpNn5q",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "email": "SEU_EMAIL",
  "password": "SUA_SENHA"
}

O que preencher em cada campo

Como ler a resposta

O retorno contém access_token, token_type, expires_in/expires_at, refresh_token e user. Copie access_token para Authorization: Bearer SEU_ACCESS_TOKEN nas rotas de membro. Respeite a validade retornada. A função owner/admin/developer/viewer continua sendo a definida no Partner; o login não aumenta privilégios.

Erros e como agir

• Credenciais inválidas podem ser reportadas sem diferenciar usuário inexistente de senha incorreta; conferir o login sem presumir qual dado falhou.
• email_not_confirmed exige concluir a confirmação permitida pelo projeto.
• HTTP 429 indica limitação de autenticação; evitar repetição rápida.
• Login bem-sucedido seguido de 403 numa rota pode ser falta de vínculo ou função autorizada. Refazer o login não concede uma função superior.

Depois desta chamada

• Coloque access_token no header Authorization da rota de membro escolhida.
• Quando expirar, use o fluxo de autenticação do seu sistema para renovar a sessão. Estes exemplos não são um gerenciador de sessões.

Regras desta operação

• A resposta contém tokens sensíveis. Não compartilhe uma execução do seu sistema que inclua esses dados.
• Se a conta exigir MFA, conclua também o fluxo de autenticação apropriado.

Enviar uma mensagem de texto pelo número comercial selecionado para um usuário identificado por BSUID.

Referência oficial Meta: Envio de mensagens pela Cloud API · Identidade do destinatário e BSUID · Janela de atendimento e preços da Meta

Antes de começar

• Primeiro chame reveal-partner-instance-meta-token com sua Partner API Key e o escopo instances.credentials.read. A chave do Partner é usada somente no domínio HookCloud; o token revelado autentica a Graph.
• Concluir a conexão da instância e ter acesso aos ativos e permissões Meta exigidos pela operação. A existência do exemplo no catálogo não comprova elegibilidade nem aprovação de um recurso nessa WABA.
• Ter autorização para falar com o destinatário e um BSUID real recebido no webhook da mesma empresa. Mensagens livres dependem da janela de atendimento e das regras vigentes da Meta; não substituem templates exigidos fora dela.
• O token Meta precisa de whatsapp_business_messaging e acesso ao número/ativo usado. A chave da HookCloud não substitui essa permissão da Meta.

Autenticação e permissão

Envie o meta_access_token revelado para esta instância. A Partner API Key só autentica chamadas no domínio HookCloud; não a envie para a Meta.

O escopo instances.credentials.read permite buscar a credencial no Partner. A operação na Meta exige também as permissões e a elegibilidade do ativo descritas abaixo.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/messages

{
  "Authorization": "Bearer META_ACCESS_TOKEN_DA_INSTANCIA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "messaging_product": "whatsapp",
  "recipient": "BR.BSUID_RECEBIDO_NO_WEBHOOK",
  "type": "text",
  "text": {
    "body": "Olá, recebemos sua solicitação."
  }
}

O que preencher em cada campo

Como ler a resposta

Resposta ilustrativa de aceitação: {"messages":[{"id":"wamid.EXEMPLO"}]}. messages[].id é a referência da mensagem; guarde esse ID para correlacionar os status. contacts, quando presente, descreve a identidade reconhecida pela Meta. HTTP 2xx confirma a aceitação da chamada; sent, delivered, read ou failed vêm do webhook e não são garantidos pela resposta inicial.

Erros e como agir

• Antes da Graph: falha ao revelar token, chave sem instances.credentials.read ou ID configurado divergente da instância. Corrigir a credencial/seleção; não trocar por um token de outro cliente.
• Na Graph: consultar resposta.error.code, error_subcode, error_data.details e fbtrace_id. Token inválido/expirado, ativo não autorizado e parâmetro incorreto são classes distintas; o HTTP status sozinho não identifica a causa.
• Aceitação HTTP não encerra a análise: falhas de janela, destinatário, política, qualidade ou limite podem aparecer no webhook. Correlacionar pelo wamid e tratar o motivo concreto antes de repetir; uma nova execução pode criar outra mensagem.

Depois desta chamada

• Guardar o message_id retornado e correlacionar os eventos do webhook. report-partner-message-status apenas registra o status no Partner; não envia a mensagem novamente.

Regras desta operação

• recipient recebe o BSUID opaco, por exemplo BR.BSUID_REAL, vindo de contacts[].user_id, messages[].from_user_id ou statuses[].recipient_user_id. Preservar prefixo, letras e maiúsculas. user_id é campo de identidade no webhook, não o nome do campo de envio. Não usar username nem PHONE_NUMBER_ID como destinatário; não acrescentar to ao exemplo BSUID, pois a Meta prioriza to quando ambos estão presentes. Parent BSUID não deve ser assumido disponível; exige habilitação própria.
• Partner API Key autentica somente a HookCloud. A Graph recebe somente o Meta Access Token da instância; nunca envie a chave Partner à Meta nem exponha o token no navegador.
• Texto livre depende de uma mensagem recebida e autenticada do usuário nas últimas 24 horas para esse número e geração da conexão. Criar um contato, importar cliente, enviar um template, receber sent/delivered/read ou identificar FEP não reinicia essa janela. Fora dela, use template aprovado e autorização adequada do destinatário.
• FEP é benefício de cobrança, separado da permissão de conteúdo. Mostre sua expiração somente com evidência Meta pertinente, como conversation.origin.type=referral_conversion, expiration_timestamp e pricing compatível; ausência desses campos significa não confirmado. Não deduza uma janela fixa da existência de um anúncio nem estenda texto livre para o prazo FEP. Confira a política oficial vigente para elegibilidade e duração.
• Para telefone conhecido e autorizado, substitua recipient por to com DDI e dígitos. Não envie user_id no body Graph como se fosse campo de envio. BSUID usa recipient, preserva o identificador opaco e seu contexto de portfólio; username reservado não identifica o destinatário.
• HTTP 2xx/um wamid confirma aceitação, não entrega. Persista o pedido antes de chamar a Meta e deduplique sua fila. Timeout ou resposta ilegível após POST deve ficar incerto e ser reconciliado com webhook/histórico; não faça reenvio automático cego. Idempotency-Key do Partner não oferece idempotência para POSTs Graph.

Enviar uma tradução aprovada de um template da WABA, informando nome, idioma e, quando necessário, os valores dos parâmetros.

Referência oficial Meta: Envio de mensagens pela Cloud API · Identidade do destinatário e BSUID · Janela de atendimento e preços da Meta

Antes de começar

• Primeiro chame reveal-partner-instance-meta-token com sua Partner API Key e o escopo instances.credentials.read. A chave do Partner é usada somente no domínio HookCloud; o token revelado autentica a Graph.
• Concluir a conexão da instância e ter acesso aos ativos e permissões Meta exigidos pela operação. A existência do exemplo no catálogo não comprova elegibilidade nem aprovação de um recurso nessa WABA.
• Template da WABA em condição de envio e tradução correta. APPROVED não elimina regras de qualidade, categoria, destinatário e política; consultar o status atual.
• O token Meta precisa de whatsapp_business_messaging e acesso ao número/ativo usado. A chave da HookCloud não substitui essa permissão da Meta.

Autenticação e permissão

Envie o meta_access_token revelado para esta instância. A Partner API Key só autentica chamadas no domínio HookCloud; não a envie para a Meta.

O escopo instances.credentials.read permite buscar a credencial no Partner. A operação na Meta exige também as permissões e a elegibilidade do ativo descritas abaixo.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/messages

{
  "Authorization": "Bearer META_ACCESS_TOKEN_DA_INSTANCIA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "messaging_product": "whatsapp",
  "recipient": "BR.BSUID_RECEBIDO_NO_WEBHOOK",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "TEMPLATE_LANGUAGE"
    }
  }
}

O que preencher em cada campo

Como ler a resposta

Resposta ilustrativa de aceitação: {"messages":[{"id":"wamid.EXEMPLO"}]}. messages[].id é a referência da mensagem; guarde esse ID para correlacionar os status. contacts, quando presente, descreve a identidade reconhecida pela Meta. HTTP 2xx confirma a aceitação da chamada; sent, delivered, read ou failed vêm do webhook e não são garantidos pela resposta inicial.

Erros e como agir

• Antes da Graph: falha ao revelar token, chave sem instances.credentials.read ou ID configurado divergente da instância. Corrigir a credencial/seleção; não trocar por um token de outro cliente.
• Na Graph: consultar resposta.error.code, error_subcode, error_data.details e fbtrace_id. Token inválido/expirado, ativo não autorizado e parâmetro incorreto são classes distintas; o HTTP status sozinho não identifica a causa.
• Aceitação HTTP não encerra a análise: falhas de janela, destinatário, política, qualidade ou limite podem aparecer no webhook. Correlacionar pelo wamid e tratar o motivo concreto antes de repetir; uma nova execução pode criar outra mensagem.
• Nome/idioma ausente na WABA, template pausado/desabilitado e parâmetros incompatíveis exigem correções diferentes. A documentação atual informa erro 132018 para problemas de parâmetros de componentes no envio a partir da Graph v23.
• Templates de autenticação que dependem do telefone têm restrições com BSUID; não supor que one-tap, zero-tap ou copy-code aceitem este exemplo sem conferir a modalidade elegível.

Depois desta chamada

• Usar meta-list-templates/meta-get-template para confirmar nome, idioma, status e components. Guardar o wamid e acompanhar o webhook após o envio.
• Prefira list-partner-meta-templates/get-partner-meta-template para ler o cache. Atualize via eventos hookcloud.meta.template.updated e refresh-partner-meta-templates respeitando o cooldown; use GET Graph pontual quando realmente necessário.

Regras desta operação

• recipient recebe o BSUID opaco, por exemplo BR.BSUID_REAL, vindo de contacts[].user_id, messages[].from_user_id ou statuses[].recipient_user_id. Preservar prefixo, letras e maiúsculas. user_id é campo de identidade no webhook, não o nome do campo de envio. Não usar username nem PHONE_NUMBER_ID como destinatário; não acrescentar to ao exemplo BSUID, pois a Meta prioriza to quando ambos estão presentes. Parent BSUID não deve ser assumido disponível; exige habilitação própria.
• Partner API Key autentica somente a HookCloud. A Graph recebe somente o Meta Access Token da instância; nunca envie a chave Partner à Meta nem exponha o token no navegador.
• Texto livre depende de uma mensagem recebida e autenticada do usuário nas últimas 24 horas para esse número e geração da conexão. Criar um contato, importar cliente, enviar um template, receber sent/delivered/read ou identificar FEP não reinicia essa janela. Fora dela, use template aprovado e autorização adequada do destinatário.
• FEP é benefício de cobrança, separado da permissão de conteúdo. Mostre sua expiração somente com evidência Meta pertinente, como conversation.origin.type=referral_conversion, expiration_timestamp e pricing compatível; ausência desses campos significa não confirmado. Não deduza uma janela fixa da existência de um anúncio nem estenda texto livre para o prazo FEP. Confira a política oficial vigente para elegibilidade e duração.
• Para telefone conhecido e autorizado, substitua recipient por to com DDI e dígitos. Não envie user_id no body Graph como se fosse campo de envio. BSUID usa recipient, preserva o identificador opaco e seu contexto de portfólio; username reservado não identifica o destinatário.
• HTTP 2xx/um wamid confirma aceitação, não entrega. Persista o pedido antes de chamar a Meta e deduplique sua fila. Timeout ou resposta ilegível após POST deve ficar incerto e ser reconciliado com webhook/histórico; não faça reenvio automático cego. Idempotency-Key do Partner não oferece idempotência para POSTs Graph.

Enviar imagem previamente carregado na Meta para o BSUID selecionado.

Referência oficial Meta: Envio de mensagens pela Cloud API · Identidade do destinatário e BSUID · Janela de atendimento e preços da Meta

Antes de começar

• Primeiro chame reveal-partner-instance-meta-token com sua Partner API Key e o escopo instances.credentials.read. A chave do Partner é usada somente no domínio HookCloud; o token revelado autentica a Graph.
• Concluir a conexão da instância e ter acesso aos ativos e permissões Meta exigidos pela operação. A existência do exemplo no catálogo não comprova elegibilidade nem aprovação de um recurso nessa WABA.
• Ter autorização para falar com o destinatário e um BSUID real recebido no webhook da mesma empresa. Mensagens livres dependem da janela de atendimento e das regras vigentes da Meta; não substituem templates exigidos fora dela.
• Arquivo disponível na Meta com tipo compatível: image/png ou image/jpeg, até 5 MB.
• O token Meta precisa de whatsapp_business_messaging e acesso ao número/ativo usado. A chave da HookCloud não substitui essa permissão da Meta.

Autenticação e permissão

Envie o meta_access_token revelado para esta instância. A Partner API Key só autentica chamadas no domínio HookCloud; não a envie para a Meta.

O escopo instances.credentials.read permite buscar a credencial no Partner. A operação na Meta exige também as permissões e a elegibilidade do ativo descritas abaixo.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/messages

{
  "Authorization": "Bearer META_ACCESS_TOKEN_DA_INSTANCIA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "messaging_product": "whatsapp",
  "recipient": "BR.BSUID_RECEBIDO_NO_WEBHOOK",
  "type": "image",
  "image": {
    "id": "MEDIA_ID"
  }
}

O que preencher em cada campo

Como ler a resposta

Resposta ilustrativa de aceitação: {"messages":[{"id":"wamid.EXEMPLO"}]}. messages[].id é a referência da mensagem; guarde esse ID para correlacionar os status. contacts, quando presente, descreve a identidade reconhecida pela Meta. HTTP 2xx confirma a aceitação da chamada; sent, delivered, read ou failed vêm do webhook e não são garantidos pela resposta inicial.

Erros e como agir

• Antes da Graph: falha ao revelar token, chave sem instances.credentials.read ou ID configurado divergente da instância. Corrigir a credencial/seleção; não trocar por um token de outro cliente.
• Na Graph: consultar resposta.error.code, error_subcode, error_data.details e fbtrace_id. Token inválido/expirado, ativo não autorizado e parâmetro incorreto são classes distintas; o HTTP status sozinho não identifica a causa.
• Aceitação HTTP não encerra a análise: falhas de janela, destinatário, política, qualidade ou limite podem aparecer no webhook. Correlacionar pelo wamid e tratar o motivo concreto antes de repetir; uma nova execução pode criar outra mensagem.

Depois desta chamada

• Guardar o message_id retornado e correlacionar os eventos do webhook. report-partner-message-status apenas registra o status no Partner; não envia a mensagem novamente.

Regras desta operação

• recipient recebe o BSUID opaco, por exemplo BR.BSUID_REAL, vindo de contacts[].user_id, messages[].from_user_id ou statuses[].recipient_user_id. Preservar prefixo, letras e maiúsculas. user_id é campo de identidade no webhook, não o nome do campo de envio. Não usar username nem PHONE_NUMBER_ID como destinatário; não acrescentar to ao exemplo BSUID, pois a Meta prioriza to quando ambos estão presentes. Parent BSUID não deve ser assumido disponível; exige habilitação própria.
• Imagem JPEG/PNG válida. Um documento PDF não vira imagem apenas por alterar o MIME.
• Um ID inexistente, removido ou não acessível ao token falha mesmo que o formato do JSON esteja correto. O fluxo não faz upload automaticamente nesta operação; use meta-upload-media antes.
• Partner API Key autentica somente a HookCloud. A Graph recebe somente o Meta Access Token da instância; nunca envie a chave Partner à Meta nem exponha o token no navegador.
• Texto livre depende de uma mensagem recebida e autenticada do usuário nas últimas 24 horas para esse número e geração da conexão. Criar um contato, importar cliente, enviar um template, receber sent/delivered/read ou identificar FEP não reinicia essa janela. Fora dela, use template aprovado e autorização adequada do destinatário.
• FEP é benefício de cobrança, separado da permissão de conteúdo. Mostre sua expiração somente com evidência Meta pertinente, como conversation.origin.type=referral_conversion, expiration_timestamp e pricing compatível; ausência desses campos significa não confirmado. Não deduza uma janela fixa da existência de um anúncio nem estenda texto livre para o prazo FEP. Confira a política oficial vigente para elegibilidade e duração.
• Para telefone conhecido e autorizado, substitua recipient por to com DDI e dígitos. Não envie user_id no body Graph como se fosse campo de envio. BSUID usa recipient, preserva o identificador opaco e seu contexto de portfólio; username reservado não identifica o destinatário.
• HTTP 2xx/um wamid confirma aceitação, não entrega. Persista o pedido antes de chamar a Meta e deduplique sua fila. Timeout ou resposta ilegível após POST deve ficar incerto e ser reconciliado com webhook/histórico; não faça reenvio automático cego. Idempotency-Key do Partner não oferece idempotência para POSTs Graph.

Enviar documento previamente carregado na Meta para o BSUID selecionado.

Referência oficial Meta: Envio de mensagens pela Cloud API · Identidade do destinatário e BSUID · Janela de atendimento e preços da Meta

Antes de começar

• Primeiro chame reveal-partner-instance-meta-token com sua Partner API Key e o escopo instances.credentials.read. A chave do Partner é usada somente no domínio HookCloud; o token revelado autentica a Graph.
• Concluir a conexão da instância e ter acesso aos ativos e permissões Meta exigidos pela operação. A existência do exemplo no catálogo não comprova elegibilidade nem aprovação de um recurso nessa WABA.
• Ter autorização para falar com o destinatário e um BSUID real recebido no webhook da mesma empresa. Mensagens livres dependem da janela de atendimento e das regras vigentes da Meta; não substituem templates exigidos fora dela.
• Arquivo disponível na Meta com tipo compatível: formatos de documento suportados, por exemplo application/pdf, até 100 MB.
• O token Meta precisa de whatsapp_business_messaging e acesso ao número/ativo usado. A chave da HookCloud não substitui essa permissão da Meta.

Autenticação e permissão

Envie o meta_access_token revelado para esta instância. A Partner API Key só autentica chamadas no domínio HookCloud; não a envie para a Meta.

O escopo instances.credentials.read permite buscar a credencial no Partner. A operação na Meta exige também as permissões e a elegibilidade do ativo descritas abaixo.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/messages

{
  "Authorization": "Bearer META_ACCESS_TOKEN_DA_INSTANCIA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "messaging_product": "whatsapp",
  "recipient": "BR.BSUID_RECEBIDO_NO_WEBHOOK",
  "type": "document",
  "document": {
    "id": "MEDIA_ID"
  }
}

O que preencher em cada campo

Como ler a resposta

Resposta ilustrativa de aceitação: {"messages":[{"id":"wamid.EXEMPLO"}]}. messages[].id é a referência da mensagem; guarde esse ID para correlacionar os status. contacts, quando presente, descreve a identidade reconhecida pela Meta. HTTP 2xx confirma a aceitação da chamada; sent, delivered, read ou failed vêm do webhook e não são garantidos pela resposta inicial.

Erros e como agir

• Antes da Graph: falha ao revelar token, chave sem instances.credentials.read ou ID configurado divergente da instância. Corrigir a credencial/seleção; não trocar por um token de outro cliente.
• Na Graph: consultar resposta.error.code, error_subcode, error_data.details e fbtrace_id. Token inválido/expirado, ativo não autorizado e parâmetro incorreto são classes distintas; o HTTP status sozinho não identifica a causa.
• Aceitação HTTP não encerra a análise: falhas de janela, destinatário, política, qualidade ou limite podem aparecer no webhook. Correlacionar pelo wamid e tratar o motivo concreto antes de repetir; uma nova execução pode criar outra mensagem.

Depois desta chamada

• Guardar o message_id retornado e correlacionar os eventos do webhook. report-partner-message-status apenas registra o status no Partner; não envia a mensagem novamente.

Regras desta operação

• recipient recebe o BSUID opaco, por exemplo BR.BSUID_REAL, vindo de contacts[].user_id, messages[].from_user_id ou statuses[].recipient_user_id. Preservar prefixo, letras e maiúsculas. user_id é campo de identidade no webhook, não o nome do campo de envio. Não usar username nem PHONE_NUMBER_ID como destinatário; não acrescentar to ao exemplo BSUID, pois a Meta prioriza to quando ambos estão presentes. Parent BSUID não deve ser assumido disponível; exige habilitação própria.
• Usar um formato listado pela Meta. Um arquivo HTML de uma página de download não é o documento pretendido.
• Um ID inexistente, removido ou não acessível ao token falha mesmo que o formato do JSON esteja correto. O fluxo não faz upload automaticamente nesta operação; use meta-upload-media antes.
• Partner API Key autentica somente a HookCloud. A Graph recebe somente o Meta Access Token da instância; nunca envie a chave Partner à Meta nem exponha o token no navegador.
• Texto livre depende de uma mensagem recebida e autenticada do usuário nas últimas 24 horas para esse número e geração da conexão. Criar um contato, importar cliente, enviar um template, receber sent/delivered/read ou identificar FEP não reinicia essa janela. Fora dela, use template aprovado e autorização adequada do destinatário.
• FEP é benefício de cobrança, separado da permissão de conteúdo. Mostre sua expiração somente com evidência Meta pertinente, como conversation.origin.type=referral_conversion, expiration_timestamp e pricing compatível; ausência desses campos significa não confirmado. Não deduza uma janela fixa da existência de um anúncio nem estenda texto livre para o prazo FEP. Confira a política oficial vigente para elegibilidade e duração.
• Para telefone conhecido e autorizado, substitua recipient por to com DDI e dígitos. Não envie user_id no body Graph como se fosse campo de envio. BSUID usa recipient, preserva o identificador opaco e seu contexto de portfólio; username reservado não identifica o destinatário.
• HTTP 2xx/um wamid confirma aceitação, não entrega. Persista o pedido antes de chamar a Meta e deduplique sua fila. Timeout ou resposta ilegível após POST deve ficar incerto e ser reconciliado com webhook/histórico; não faça reenvio automático cego. Idempotency-Key do Partner não oferece idempotência para POSTs Graph.

Enviar áudio previamente carregado na Meta para o BSUID selecionado.

Referência oficial Meta: Envio de mensagens pela Cloud API · Identidade do destinatário e BSUID · Janela de atendimento e preços da Meta

Antes de começar

• Primeiro chame reveal-partner-instance-meta-token com sua Partner API Key e o escopo instances.credentials.read. A chave do Partner é usada somente no domínio HookCloud; o token revelado autentica a Graph.
• Concluir a conexão da instância e ter acesso aos ativos e permissões Meta exigidos pela operação. A existência do exemplo no catálogo não comprova elegibilidade nem aprovação de um recurso nessa WABA.
• Ter autorização para falar com o destinatário e um BSUID real recebido no webhook da mesma empresa. Mensagens livres dependem da janela de atendimento e das regras vigentes da Meta; não substituem templates exigidos fora dela.
• Arquivo disponível na Meta com tipo compatível: audio/aac, audio/mp4, audio/mpeg, audio/amr ou audio/ogg, até 16 MB.
• O token Meta precisa de whatsapp_business_messaging e acesso ao número/ativo usado. A chave da HookCloud não substitui essa permissão da Meta.

Autenticação e permissão

Envie o meta_access_token revelado para esta instância. A Partner API Key só autentica chamadas no domínio HookCloud; não a envie para a Meta.

O escopo instances.credentials.read permite buscar a credencial no Partner. A operação na Meta exige também as permissões e a elegibilidade do ativo descritas abaixo.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/messages

{
  "Authorization": "Bearer META_ACCESS_TOKEN_DA_INSTANCIA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "messaging_product": "whatsapp",
  "recipient": "BR.BSUID_RECEBIDO_NO_WEBHOOK",
  "type": "audio",
  "audio": {
    "id": "MEDIA_ID"
  }
}

O que preencher em cada campo

Como ler a resposta

Resposta ilustrativa de aceitação: {"messages":[{"id":"wamid.EXEMPLO"}]}. messages[].id é a referência da mensagem; guarde esse ID para correlacionar os status. contacts, quando presente, descreve a identidade reconhecida pela Meta. HTTP 2xx confirma a aceitação da chamada; sent, delivered, read ou failed vêm do webhook e não são garantidos pela resposta inicial.

Erros e como agir

• Antes da Graph: falha ao revelar token, chave sem instances.credentials.read ou ID configurado divergente da instância. Corrigir a credencial/seleção; não trocar por um token de outro cliente.
• Na Graph: consultar resposta.error.code, error_subcode, error_data.details e fbtrace_id. Token inválido/expirado, ativo não autorizado e parâmetro incorreto são classes distintas; o HTTP status sozinho não identifica a causa.
• Aceitação HTTP não encerra a análise: falhas de janela, destinatário, política, qualidade ou limite podem aparecer no webhook. Correlacionar pelo wamid e tratar o motivo concreto antes de repetir; uma nova execução pode criar outra mensagem.

Depois desta chamada

• Guardar o message_id retornado e correlacionar os eventos do webhook. report-partner-message-status apenas registra o status no Partner; não envia a mensagem novamente.

Regras desta operação

• recipient recebe o BSUID opaco, por exemplo BR.BSUID_REAL, vindo de contacts[].user_id, messages[].from_user_id ou statuses[].recipient_user_id. Preservar prefixo, letras e maiúsculas. user_id é campo de identidade no webhook, não o nome do campo de envio. Não usar username nem PHONE_NUMBER_ID como destinatário; não acrescentar to ao exemplo BSUID, pois a Meta prioriza to quando ambos estão presentes. Parent BSUID não deve ser assumido disponível; exige habilitação própria.
• OGG precisa usar codec Opus; conferir a codificação real. Este exemplo envia áudio comum, sem ativar recursos opcionais de mensagem de voz.
• Um ID inexistente, removido ou não acessível ao token falha mesmo que o formato do JSON esteja correto. O fluxo não faz upload automaticamente nesta operação; use meta-upload-media antes.
• Partner API Key autentica somente a HookCloud. A Graph recebe somente o Meta Access Token da instância; nunca envie a chave Partner à Meta nem exponha o token no navegador.
• Texto livre depende de uma mensagem recebida e autenticada do usuário nas últimas 24 horas para esse número e geração da conexão. Criar um contato, importar cliente, enviar um template, receber sent/delivered/read ou identificar FEP não reinicia essa janela. Fora dela, use template aprovado e autorização adequada do destinatário.
• FEP é benefício de cobrança, separado da permissão de conteúdo. Mostre sua expiração somente com evidência Meta pertinente, como conversation.origin.type=referral_conversion, expiration_timestamp e pricing compatível; ausência desses campos significa não confirmado. Não deduza uma janela fixa da existência de um anúncio nem estenda texto livre para o prazo FEP. Confira a política oficial vigente para elegibilidade e duração.
• Para telefone conhecido e autorizado, substitua recipient por to com DDI e dígitos. Não envie user_id no body Graph como se fosse campo de envio. BSUID usa recipient, preserva o identificador opaco e seu contexto de portfólio; username reservado não identifica o destinatário.
• HTTP 2xx/um wamid confirma aceitação, não entrega. Persista o pedido antes de chamar a Meta e deduplique sua fila. Timeout ou resposta ilegível após POST deve ficar incerto e ser reconciliado com webhook/histórico; não faça reenvio automático cego. Idempotency-Key do Partner não oferece idempotência para POSTs Graph.

Enviar vídeo previamente carregado na Meta para o BSUID selecionado.

Referência oficial Meta: Envio de mensagens pela Cloud API · Identidade do destinatário e BSUID · Janela de atendimento e preços da Meta

Antes de começar

• Primeiro chame reveal-partner-instance-meta-token com sua Partner API Key e o escopo instances.credentials.read. A chave do Partner é usada somente no domínio HookCloud; o token revelado autentica a Graph.
• Concluir a conexão da instância e ter acesso aos ativos e permissões Meta exigidos pela operação. A existência do exemplo no catálogo não comprova elegibilidade nem aprovação de um recurso nessa WABA.
• Ter autorização para falar com o destinatário e um BSUID real recebido no webhook da mesma empresa. Mensagens livres dependem da janela de atendimento e das regras vigentes da Meta; não substituem templates exigidos fora dela.
• Arquivo disponível na Meta com tipo compatível: video/mp4 ou video/3gpp, até 16 MB.
• O token Meta precisa de whatsapp_business_messaging e acesso ao número/ativo usado. A chave da HookCloud não substitui essa permissão da Meta.

Autenticação e permissão

Envie o meta_access_token revelado para esta instância. A Partner API Key só autentica chamadas no domínio HookCloud; não a envie para a Meta.

O escopo instances.credentials.read permite buscar a credencial no Partner. A operação na Meta exige também as permissões e a elegibilidade do ativo descritas abaixo.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/messages

{
  "Authorization": "Bearer META_ACCESS_TOKEN_DA_INSTANCIA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "messaging_product": "whatsapp",
  "recipient": "BR.BSUID_RECEBIDO_NO_WEBHOOK",
  "type": "video",
  "video": {
    "id": "MEDIA_ID"
  }
}

O que preencher em cada campo

Como ler a resposta

Resposta ilustrativa de aceitação: {"messages":[{"id":"wamid.EXEMPLO"}]}. messages[].id é a referência da mensagem; guarde esse ID para correlacionar os status. contacts, quando presente, descreve a identidade reconhecida pela Meta. HTTP 2xx confirma a aceitação da chamada; sent, delivered, read ou failed vêm do webhook e não são garantidos pela resposta inicial.

Erros e como agir

• Antes da Graph: falha ao revelar token, chave sem instances.credentials.read ou ID configurado divergente da instância. Corrigir a credencial/seleção; não trocar por um token de outro cliente.
• Na Graph: consultar resposta.error.code, error_subcode, error_data.details e fbtrace_id. Token inválido/expirado, ativo não autorizado e parâmetro incorreto são classes distintas; o HTTP status sozinho não identifica a causa.
• Aceitação HTTP não encerra a análise: falhas de janela, destinatário, política, qualidade ou limite podem aparecer no webhook. Correlacionar pelo wamid e tratar o motivo concreto antes de repetir; uma nova execução pode criar outra mensagem.

Depois desta chamada

• Guardar o message_id retornado e correlacionar os eventos do webhook. report-partner-message-status apenas registra o status no Partner; não envia a mensagem novamente.

Regras desta operação

• recipient recebe o BSUID opaco, por exemplo BR.BSUID_REAL, vindo de contacts[].user_id, messages[].from_user_id ou statuses[].recipient_user_id. Preservar prefixo, letras e maiúsculas. user_id é campo de identidade no webhook, não o nome do campo de envio. Não usar username nem PHONE_NUMBER_ID como destinatário; não acrescentar to ao exemplo BSUID, pois a Meta prioriza to quando ambos estão presentes. Parent BSUID não deve ser assumido disponível; exige habilitação própria.
• A Meta aceita vídeo H.264 com áudio AAC, uma única faixa de áudio ou sem áudio. A extensão sozinha não garante compatibilidade; conferir os codecs reais do arquivo.
• Um ID inexistente, removido ou não acessível ao token falha mesmo que o formato do JSON esteja correto. O fluxo não faz upload automaticamente nesta operação; use meta-upload-media antes.
• Partner API Key autentica somente a HookCloud. A Graph recebe somente o Meta Access Token da instância; nunca envie a chave Partner à Meta nem exponha o token no navegador.
• Texto livre depende de uma mensagem recebida e autenticada do usuário nas últimas 24 horas para esse número e geração da conexão. Criar um contato, importar cliente, enviar um template, receber sent/delivered/read ou identificar FEP não reinicia essa janela. Fora dela, use template aprovado e autorização adequada do destinatário.
• FEP é benefício de cobrança, separado da permissão de conteúdo. Mostre sua expiração somente com evidência Meta pertinente, como conversation.origin.type=referral_conversion, expiration_timestamp e pricing compatível; ausência desses campos significa não confirmado. Não deduza uma janela fixa da existência de um anúncio nem estenda texto livre para o prazo FEP. Confira a política oficial vigente para elegibilidade e duração.
• Para telefone conhecido e autorizado, substitua recipient por to com DDI e dígitos. Não envie user_id no body Graph como se fosse campo de envio. BSUID usa recipient, preserva o identificador opaco e seu contexto de portfólio; username reservado não identifica o destinatário.
• HTTP 2xx/um wamid confirma aceitação, não entrega. Persista o pedido antes de chamar a Meta e deduplique sua fila. Timeout ou resposta ilegível após POST deve ficar incerto e ser reconciliado com webhook/histórico; não faça reenvio automático cego. Idempotency-Key do Partner não oferece idempotência para POSTs Graph.

Enviar sticker previamente carregado na Meta para o BSUID selecionado.

Referência oficial Meta: Envio de mensagens pela Cloud API · Identidade do destinatário e BSUID · Janela de atendimento e preços da Meta

Antes de começar

• Primeiro chame reveal-partner-instance-meta-token com sua Partner API Key e o escopo instances.credentials.read. A chave do Partner é usada somente no domínio HookCloud; o token revelado autentica a Graph.
• Concluir a conexão da instância e ter acesso aos ativos e permissões Meta exigidos pela operação. A existência do exemplo no catálogo não comprova elegibilidade nem aprovação de um recurso nessa WABA.
• Ter autorização para falar com o destinatário e um BSUID real recebido no webhook da mesma empresa. Mensagens livres dependem da janela de atendimento e das regras vigentes da Meta; não substituem templates exigidos fora dela.
• Arquivo disponível na Meta com tipo compatível: image/webp: até 100 KB estático ou 500 KB animado.
• O token Meta precisa de whatsapp_business_messaging e acesso ao número/ativo usado. A chave da HookCloud não substitui essa permissão da Meta.

Autenticação e permissão

Envie o meta_access_token revelado para esta instância. A Partner API Key só autentica chamadas no domínio HookCloud; não a envie para a Meta.

O escopo instances.credentials.read permite buscar a credencial no Partner. A operação na Meta exige também as permissões e a elegibilidade do ativo descritas abaixo.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/messages

{
  "Authorization": "Bearer META_ACCESS_TOKEN_DA_INSTANCIA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "messaging_product": "whatsapp",
  "recipient": "BR.BSUID_RECEBIDO_NO_WEBHOOK",
  "type": "sticker",
  "sticker": {
    "id": "MEDIA_ID"
  }
}

O que preencher em cada campo

Como ler a resposta

Resposta ilustrativa de aceitação: {"messages":[{"id":"wamid.EXEMPLO"}]}. messages[].id é a referência da mensagem; guarde esse ID para correlacionar os status. contacts, quando presente, descreve a identidade reconhecida pela Meta. HTTP 2xx confirma a aceitação da chamada; sent, delivered, read ou failed vêm do webhook e não são garantidos pela resposta inicial.

Erros e como agir

• Antes da Graph: falha ao revelar token, chave sem instances.credentials.read ou ID configurado divergente da instância. Corrigir a credencial/seleção; não trocar por um token de outro cliente.
• Na Graph: consultar resposta.error.code, error_subcode, error_data.details e fbtrace_id. Token inválido/expirado, ativo não autorizado e parâmetro incorreto são classes distintas; o HTTP status sozinho não identifica a causa.
• Aceitação HTTP não encerra a análise: falhas de janela, destinatário, política, qualidade ou limite podem aparecer no webhook. Correlacionar pelo wamid e tratar o motivo concreto antes de repetir; uma nova execução pode criar outra mensagem.

Depois desta chamada

• Guardar o message_id retornado e correlacionar os eventos do webhook. report-partner-message-status apenas registra o status no Partner; não envia a mensagem novamente.

Regras desta operação

• recipient recebe o BSUID opaco, por exemplo BR.BSUID_REAL, vindo de contacts[].user_id, messages[].from_user_id ou statuses[].recipient_user_id. Preservar prefixo, letras e maiúsculas. user_id é campo de identidade no webhook, não o nome do campo de envio. Não usar username nem PHONE_NUMBER_ID como destinatário; não acrescentar to ao exemplo BSUID, pois a Meta prioriza to quando ambos estão presentes. Parent BSUID não deve ser assumido disponível; exige habilitação própria.
• Usar sticker WebP compatível com as dimensões e características exigidas pela Meta; uma imagem PNG comum não corresponde a este tipo.
• Um ID inexistente, removido ou não acessível ao token falha mesmo que o formato do JSON esteja correto. O fluxo não faz upload automaticamente nesta operação; use meta-upload-media antes.
• Partner API Key autentica somente a HookCloud. A Graph recebe somente o Meta Access Token da instância; nunca envie a chave Partner à Meta nem exponha o token no navegador.
• Texto livre depende de uma mensagem recebida e autenticada do usuário nas últimas 24 horas para esse número e geração da conexão. Criar um contato, importar cliente, enviar um template, receber sent/delivered/read ou identificar FEP não reinicia essa janela. Fora dela, use template aprovado e autorização adequada do destinatário.
• FEP é benefício de cobrança, separado da permissão de conteúdo. Mostre sua expiração somente com evidência Meta pertinente, como conversation.origin.type=referral_conversion, expiration_timestamp e pricing compatível; ausência desses campos significa não confirmado. Não deduza uma janela fixa da existência de um anúncio nem estenda texto livre para o prazo FEP. Confira a política oficial vigente para elegibilidade e duração.
• Para telefone conhecido e autorizado, substitua recipient por to com DDI e dígitos. Não envie user_id no body Graph como se fosse campo de envio. BSUID usa recipient, preserva o identificador opaco e seu contexto de portfólio; username reservado não identifica o destinatário.
• HTTP 2xx/um wamid confirma aceitação, não entrega. Persista o pedido antes de chamar a Meta e deduplique sua fila. Timeout ou resposta ilegível após POST deve ficar incerto e ser reconciliado com webhook/histórico; não faça reenvio automático cego. Idempotency-Key do Partner não oferece idempotência para POSTs Graph.

Enviar uma localização estática com coordenadas geográficas e um nome opcional.

Referência oficial Meta: Envio de mensagens pela Cloud API · Identidade do destinatário e BSUID · Janela de atendimento e preços da Meta

Antes de começar

• Primeiro chame reveal-partner-instance-meta-token com sua Partner API Key e o escopo instances.credentials.read. A chave do Partner é usada somente no domínio HookCloud; o token revelado autentica a Graph.
• Concluir a conexão da instância e ter acesso aos ativos e permissões Meta exigidos pela operação. A existência do exemplo no catálogo não comprova elegibilidade nem aprovação de um recurso nessa WABA.
• Ter autorização para falar com o destinatário e um BSUID real recebido no webhook da mesma empresa. Mensagens livres dependem da janela de atendimento e das regras vigentes da Meta; não substituem templates exigidos fora dela.
• O token Meta precisa de whatsapp_business_messaging e acesso ao número/ativo usado. A chave da HookCloud não substitui essa permissão da Meta.

Autenticação e permissão

Envie o meta_access_token revelado para esta instância. A Partner API Key só autentica chamadas no domínio HookCloud; não a envie para a Meta.

O escopo instances.credentials.read permite buscar a credencial no Partner. A operação na Meta exige também as permissões e a elegibilidade do ativo descritas abaixo.

Configure a chamada HTTP

No backend do seu sistema, use o método POST com a URL e os headers abaixo. Substitua os marcadores pelos dados reais; não envie credenciais pelo navegador do cliente final.

https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/messages

{
  "Authorization": "Bearer META_ACCESS_TOKEN_DA_INSTANCIA",
  "Content-Type": "application/json"
}

Envie o corpo em JSON e substitua os exemplos pelos seus dados. A rota já está na URL; não é necessário repeti-la no JSON.

{
  "messaging_product": "whatsapp",
  "recipient": "BR.BSUID_RECEBIDO_NO_WEBHOOK",
  "type": "location",
  "location": {
    "latitude": -22.9,
    "longitude": -43.17,
    "name": "Local de teste"
  }
}

O que preencher em cada campo