📘 Este middleware dá acesso às conversas e às tarefas da Botdizzer por um endereço único. Todas as chamadas vão para o servidor do middleware; ele repassa cada uma ao Botdizzer com o seu token.
Endereço base
https://{SERVIDOR}
➡️“{SERVIDOR}”: endereço do middleware no seu ambiente, por exemplo api.suaempresa.com.br. Substitua em todos os exemplos.
◽ As respostas são JSON em UTF-8. Datas vêm em ISO 8601 (UTC), por exemplo 2026-10-27T21:07:49.151Z.
🔑 Envie o token da sua conexão Botdizzer em todas as chamadas, no header Authorization. Só o /health dispensa o token.
Header
Authorization: Bearer {seutokenaqui}
➡️“seutokenaqui”: token cadastrado na conexão, na Botdizzer.
◽ O middleware repassa o token ao Botdizzer em cada chamada e não guarda nenhuma cópia.
◽ Sem o header, a resposta é 401. Se o token for inválido, o erro do Botdizzer volta como veio.
⚠️ Mantenha o token no servidor
Ele dá acesso às conversas e às tarefas da empresa. Não coloque o token em código que roda no navegador nem em aplicativos distribuídos.
APIs › Começo › Erros
Erros
Os erros do próprio middleware vêm no formato {"error": "mensagem"}. Erros gerados pelo Botdizzer, como uma tarefa inexistente ou um campo com valor não aceito, voltam com o status e o corpo originais.
Status
Quando acontece
O que fazer
400
Parâmetro inválido: ID que não é número, status ou priority fora dos valores aceitos, datas fora do formato, campo não aceito no corpo, JSON malformado, comentário sem content ou userId, anexo sem multipart.
Corrija o parâmetro indicado na mensagem.
401
Header Authorization: Bearer ausente.
Envie o token.
404
Rota ou método inexistente.
Confira o caminho e o método.
413
Corpo acima do limite: 1 MB no JSON, 20 MB no upload de anexos.
Reduza ou divida os arquivos.
502
O middleware não conseguiu falar com o Botdizzer.
Tente de novo. Se persistir, avise o responsável pelo middleware.
504
O Botdizzer demorou mais que o limite (15 s por padrão).
Tente de novo.
APIs › Começo › Status do serviço
Status do serviço
GET
💓 Indica se o middleware está no ar. Use em ferramentas de monitoramento.
Endpoint
https://{SERVIDOR}/health
Método
GET
Autenticação
Não precisa
Resposta
{ "status": "ok" }
APIs › Chat-Conversas › API Listar Mensagens do Ticket
API Listar Mensagens do Ticket
GET
💬 Retorna as mensagens da conversa, da mais recente para a mais antiga, em páginas. Notas internas, marcadores de sistema e avisos de falha de envio são sempre removidos.
➡️“count”: total de mensagens do ticket, já sem as internas.
➡️“hasMore”:true quando há mensagens mais antigas na próxima página.
➡️“fromMe”:true se a mensagem foi enviada pela empresa; false se veio do contato.
➡️“mediaType”: onde está o conteúdo da mensagem:
mediaType
Conteúdo
Onde ler
conversation
Mensagem de texto do chat
body
audio
Áudio, nos formatos aceitos pelo WhatsApp (ex.: .opus)
mediaUrl
document
Arquivo, como PDF ou DOCX
mediaUrl
image
Imagem
mediaUrl
video
Vídeo
mediaUrl
💡 Paginação
Peça a página seguinte enquanto vier "hasMore": true. Cada página seguinte traz mensagens mais antigas; dentro da página, a mais antiga vem primeiro. Exemplo: 148 mensagens com pageSize=50 → páginas 1 e 2 com 50, página 3 com 48 e hasMore: false.
◽ A consulta é somente leitura: não marca a conversa como lida nem avisa os atendentes.
APIs › Chat-Conversas › API Dados do Ticket
API Dados do Ticket
GET
🎫 Retorna os dados do ticket e os objetos ligados a ele: contato, atendente, fila, conexão de WhatsApp, tags e empresa. A consulta não altera o ticket.
Endpoint
https://{SERVIDOR}/dadosticket/{ticketId}
Método
GET
Autenticação
Bearer {seutokenaqui}
Parâmetros
➡️“ticketId”: ID do ticket, no próprio endereço. Obrigatório.
➡️“contact”: também traz lid, profilePicUrl, active, channel, picupdatedAt, genero, estado, referencia, endereco, aniversario, createdAt e updatedAt. extraInfo lista os campos personalizados.
➡️“user”: atendente responsável. Pode vir null se o ticket ainda não foi assumido.
➡️“tags”: etiquetas do ticket, cada uma com id, name e color.
◽ A resposta tem sempre esses campos e nenhum outro. Se algum deixar de vir do Botdizzer, ele some da resposta: trate campos ausentes no seu código.
APIs › Chat-Conversas › API Listar Tickets por Período
API Listar Tickets por Período
GET
🗂️ Retorna os tickets com o status pedido que tiveram a última movimentação (updatedAt) entre as duas datas, inclusive. A lista é paginada e vem em ordem de movimentação.
➡️“status”:open (em atendimento), pending (aguardando) ou closed (finalizado). Obrigatório.
➡️“dataInicial”: primeiro dia da última movimentação, AAAA-MM-DD. Obrigatório.
➡️“dataFinal”: último dia, inclusive. No máximo 31 dias depois de dataInicial. Obrigatório.
➡️“pageNumber”: página. Padrão 1.
🕒 Os dias seguem o horário de Brasília
Os campos createdAt e updatedAt da resposta vêm em UTC. Um ticket movimentado às 21h51 de 20/10 aparece em dataFinal=2026-10-20, embora o updatedAt seja 2026-10-21T00:51:05Z.
Repita com o próximo pageNumber enquanto vier "hasMore": true. Uma página pode vir com poucos tickets, ou vazia, e ainda ter hasMore: true: continue até receber false. Períodos longos demoram mais; use um tempo de espera folgado no seu cliente.
APIs › Tarefas › API Listar Tarefas
API Listar Tarefas
GET
📋 Lista as tarefas da empresa, filtradas pelo endereço. Cada tarefa vem com quem criou e o responsável, das mais prioritárias e recentes para as demais. Não há paginação: a lista vem inteira.
Prazo (ISO 8601) e horários de início e fim (HH:MM).
reminderMinutes
Lembrete, em minutos antes.
tipo
lembrete, reuniao, ligacao, email, visita ou tarefa.
sala, salaCodigo, meetingUrl
Dados da sala, na reunião.
isRecurring, recurringPattern
Se a tarefa se repete, e com que frequência.
checklist
Itens, cada um com texto e feito.
responsaveis
Todos os responsáveis, em ordem; o primeiro é o principal.
sharedWith
Atendentes com quem a tarefa é compartilhada.
ticketId, crmOportunidadeId, projetoId
Atendimento, oportunidade de CRM e projeto vinculados.
creator, assignee
Quem criou e o responsável.
◽ Tarefa que não existe, ou que é de outra empresa, é recusada pelo Botdizzer; o erro volta como veio.
APIs › Tarefas › API Atualizar Tarefa
API Atualizar Tarefa
PUT
🧩 Atualiza uma tarefa: só o que vier no corpo muda. Campos que não vierem continuam como estão.
Endpoint
https://{SERVIDOR}/tarefas/{tarefaId}
Método
PUT
Autenticação
Bearer {seutokenaqui}
Payload
{
"title": "Retornar ligação do cliente",
"description": "Cliente pediu retorno à tarde",
"priority": "high",
"assignedTo": 4,
"dueDate": "2028-12-30T23:59:59.000Z",
"startTime": "14:00",
"endTime": "14:30",
"reminderMinutes": 30,
"tipo": "ligacao",
"sharedWith": [],
"isRecurring": false,
"checklist": [
{ "texto": "Ligar para o cliente", "feito": true },
{ "texto": "Registrar o retorno" }
]
}
➡️“tarefaId”: ID da tarefa, no próprio endereço. Obrigatório.
➡️“title”: novo título da tarefa.
➡️“description”: nova descrição.
➡️“priority”:high, medium ou low.
➡️“assignedTo”: ID do atendente responsável. Mande 0 para deixar a tarefa sem responsável.
➡️“dueDate”: prazo, em ISO 8601 — AAAA-MM-DDTHH:mm:ss.sssZ. Mande null para tirar o prazo.
➡️“startTime”: horário de início, HH:MM, no fuso da empresa. Vazio ou null: sem horário.
➡️“endTime”: horário de fim, no mesmo formato. Não pode vir antes do início.
➡️“reminderMinutes”: lembrete, em minutos antes: 5, 15, 30, 60, 120 ou 1440. Vazio, null ou 0: sem lembrete.
➡️“tipo”:lembrete, reuniao, ligacao, email, visita ou tarefa. Vazio: sem tipo.
➡️“sala”: só na reunião — nossa (sala de vídeo da plataforma), meet (Google Meet, pela agenda) ou nenhuma.
➡️“sharedWith”: lista inteira de IDs de atendentes com quem a tarefa é compartilhada. Substitui a anterior — [] tira todos.
➡️“isRecurring”:false para a tarefa deixar de se repetir. Com true, o recurringPattern é obrigatório.
➡️“recurringPattern”:daily, weekly, monthly ou yearly.
➡️“recurringOptions”: só no semanal — os dias em daysOfWeek, de 0 (domingo) a 6 (sábado). Ex.: {"daysOfWeek":[1,3,5]}.
➡️“status”:pending para em aberto, completed para concluída.
➡️“ticketId”: ID do atendimento vinculado. Mande 0 ou null para desvincular.
➡️“checklist”: lista inteira de itens, com texto e feito (true quando feito). Substitui a lista anterior — o item que não vier sai.
◽ Para um item continuar o mesmo, mande junto o id que ele já tem. Sem id, entra como novo.
◽[] tira todos os itens. Sem o campo checklist, a lista fica como está.
➡️“sincronizarAgenda”:true coloca a tarefa no Google Agenda do responsável; false tira.
💡 Sincronização com a agenda
Se a tarefa estiver no Google Agenda, as alterações vão para o evento.
⚠️ Só os campos acima
Qualquer outro campo no corpo é recusado pelo middleware com 400, e a resposta lista os campos aceitos. Um valor que o campo não aceita é recusado pelo Botdizzer, que diz qual campo corrigir.