Leitura de 8 minutos Atualizada: 08/05/2026 Criado pela: Equipe Botmaker

Como enviar notificações por meio da API?

1. Introdução

A API do Botmaker v2.0 permite enviar notificações e templates de WhatsApp de forma programática, criar e gerenciar campanhas em massa, consultar resultados de envios e administrar listas negras de contatos.

O WhatsApp permite que empresas enviem mensagens dentro de uma janela de 24 horas a partir da última mensagem do usuário. Fora dessa janela, é obrigatório utilizar templates (HSM) previamente aprovados pela Meta para retomar a conversa. As notificações são um produto pago do WhatsApp.

1.1 Resumo dos Endpoints de Notificações

Método	Path	Descrição
POST	/notifications	Criar e enviar uma notificação
POST	/notifications/campaigns	Criar uma campanha de notificações
GET	/notifications/campaigns	Listar campanhas existentes
GET	/notifications/sent-results	Listar resultados de envios com contadores
GET	/notifications/sent-results/{id}	Detalhe de uma instância com clientes
POST	/notifications/contacts-blacklist	Adicionar contatos à lista negra
GET	/notifications/contacts-blacklist	Listar contatos na lista negra
DELETE	/notifications/contacts-blacklist/{c}	Remover contato da lista negra

2. Autenticação

A API utiliza autenticação por API Key. O token é enviado no header de cada request.

Esquema de segurança

Propriedade	Valor
Tipo	apiKey
Nome do header	access-token
Localização	header

2.1 Obter o Access Token

Fazer login no Botmaker: https://go.botmaker.com
Navegar até Configurações > Integrações > API do Botmaker.
Clicar em “Gerar credenciais” ou usar as existentes.
Copiar o access-token exibido na tela.

URL direta: https://go.botmaker.com/#/integrations/api

2.2 Headers Obrigatórios

access-token: <SEU_ACCESS_TOKEN>

Content-Type: application/json

Accept: application/json

2.3 Gerenciar Credenciais via API

Endpoint	Método	Descrição
GET /auth/credentials	GET	Obter credenciais atuais da API.
POST /auth/credentials	POST	Atualizar/regenerar credenciais da API.
DELETE /auth/credentials	DELETE	Excluir credenciais da API.

3. Obter o Channel ID

Antes de enviar notificações, você precisa obter o ID do canal do WhatsApp. Esse valor é obrigatório no campo channelId do endpoint de notificações.

GET /channels

Parâmetros de query

Parâmetro	Tipo	Descrição
platform	string	Filtrar por plataforma. Usar "whatsapp" para obter apenas canais de WhatsApp.
active	boolean	Filtrar apenas canais ativos (true).

Exemplo

GET https://api.botmaker.com/v2.0/channels?platform=whatsapp&active=true

Headers:

access-token: <SEU_ACCESS_TOKEN>

Resposta

{

"items": [

{

"id": "botproject-whatsapp-5511947038***",

"platform": "whatsapp",

"active": true,

"name": "Minha Linha WhatsApp",

"webhookId": "webhook_abc123"

}

]

}

Rate limit: 1 request por segundo.

⚠ O valor do campo "id" é o channelId que você precisará para enviar notificações.

4. Templates de WhatsApp

Os templates devem estar aprovados pela Meta antes de poderem ser usados para enviar notificações. A API v2.0 permite criá-los, listá-los e excluí-los.

4.1 Listar Templates

GET /whatsapp/templates

Parâmetros de query

Parâmetro	Tipo	Descrição
state	string (enum)	Filtrar por status: APPROVED ou REJECTED.

Exemplo

GET https://api.botmaker.com/v2.0/whatsapp/templates?state=APPROVED

4.2 Criar Template

POST /whatsapp/templates

Body (WhatsAppTemplateRequest)

Campo	Tipo	Obrigatório	Descrição
name	string	Não	Nome do template em snake_case. Ex: "promo_inverno"
phoneLineNumber	string	Condicional	Número da linha WhatsApp. Obrigatório apenas se houver mais de uma conta business.
botName	string	Condicional	Nome do bot associado. Obrigatório se o projeto tiver múltiplos bots.
category	string (enum)	Não	Categoria: MARKETING, UTILITY, AUTHENTICATION
locale	string	Não	Idioma do template (ex: pt_BR, es_AR, en_US).
header	object	Não	Cabeçalho do template (texto, imagem, vídeo ou documento).
body	object	Sim	Corpo da mensagem com texto e variáveis.
footer	object	Não	Rodapé do template.
buttons	array	Não	Botões: QUICK_REPLY (máx 3), URL (máx 1), PHONE_NUMBER (máx 1). Não é possível combinar QUICK_REPLY com URL/PHONE_NUMBER.
optInImage	string	Não	URL de imagem de exemplo mostrando o opt-in do usuário.

Status possíveis de um template

Status	Descrição
APPROVED	Aprovado pela Meta. Pronto para uso.
REJECTED	Rejeitado pela Meta. Verificar notas de rejeição.
ACCOUNT_PENDING	Pendente de revisão por parte da conta.
BOTMAKER_PENDING	Pendente de revisão interna do Botmaker.

4.3 Consultar / Excluir Template

Endpoint	Método	Descrição
/whatsapp/templates/{idOrName}	GET	Obter detalhes de um template por ID ou nome.
/whatsapp/templates/{idOrName}	DELETE	Excluir um template.

5. Enviar Notificação (send-notification)

POST /notifications

Cria e envia uma nova notificação dentro de uma campanha, ou adiciona mais contatos a uma notificação existente. Suporta WhatsApp, SMS e Email.

5.1 Request Body (NotificationRequest)

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da notificação.
channelId	string	Sim	ID do canal. Obtido via GET /channels. Plataformas suportadas: WhatsApp, SMS, Email.
campaign	string	Não	Nome ou ID da campanha, ou null para a campanha padrão.
intentIdOrName	string	Não	ID ou nome do intent/template a ser disparado. O nome é o que aparece na página de bots do Botmaker.
contacts	array	Sim	Lista de contatos destinatários (ver esquema NotificationContactRequest).

5.2 Esquema de Contato (NotificationContactRequest)

Campo	Tipo	Obrigatório	Descrição
contactId	string	Sim	ID do contato. No WhatsApp é o número de telefone com código do país. Ex: "5511955667788"
variables	object	Não	Variáveis a serem definidas antes de executar o intent. Ex: {"nome": "João", "pedido": "ORD-123"}
tags	object	Não	Tags (booleanos) a serem definidas antes de executar o intent. Ex: {"vip": true, "novo": false}
webhookPayload	string	Não	Dados personalizados para receber na notificação do webhook. Qualquer string para rastreamento.

5.3 Exemplo Completo

POST https://api.botmaker.com/v2.0/notifications

Headers:

Content-Type: application/json

access-token: <SEU_ACCESS_TOKEN>

Body:

{

"name": "Confirmação Pedido #42",

"channelId": "botproject-whatsapp-5511947038000",

"campaign": "vendas_abril_2026",

"intentIdOrName": "confirmacao_pedido",

"contacts": [

{

"contactId": "5511955667788",

"variables": {

"nome": "João Silva",

"nroPedido": "ORD-2026-0042",

"total": "R$ 850,00"

"tags": {

"compradorFrequente": true

"webhookPayload": "order-tracking-042"

{

"contactId": "5511966778899",

"variables": {

"nome": "Maria Souza",

"nroPedido": "ORD-2026-0043",

"total": "R$ 420,00"

}

]

}

5.4 Respostas

Código	Descrição
201	Notificação enviada com sucesso.
400	Dados da campanha ou notificação inválidos.
429	Rate limit excedido (máx 5 req/seg).

6. Campanhas de Notificações

6.1 Criar Campanha (create-campaign)

POST /notifications/campaigns

Cria uma nova campanha de notificações. As campanhas agrupam envios para organizar e medir resultados.

Request Body (CampaignRequest)

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome único da campanha.
goal	string	Não	Texto que define o objetivo da campanha.

Exemplo

POST https://api.botmaker.com/v2.0/notifications/campaigns

Body:

{

"name": "Promo Inverno 2026",

"goal": "Enviar cupons de desconto para usuários ativos do último mês"

}

Respostas

Código	Descrição
201	Campanha criada com sucesso.
400	Dados da campanha inválidos.
429	Rate limit excedido (máx 5 req/seg).

6.2 Listar Campanhas (list-campaigns)

GET /notifications/campaigns

Lista todas as campanhas de notificações. Retorna páginas de 250 campanhas. Continuar chamando o nextPageURL até que seja null.

Resposta (CampaignPage)

Campo	Tipo	Descrição
nextPage	string \| null	URL da próxima página. null se não houver mais dados.
items	array	Lista de campanhas.

Objeto Campaign (CampaignResponse)

Campo	Tipo	Descrição
id	string	ID único da campanha.
name	string	Nome da campanha.
goal	string	Objetivo da campanha.
active	boolean	Se a campanha está ativa.

7. Resultados de Envios (sent-results)

7.1 Listar Resultados (list-sent-notifications-results)

GET /notifications/sent-results

Lista as notificações enviadas com seus contadores de status (sent, delivered, read, answered). Retorna até 500 instâncias por página, ordenadas por data de início decrescente.

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição
notification-name	string	Não	Nome da notificação. Se fornecido, os filtros de data são ignorados.
from	date-time	Condicional	Data mínima de início. Obrigatório se notification-name não for fornecido. Máximo 3 meses atrás. Formato ISO-8601.
to	date-time	Não	Data máxima de início. Padrão: now() menos 1 dia. Formato ISO-8601.

Exemplo por período de datas

GET https://api.botmaker.com/v2.0/notifications/sent-results

?from=2026-03-01T00:00:00Z

&to=2026-04-14T00:00:00Z

Exemplo por nome

GET https://api.botmaker.com/v2.0/notifications/sent-results

?notification-name=Welcome%20Message

Resposta (NotificationInstancesPage)

Campo	Tipo	Descrição
nextPage	string \| null	URL da próxima página (usar exatamente como vem com o header access-token).
items	array	Lista de NotificationInstanceResponse.

Objeto NotificationInstanceResponse

Campo	Tipo	Descrição
notificationInstanceId	string	ID da instância da notificação.
campaignName	string	Nome da campanha. Ex: "Marketing Campaign 2024"
contactGroup	string	Grupo de contatos. Ex: "Premium Users"
notificationName	string	Nome da notificação.
start	string	Timestamp de início do envio. Ex: "2024-01-15T10:30:00Z"
end	string	Timestamp de fim do envio.
status	string	Status da notificação. Ex: "COMPLETED"
details	object	Contadores de status (ver detalhe abaixo).

Objeto de Contadores (NotificationInstanceDetails)

Campo	Tipo	Descrição
sent	integer	Quantidade de mensagens enviadas. Ex: 100
delivered	integer	Quantidade de mensagens entregues. Ex: 95
read	integer	Quantidade de mensagens lidas. Ex: 80
answered	integer	Quantidade de mensagens respondidas. Ex: 25
error	integer	Quantidade de mensagens com erro. Ex: 5

7.2 Detalhe da Instância (get-notification-instance-detail)

GET /notifications/sent-results/{notificationInstanceId}

Obtém o detalhe de clientes para a última instância de uma notificação específica. Retorna 500 clientes por página com suporte a paginação.

Parâmetros de Path

Parâmetro	Tipo	Descrição
notificationInstanceId	string	ID da instância. Ex: "notif_123456"

Exemplo

GET https://api.botmaker.com/v2.0/notifications/sent-results/notif_123456

Resposta (NotificationInstanceDetailResponse)

Campo	Tipo	Descrição
nextPage	string \| null	URL da próxima página. null se não houver mais.
notification	object	Info da notificação (NotificationInfo).
customers	array	Lista de até 500 clientes (CustomerDetail).

Objeto NotificationInfo

Campo	Tipo	Descrição
campaignName	string	Nome da campanha.
contactGroup	string	Grupo de contatos.
notificationName	string	Nome da notificação.
notificationId	string	ID da notificação.
notificationInstanceId	string	ID da instância.
start / end	string	Timestamps de início e fim.
status	string	Status. Ex: "COMPLETED"
details	object	Contadores (sent, delivered, read, answered, error).

Objeto CustomerDetail

Campo	Tipo	Descrição
customerId	string	ID do cliente no Botmaker. Ex: "002HITVZHY47SGW8FHCX"
sessionId	string	ID da sessão.
contactId	string	Número de telefone. Ex: "5511999995555"
phone	string	Número de telefone.
firstName / lastName	string	Nome e sobrenome do contato.
email	string	Email do contato.
lastStatus	enum	Último status: sent \| delivered \| read \| answered \| error
answeredMessage	string	Texto da resposta do cliente. Ex: "Sim, tenho interesse"
answeredMessageId	string	ID da mensagem de resposta.
status	object	Timestamps por evento (sent, delivered, read, answered, error).

Objeto CustomerStatus (timestamps por evento)

{

"sent": "2024-01-15T10:30:00Z",

"delivered": "2024-01-15T10:30:05Z",

"read": "2024-01-15T10:35:00Z",

"answered": "2024-01-15T10:40:00Z",

"error": null

}

8. Lista Negra de Contatos (Blacklist)

A blacklist impede que notificações sejam enviadas para determinados números de telefone.

8.1 Adicionar Contatos à Blacklist

POST /notifications/contacts-blacklist

Adiciona um ou mais contatos à lista negra. Limite: 1000 contatos por request.

Body

{

"contacts": ["5511999993333", "5521912349876"]

}

Código	Descrição
204	Contatos adicionados com sucesso.
400	Nenhum contato enviado.
429	Rate limit excedido.

8.2 Listar Contatos na Blacklist

GET /notifications/contacts-blacklist

Retorna a lista paginada de contatos bloqueados. Usar nextPage para paginar.

8.3 Remover Contato da Blacklist

DELETE /notifications/contacts-blacklist/{contact}

Exemplo

DELETE https://api.botmaker.com/v2.0/notifications/contacts-blacklist/5511999995555

11. Boas Práticas

11.1 Políticas da Meta para Marketing

A Meta limita a quantidade de mensagens de marketing que cada usuário pode receber por dia (algoritmo automático da Meta).
Máximo de 2 mensagens de marketing consecutivas para um usuário em 24 horas. Se o usuário responder, o ciclo é reiniciado.
Uma terceira mensagem consecutiva de marketing resultará em erro de envio.

11.2 Formato de Datas

Todas as datas devem usar o formato ISO-8601. Exemplo: 2026-04-14T16:21:20.535Z (Z = GMT-0).

11.3 Ordem de Envio

Os envios em massa são processados em paralelo, portanto a ordem não é garantida. Para garantir sequência:

Aguardar confirmação de entrega por webhook antes de enviar a próxima mensagem.
Espaçar mensagens de uma mesma conversa para processamento sequencial.

11.4 Tratamento de Erros

Código	Ação Recomendada
400	Verificar parâmetros do body e IDs. O campo errors[] contém o detalhe.
401	Regenerar ou verificar o access-token.
404	Verificar se o recurso (notificação, template) existe.
429	Implementar retry com backoff exponencial. Respeitar os limites por endpoint.

11.5 Paginação

Vários endpoints retornam respostas paginadas com um campo nextPage. Para percorrer todos os resultados:

Fazer a primeira chamada ao endpoint.
Se nextPage não for null, fazer GET para essa URL exata com o header access-token.
Repetir até que nextPage seja null.

11.6 Estrutura de Erros

{

"errors": [

{

"type": "VALIDATION_ERROR",

"source": "channelId",

"message": "Channel not found"

}

]

}

12. Exemplo: Fluxo Completo de Envio

Passo 1 — Obter o Channel ID

GET https://api.botmaker.com/v2.0/channels?platform=whatsapp&active=true

// Resposta -> usar o campo "id" do canal desejado

Passo 2 — Verificar o template aprovado

GET https://api.botmaker.com/v2.0/whatsapp/templates?state=APPROVED

// Confirmar que o template desejado está na lista

Passo 3 — Criar a campanha (opcional)

POST https://api.botmaker.com/v2.0/notifications/campaigns

Body: { "name": "Vendas Abril", "goal": "Confirmações de pedido" }

Passo 4 — Enviar a notificação

POST https://api.botmaker.com/v2.0/notifications

Body:

{

"name": "Confirmação Pedido",

"channelId": "botproject-whatsapp-5511947038000",

"campaign": "Vendas Abril",

"intentIdOrName": "confirmacao_pedido",

"contacts": [

{ "contactId": "5511955667788", "variables": { "nome": "João" } }

]

}

Passo 5 — Consultar resultados

GET https://api.botmaker.com/v2.0/notifications/sent-results

?notification-name=Confirmação%20Pedido

Passo 6 — Ver detalhe por cliente

GET https://api.botmaker.com/v2.0/notifications/sent-results/{instanceId}

// Retorna cada cliente com seu status: sent, delivered, read, answered, error

11. Envios na Plataforma

Todos os envios realizados por API utilizando estes endpoints podem ser visualizados na seção https://go.botmaker.com/#/campaigns da plataforma. Da mesma forma, também é possível realizar envios diretamente a partir dessa seção.

Lembre-se de visitar nossa Central de Ajuda para obter mais informações.