A API do Noz deixa bots, agentes de IA e a sua plataforma fazerem tudo o que a tela faz: ver a saúde de números, WABAs e BMs, vincular número novo numa BM, criar, editar e vincular templates, disparar campanhas e receber cada evento por webhook.
72endpoints
23novos para automação
JSONREST + MCP
o que precisa de mim agora?
# retrato da conta, do pior para o melhorcurl https://hml.prismkg.com/api/v1/overview \
-H "Authorization: Bearer $NOZ_TOKEN"
{ "data": {
"numbers": { "total": 12, "good": 9, "bad": 1 },
"needs_action": [{
"type": "number", "name": "Vendas 3",
"label": "Qualidade baixa", "code": "qualidade_red",
"next_action": "Parar 7 dias, só responder"
}]
} }
Nenhum endpoint com “”.
Autenticação
Gere um token em Configurações → API e MCP. Ele vale para a conta (empresa) em que foi criado: tudo o que a API devolve e muda fica dentro dessa conta. Envie em todas as chamadas, menos /api/v1/health. O valor aparece uma vez só; o Noz guarda apenas o hash.
Corpo em JSON com Content-Type: application/json; a resposta também é JSON.
3
Auditoria
Toda escrita feita pela API entra na Auditoria da conta, com o nome do token.
Respostas e erros
Sucesso vem em data. Erro vem com message em português, pronto para o bot repetir a quem opera, e às vezes com detalhes (missing, invalid_channels, problems).
Status
Quando
200 / 201
Deu certo (201 quando criou algo).
401
Token ausente ou inválido.
403
A ação exige um nível de acesso maior.
404
Não existe nesta conta (de outra conta também dá 404).
422
Dado inválido ou regra do negócio (número com formato errado, template com problema, PIN curto).
429
Limite do grupo de envio esgotado em 24h.
502
A Meta ou a Infobip recusaram; o motivo vem em message.
Envio iniciado pelo negócio (template, campanha, iniciar conversa) é barrado em número com qualidade vermelha e em conta suspensa. Responder conversa aberta continua liberado.
Guia: bot que vincula número numa BM
O gateway de números (onde o bot aluga o chip e lê o SMS) fica do lado do bot. O Noz cuida da Meta: cria o número na WABA, pede o código, confirma, registra com o PIN e já traz os layouts da conta.
Escolher a WABAGET /wabas?health=good e use uma com has_credential: true. Para saber se a BM dela está boa, GET /bms/{id}.
Alugar o número no gatewayDo lado do bot. Guarde o número sem o 55 (DDD + 8 ou 9 dígitos).
Criar na WABAPOST /wabas/{waba}/numbers com phone e verified_name. A Meta manda o código por SMS. Guarde o channel_id.
Ler o código no gateway e confirmarPOST /channels/{id}/verify-code. Com active: true, o número já está registrado. Sem SMS? POST /channels/{id}/request-code com "method":"VOICE".
Se pedir PINpin_required: true → POST /channels/{id}/register com o PIN de 6 dígitos.
Conferir e usarGET /channels/{id}/health deve dizer Operando. Faltou template? POST /templates/{id}/channels.
# 3) cria o número na WABA e pede o SMScurl -X POST https://hml.prismkg.com/api/v1/wabas/104857600/numbers \
-H "Authorization: Bearer $NOZ_TOKEN" -H "Content-Type: application/json" \
-d '{"phone":"11988887777","verified_name":"Loja Atendimento"}'# => {"data":{"channel_id":31,"code_requested":true,...}}# 4) código lido no gatewaycurl -X POST https://hml.prismkg.com/api/v1/channels/31/verify-code \
-H "Authorization: Bearer $NOZ_TOKEN" -H "Content-Type: application/json" \
-d '{"code":"123456"}'# => {"data":{"active":true,"pin_required":false,...}}
Receber eventos
Cadastre um webhook por número (POST /channels/{id}/webhooks). Cada entrega traz X-Noz-Signature: sha256=<hex>, o HMAC-SHA256 do corpo cru com o seu secret. Responda 2xx rápido; outro status agenda nova tentativa.
O retrato da conta para um bot decidir o que fazer: números, BMs e WABAs boas ou ruins, e a lista do que precisa de ação, já ordenada do pior para o melhor. Os rótulos são os mesmos chips da tela (curtos e podem mudar); para automação use o code, que é estável.
GET/api/v1/overviewnovo
Visão geral da conta
Contagem de números (bons, atenção, ruins e por rótulo), BMs por situação, WABAs sem número ou sem credencial e a lista needs_action.
{"data":{"id":7,"phone":"5511988887777","quality":"RED","quality_label":"Vermelha","tier":"TIER_1K","can_send":"AVAILABLE",
"health":{"good":false,"tone":"bad","label":"Qualidade baixa","code":"qualidade_red","next_action":"Parar 7 dias, só responder","group":"meta","limit_24h":1000,"sent_24h":312,"available":688}}}
WABAs e BMs
Contas do WhatsApp (WABA) e portfólios (BM) da conta, com os números de cada uma, situação, verificação do negócio, pagamento e envios. Use health=good|bad|attention para filtrar.
GET/api/v1/wabasnovo
Listar WABAs
Cada WABA com a BM, se há credencial para criar números nela, layouts por status, última falha ao subir número e a saúde de cada número.
Relê os números de cada WABA (traz os novos, aponta os que sumiram), a verificação, o pagamento e a saúde, e refaz a situação. Devolve a BM atualizada.
Parâmetro
Descrição
id* integercaminho
Id da BM.
Requisição
curl -X POST "https://hml.prismkg.com/api/v1/bms/{id}/sync" \
-H "Authorization: Bearer $NOZ_TOKEN"
Resposta · 200
{"data":{"message":"Loja: 2 número(s) lido(s) na Meta, 2 podendo enviar. A BM está em uso.","created_numbers":[],"missing_numbers":[],"bm":{"id":3,"good":true}}}
POST/api/v1/bms/{id}/payment-checknovo
Verificar pagamento da BM
Pergunta à Meta agora. Pagamento OK libera os números travados por pagamento sem esperar o cooldown.
Parâmetro
Descrição
id* integercaminho
Id da BM.
Requisição
curl -X POST "https://hml.prismkg.com/api/v1/bms/{id}/payment-check" \
-H "Authorization: Bearer $NOZ_TOKEN"
Resposta · 200
{"data":{"message":"Pagamento OK na Meta; 2 número(s) liberado(s).","bm":{"id":3,"name":"Loja","good":true,"payment":"ok"}}}
Vincular número novo
O bot aluga o número no gateway dele, cria o número numa WABA da conta, lê o código que chegou por SMS ou ligação e confirma. O Noz registra na Cloud API com o PIN guardado (ou o padrão) e o número herda os layouts da conta.
POST/api/v1/wabas/{waba}/numbersnovo
Criar número na WABA
Mesmo fluxo do "+ Número" da tela. Já pede o código (SMS por padrão). Número brasileiro é DDD + 8 ou 9 dígitos, sem o 55.
Parâmetro
Descrição
waba* stringcaminho
WABA da conta com credencial (has_credential = true em GET /wabas).
phone* stringcorpo
Número sem o DDI, ex.: 11988887777.
verified_name* stringcorpo
Nome de exibição (mín. 3 caracteres).
cc stringcorpo
DDI, padrão 55.
method stringcorpo
SMS (padrão), VOICE ou NONE (não pede o código agora).
same_group booleancorpo
Entra no mesmo grupo de envio do número que emprestou a credencial.
{"data":{"message":"Número 5511988887777 criado na conta Loja WhatsApp. Herdou 14 layouts da conta. Código enviado por SMS para o número. ...","channel_id":31,"phone":"5511988887777","code_requested":true,"bm_id":3}}
Relê na Meta (qualidade, tier, can_send) ou, na Infobip, os templates do sender. Devolve o número com a saúde nova.
Parâmetro
Descrição
id* integercaminho
Id do número.
Requisição
curl -X POST "https://hml.prismkg.com/api/v1/channels/{id}/sync" \
-H "Authorization: Bearer $NOZ_TOKEN"
Resposta · 200
{"data":{"message":"Número sincronizado com a Meta.",
"channel":{"id":7,"phone":"5511988887777","status":"WORKING","quality":"GREEN","tier":"TIER_1K","can_send":"AVAILABLE",
"health":{"good":true,"tone":"ok","label":"Operando","next_action":null,"limit_24h":1000,"sent_24h":120,"available":880}}}}
POST/api/v1/channels/{id}/payment-checknovo
Verificar pagamento do número
Confere na Meta o pagamento da BM do número; paid = true libera o envio travado por pagamento.
Parâmetro
Descrição
id* integercaminho
Id do número.
Requisição
curl -X POST "https://hml.prismkg.com/api/v1/channels/{id}/payment-check" \
-H "Authorization: Bearer $NOZ_TOKEN"
Resposta · 200
{"data":{"message":"Pagamento da BM está OK.","paid":true}}
POST/api/v1/channels/official
Conectar número oficial com credenciais
Para quem já tem phone_number_id e token. Guarda os segredos cifrados e valida na hora.
{"data":[{"name":"boas_vindas","language":"pt_BR","category":"UTILITY","body":"Oi {{1}}! Seu pedido {{2}} foi confirmado.","params":2,
"header":null,"buttons":[{"type":"url","text":"Acompanhar","url":"https://loja.com/p/{{1}}","example":"1234"}]}]}
Templates (layouts)
A biblioteca de templates da conta e o vínculo de cada um com os números. Vincular = submeter à Meta (ou Infobip) naquele número; o status de aprovação chega pelo webhook e por /sync.
{"data":[{"id":10,"name":"Boas-vindas","meta_name":"boas_vindas","kind":"official","category":"utility","language":"pt_BR",
"body":"Oi {{1}}! Seu pedido {{2}} foi confirmado.","header_type":null,"header_text":null,"has_media_header":false,"buttons":[],
"var_map":{"1":{"field":"nome"},"2":{"field":"pedido"}},"channels":[{"channel_id":7,"status":"approved","rejection_reason":null}]}]}
POST/api/v1/templates
Criar template
Parâmetro
Descrição
name* stringcorpo
Nome na biblioteca.
body* stringcorpo
Corpo com {{1}}, {{2}}…
category stringcorpo
marketing (padrão), utility ou authentication.
language stringcorpo
Padrão pt_BR.
meta_name stringcorpo
Nome fixo na Meta (^[a-z0-9_]+$).
header_text stringcorpo
Cabeçalho de texto.
footer_text stringcorpo
Rodapé.
buttons arraycorpo
Botões.
var_map objectcorpo
Variável → coluna da audiência ({"1":{"field":"nome","default":"cliente"}}).
submit_channels arraycorpo
Números para já vincular.
Requisição
curl -X POST "https://hml.prismkg.com/api/v1/templates" \
-H "Authorization: Bearer $NOZ_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Boas-vindas","category":"utility","body":"Oi {{1}}! Seu pedido {{2}} foi confirmado.","var_map":{"1":{"field":"nome"},"2":{"field":"pedido"}},"submit_channels":[7,8]}'
{"data":{"id":10,"name":"Boas-vindas","meta_name":"boas_vindas","category":"utility","language":"pt_BR",
"body":"Oi {{1}}, seu pedido {{2}} saiu para entrega.","auto_replicate":true,"problems":[],"channels_by_status":{"approved":2},"channels":[]}}
DELETE/api/v1/templates/{id}novo
Remover template
Tira da biblioteca e apaga na Meta em cada WABA. Se a Meta recusar, nada sai e volta 502 com o motivo.
Template DESATIVADO/pausado no número: sobe uma nova versão (_v2, _v3…) com o texto atual e o número passa a usá-la quando aprovar.
Parâmetro
Descrição
id* integercaminho
Id do template.
channelId* integercaminho
Id do número.
Requisição
curl -X POST "https://hml.prismkg.com/api/v1/templates/{id}/channels/{channelId}/reactivate" \
-H "Authorization: Bearer $NOZ_TOKEN"
Resposta · 200
{"data":{"nome":"boas_vindas_v2","message":"Nova versão \"boas_vindas_v2\" enviada para análise. Quando aprovar, este número passa a disparar por ela."}}
POST/api/v1/templates/{id}/sync
Sincronizar status de aprovação
Parâmetro
Descrição
id* integercaminho
Id do template.
Requisição
curl -X POST "https://hml.prismkg.com/api/v1/templates/{id}/sync" \
-H "Authorization: Bearer $NOZ_TOKEN"
Resposta · 200
{"data":{"synced_channels":3}}
POST/api/v1/templates/{id}/submit
Submeter a todos os números oficiais
Sem "channels", usa todos os números Cloud com WABA.
Parâmetro
Descrição
id* integercaminho
Id do template.
channels arraycorpo
Ids dos números.
Requisição
curl -X POST "https://hml.prismkg.com/api/v1/templates/{id}/submit" \
-H "Authorization: Bearer $NOZ_TOKEN"
Envio 1 a 1 (texto dentro da janela de 24h, template para iniciar conversa, mídia por URL) e leitura do Inbox. Envio iniciado pelo negócio respeita a trava de qualidade vermelha e de conta suspensa.
{"data":{"id":9001,"conversation_id":55,"to":"5511999999999@c.us","type":"template","text":"Oi Ana! Seu pedido 1234 foi confirmado.",
"channel_id":7,"wa_message_id":"wamid.HBgMNTUxMTk5...","header":null}}
{"data":[{"id":10,"name":"Boas-vindas","meta_name":"boas_vindas","category":"utility","language":"pt_BR",
"body":"Oi {{1}}! Seu pedido {{2}} foi confirmado.","variables":2,"header_type":null,"has_media_header":false,"buttons":[],
"var_map":{"1":{"field":"nome"},"2":{"field":"pedido"}}}]}
{"data":{"notify_url":"https://SEU_DOMINIO/webhooks/infobip/TOKEN_DA_CONTA","fixed_url":"https://SEU_DOMINIO/webhooks/infobip",
"observacao":"Use notify_url em \"notifyUrl\" no envio ..."}}
{"data":[{"id":4,"title":"Política de trocas","slug":"politica-de-trocas","category_id":2,"visibility":"public","bot_knowledge":true,
"excerpt":"Você tem 30 dias.","public_url":"https://SEU_DOMINIO/w/loja/politica-de-trocas","created_at":"2026-09-01 10:00:00","updated_at":"2026-10-01 10:00:00"}]}
{"data":{"id":4,"title":"Política de trocas","slug":"politica-de-trocas","category_id":2,"visibility":"public","bot_knowledge":true,
"excerpt":"Você tem 30 dias.","public_url":"https://SEU_DOMINIO/w/loja/politica-de-trocas","content":"## Trocas\n\nVocê tem **30 dias**.",
"created_at":"2026-09-01 10:00:00","updated_at":"2026-10-01 10:00:00"}}
POST/api/v1/wiki
Criar página
Parâmetro
Descrição
title* stringcorpo
Título.
content stringcorpo
Markdown.
category_id integercorpo
Categoria.
visibility stringcorpo
private (padrão) ou public.
bot_knowledge booleancorpo
O bot usa como conhecimento.
Requisição
curl -X POST "https://hml.prismkg.com/api/v1/wiki" \
-H "Authorization: Bearer $NOZ_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title":"Política de trocas","content":"## Trocas\n\nVocê tem **30 dias**.","visibility":"public","bot_knowledge":true}'
Resposta · 201
{"data":{"id":4,"title":"Política de trocas","slug":"politica-de-trocas","category_id":null,"visibility":"public","bot_knowledge":true,
"excerpt":"Você tem 30 dias.","public_url":"https://SEU_DOMINIO/w/loja/politica-de-trocas","content":"## Trocas\n\nVocê tem **30 dias**.",
"created_at":"2026-10-08 10:00:00","updated_at":"2026-10-08 10:00:00"}}
PUT/api/v1/wiki/{id}
Atualizar página
Parâmetro
Descrição
id* integercaminho
Id da página.
Requisição
curl -X PUT "https://hml.prismkg.com/api/v1/wiki/{id}" \
-H "Authorization: Bearer $NOZ_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title":"Política de trocas e devoluções"}'
Resposta · 200
{"data":{"id":4,"title":"Política de trocas e devoluções","slug":"politica-de-trocas","visibility":"public","bot_knowledge":true,
"content":"## Trocas\n\nVocê tem **30 dias**.","updated_at":"2026-10-08 11:00:00"}}
{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"list_channels",
"description":"Lista os canais/números de WhatsApp da conta (id, nome, telefone, status, motor).","inputSchema":{"type":"object","properties":{}}}]}}