APIs › Começo › Introdução

APIs Botdizzer

v2

📘 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.

Chat-Conversas

Tarefas

APIs › Começo › Autenticação

Autenticação

🔑 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.

StatusQuando aconteceO que fazer
400Parâ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.
401Header Authorization: Bearer ausente.Envie o token.
404Rota ou método inexistente.Confira o caminho e o método.
413Corpo acima do limite: 1 MB no JSON, 20 MB no upload de anexos.Reduza ou divida os arquivos.
502O middleware não conseguiu falar com o Botdizzer.Tente de novo. Se persistir, avise o responsável pelo middleware.
504O 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.

Endpoint
https://{SERVIDOR}/tickets/{ticketId}?pageNumber={pagina}&pageSize={tamanho}
Método
GET
Autenticação
Bearer {seutokenaqui}
Parâmetros

➡️ “ticketId”: ID do ticket, no próprio endereço. É o número entre parênteses no cabeçalho da conversa, não o protocolo. Obrigatório.

➡️ “pageNumber”: página. A 1 traz as mensagens mais recentes; cada página seguinte volta no tempo. Padrão 1.

➡️ “pageSize”: mensagens por página. Padrão 50, máximo 200.

Utilize o código em requisições HTTPS
curl "https://{SERVIDOR}/tickets/1024?pageNumber=1&pageSize=50" \
  -H "Authorization: Bearer {seutokenaqui}"
Resposta
{
  "ticket": { "id": 1024, "status": "open" },
  "messages": [
    {
      "id": "wamid.HBgMNTU2NTk5OTk5OTk5FQIAEhgg",
      "body": "",
      "fromMe": false,
      "mediaType": "audio",
      "mediaUrl": "https://object.exemplo.com.br/botdizzer/company3/1793049029479.opus",
      "read": true,
      "ack": 3,
      "contactId": 5120,
      "timestamp": "2026-10-27T13:02:11.000Z"
    }
  ],
  "count": 148,
  "pageNumber": 1,
  "pageSize": 50,
  "hasMore": true
}

➡️ “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:

mediaTypeConteúdoOnde ler
conversationMensagem de texto do chatbody
audioÁudio, nos formatos aceitos pelo WhatsApp (ex.: .opus)mediaUrl
documentArquivo, como PDF ou DOCXmediaUrl
imageImagemmediaUrl
videoVídeomediaUrl

💡 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.

Utilize o código em requisições HTTPS
curl "https://{SERVIDOR}/dadosticket/1024" \
  -H "Authorization: Bearer {seutokenaqui}"
Resposta
{
  "id": 1024,
  "status": "open",
  "unreadMessages": 1,
  "lastMessage": "Áudio",
  "isGroup": false,
  "userId": 12,
  "contactId": 5120,
  "whatsappId": 7,
  "queueId": 1,
  "channel": "whatsapp_meta",
  "companyId": 3,
  "createdAt": "2026-06-23T11:24:21.329Z",
  "updatedAt": "2026-10-27T21:07:49.151Z",
  "contact": {
    "id": 5120,
    "name": "Maria Exemplo da Silva",
    "number": "5565999999999",
    "email": "maria@exemplo.com.br",
    "cpfcnpj": "",
    "cidade": "",
    "extraInfo": [ { "id": 83, "name": "Observação", "value": "Cliente desde 2023" } ]
  },
  "user": { "id": 12, "name": "João Atendente" },
  "queue": { "id": 1, "name": "Dpto Fiscal" },
  "whatsapp": { "id": 7, "name": "Empresa-oficial", "channel": "whatsapp_meta", "status": "CONNECTED" },
  "tags": [],
  "company": { "id": 3, "name": "Empresa Exemplo Ltda" }
}

➡️ “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.

Endpoint
https://{SERVIDOR}/listatickets?status={status}&dataInicial={AAAA-MM-DD}&dataFinal={AAAA-MM-DD}&pageNumber={pagina}
Método
GET
Autenticação
Bearer {seutokenaqui}
Parâmetros

➡️ “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.

Utilize o código em requisições HTTPS
curl "https://{SERVIDOR}/listatickets?status=closed&dataInicial=2026-10-01&dataFinal=2026-10-28&pageNumber=1" \
  -H "Authorization: Bearer {seutokenaqui}"
Resposta
{
  "status": "closed",
  "dataInicial": "2026-10-01",
  "dataFinal": "2026-10-28",
  "pageNumber": 1,
  "hasMore": true,
  "count": 2,
  "tickets": [
    { "id": 1024, "status": "closed", "createdAt": "2026-09-23T13:30:46.755Z", "updatedAt": "2026-10-28T11:46:50.404Z" },
    { "id": 1031, "status": "closed", "createdAt": "2026-10-28T09:12:05.118Z", "updatedAt": "2026-10-28T12:12:22.412Z" }
  ]
}

➡️ “count”: quantidade de tickets nesta página, não o total.

➡️ “tickets[].id”: use em Dados do Ticket e Listar Mensagens do Ticket.

💡 Paginação

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.

Endpoint
https://{SERVIDOR}/tarefas?status={statusDaTarefa}&priority={priorityDaTarefa}&userId={userId}
Método
GET
Autenticação
Bearer {seutokenaqui}
Parâmetros

Todos são opcionais e vão na URL. Sem nenhum, vêm todas as tarefas da empresa.

➡️ “status”: pending (em aberto) ou completed (concluída).

➡️ “priority”: high, medium ou low.

➡️ “userId”: tarefas criadas por esse atendente, atribuídas a ele ou compartilhadas com ele.

➡️ “createdBy”: só as tarefas criadas por esse atendente.

➡️ “assignedTo”: só as tarefas atribuídas a esse atendente.

➡️ “sharedWith”: só as tarefas compartilhadas com esse atendente.

➡️ “ticketId”: só as tarefas vinculadas a esse atendimento. Combina com os outros filtros.

⚠️ Um filtro de atendente por vez

createdBy, assignedTo, sharedWith e userId não se somam. Vale o primeiro enviado, nessa ordem; os outros são ignorados sem aviso.

Utilize o código em requisições HTTPS
curl "https://{SERVIDOR}/tarefas?status=pending&priority=high&assignedTo=4" \
  -H "Authorization: Bearer {seutokenaqui}"
Resposta

A lista de tarefas, cada uma com os campos de Obter uma Tarefa, incluindo creator e assignee.

◽ status ou priority fora dos valores aceitos, ou um ID que não é número, retornam 400 com o nome do parâmetro.

APIs › Tarefas › API Obter uma Tarefa

API Obter uma Tarefa

GET

🔎 Obtém uma tarefa completa, com tudo o que a janela da tarefa mostra.

Endpoint
https://{SERVIDOR}/tarefas/{tarefaId}
Método
GET
Autenticação
Bearer {seutokenaqui}
Parâmetros

➡️ “tarefaId”: ID da tarefa, no próprio endereço, no lugar de {tarefaId}. Obrigatório.

Utilize o código em requisições HTTPS
curl "https://{SERVIDOR}/tarefas/55" \
  -H "Authorization: Bearer {seutokenaqui}"
Resposta

Campos da tarefa:

CampoDescrição
title, descriptionTítulo e descrição.
priorityhigh, medium ou low.
statuspending ou completed.
dueDate, startTime, endTimePrazo (ISO 8601) e horários de início e fim (HH:MM).
reminderMinutesLembrete, em minutos antes.
tipolembrete, reuniao, ligacao, email, visita ou tarefa.
sala, salaCodigo, meetingUrlDados da sala, na reunião.
isRecurring, recurringPatternSe a tarefa se repete, e com que frequência.
checklistItens, cada um com texto e feito.
responsaveisTodos os responsáveis, em ordem; o primeiro é o principal.
sharedWithAtendentes com quem a tarefa é compartilhada.
ticketId, crmOportunidadeId, projetoIdAtendimento, oportunidade de CRM e projeto vinculados.
creator, assigneeQuem 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.

Utilize o código em requisições HTTPS
curl -X PUT "https://{SERVIDOR}/tarefas/55" \
  -H "Authorization: Bearer {seutokenaqui}" \
  -H "Content-Type: application/json" \
  -d '{"priority":"high","assignedTo":4,"dueDate":"2028-12-30T23:59:59.000Z"}'
Resposta

A tarefa atualizada, com quem criou, o responsável e o atendimento vinculado.

APIs › Tarefas › API Finalizar Tarefa

API Finalizar Tarefa

POST

✅ Marca a tarefa como concluída. É o mesmo que concluir pela tela.

Endpoint
https://{SERVIDOR}/tarefas/{tarefaId}/finalizar
Método
POST
Autenticação
Bearer {seutokenaqui}
Payload
Sem payload

➡️ “tarefaId”: ID da tarefa, no próprio endereço. Obrigatório.

◽ Se a tarefa estiver no Google Agenda, ela sai da agenda.

Utilize o código em requisições HTTPS
curl -X POST "https://{SERVIDOR}/tarefas/55/finalizar" \
  -H "Authorization: Bearer {seutokenaqui}"
Resposta

A tarefa concluída, com quem criou e o responsável. Tarefa que não existe, ou que é de outra empresa, retorna “não encontrada”.

APIs › Tarefas › API Listar Comentários da Tarefa

API Listar Comentários da Tarefa

GET

🗨️ Obtém os comentários da tarefa, do mais novo para o mais antigo.

Endpoint
https://{SERVIDOR}/tarefas/{tarefaId}/comentarios
Método
GET
Autenticação
Bearer {seutokenaqui}
Parâmetros

➡️ “tarefaId”: ID da tarefa, no próprio endereço. Obrigatório.

Utilize o código em requisições HTTPS
curl "https://{SERVIDOR}/tarefas/55/comentarios" \
  -H "Authorization: Bearer {seutokenaqui}"
Resposta
[
  {
    "id": 301,
    "content": "Combinado com @[Maria Souza](17) para amanhã",
    "createdAt": "2026-11-18T14:02:11.000Z",
    "user": { "id": 4, "name": "João Atendente", "profile": "user" }
  }
]

➡️ “user”: autor do comentário, com id, name e profile.

◽ Menções aparecem no texto no formato @[Nome](id).

APIs › Tarefas › API Criar Comentário na Tarefa

API Criar Comentário na Tarefa

POST

✍️ Cria um comentário na tarefa, em nome de um atendente.

Endpoint
https://{SERVIDOR}/tarefas/{tarefaId}/comentarios?userId={userId}
Método
POST
Autenticação
Bearer {seutokenaqui}
Payload
{
  "content": "Cliente confirmou. @[Maria Souza](17), pode enviar a proposta."
}

➡️ “tarefaId”: ID da tarefa, no próprio endereço. Obrigatório.

➡️ “userId”: ID do atendente autor do comentário. Pode ir na URL ou no payload. Obrigatório.

➡️ “content”: texto do comentário. Obrigatório.

💡 Menções

Para mencionar alguém, escreva @[Nome](id), por exemplo @[Maria Souza](17). Os mencionados e quem acompanha a tarefa são avisados.

Utilize o código em requisições HTTPS
curl -X POST "https://{SERVIDOR}/tarefas/55/comentarios?userId=4" \
  -H "Authorization: Bearer {seutokenaqui}" \
  -H "Content-Type: application/json" \
  -d '{"content":"Cliente confirmou. @[Maria Souza](17), pode enviar a proposta."}'
Resposta
{
  "id": 302,
  "content": "Cliente confirmou. @[Maria Souza](17), pode enviar a proposta.",
  "createdAt": "2026-11-18T14:10:00.000Z",
  "user": { "id": 4, "name": "João Atendente" }
}
APIs › Tarefas › API Anexar Arquivo na Tarefa

API Anexar Arquivo na Tarefa

POST

📎 Anexa um arquivo do seu computador à tarefa, em nome de um atendente.

Endpoint
https://{SERVIDOR}/tarefas/{tarefaId}/anexos?userId={userId}
Método
POST
Autenticação
Bearer {seutokenaqui}
Payload
multipart/form-data
files = (arquivo)

➡️ “tarefaId”: ID da tarefa, no próprio endereço. Obrigatório.

➡️ “userId”: ID do atendente que anexa. Tem que ir na URL; no envio de arquivo, o userId no payload é ignorado. Obrigatório.

➡️ “files”: o arquivo. O nome do campo tem que ser exatamente files; files[0], files[] e file são recusados. Obrigatório.

◽ O tipo do arquivo (por exemplo application/pdf ou image/png) fica guardado no anexo. Informe-o no envio.

◽ Vários arquivos: faça uma chamada por arquivo, ou repita o campo files na mesma chamada. Cada arquivo vira um anexo.

⚠️ Não defina o Content-Type à mão

Deixe a biblioteca HTTP montar o multipart/form-data, porque ela inclui o boundary. O limite por chamada é de 20 MB, somando todos os arquivos.

Utilize o código em requisições HTTPS
curl -X POST "https://{SERVIDOR}/tarefas/55/anexos?userId=4" \
  -H "Authorization: Bearer {seutokenaqui}" \
  -F "files=@/caminho/proposta.pdf;type=application/pdf" \
  -F "files=@/caminho/foto.png;type=image/png"
Resposta
[
  {
    "id": 88,
    "nomeOriginal": "proposta.pdf",
    "url": "https://arquivos.exemplo.com.br/tarefas/55/proposta.pdf",
    "mimeType": "application/pdf",
    "tamanho": 184233
  }
]

➡️ “tamanho”: tamanho do arquivo, em bytes.