Mais Chat Docs API
Mais diálogos, mais negócios
API docs by Redocly

Mais Chat API (3.0.0)

Download OpenAPI specification:

Suporte Mais Chat: [email protected] URL: https://maischat.com License: Proprietary

Documentação pública da Mais Chat API.
API REST para uso restrito a clientes da Mais Chat.

🔑 Autenticação

Todas as chamadas exigem o header authorization no formato:

authorization: Bearer {{tenantToken}}
Content-Type: application/json

O tenantToken é exclusivo do cliente e deve ser solicitado ao Suporte Mais Chat.
Sem esse header a API responderá 401 Unauthorized.

⚠️ Limite de Requisições (Rate Limit)

Todas as rotas da API possuem rate limit para garantir a estabilidade do serviço.
Para detalhes sobre limites específicos ou aumento de capacidade, entre em contato com o Suporte Mais Chat.

Webhooks

Além da API REST, a Mais Chat envia eventos HTTP para endpoints configurados pelos clientes. Webhooks são contratos de eventos recebidos pelo servidor do cliente; eles não representam rotas REST da API Mais Chat.

Cada entrega é um POST com Content-Type: application/json, headers padrão e corpo no envelope:

{
  "event": "newProtocol",
  "entry": {},
  "timestamp": 1719320400000
}

Headers enviados:

  • X-Webhook-Event: nome do evento, igual ao campo event.
  • X-Webhook-Delivery: UUID da tentativa de entrega.
  • X-Webhook-Id: identificador do evento de origem, quando disponível, para idempotência.
  • X-Webhook-Signature: assinatura HMAC-SHA256 quando o webhook possui secret.

Quando há secret, o corpo bruto é assinado no formato sha256=HMAC_SHA256(secret, corpo_bruto). A validação deve usar o corpo bruto recebido, antes do parse JSON.

O endpoint do cliente deve responder 2xx para confirmar o recebimento. Respostas 4xx indicam rejeição definitiva. Respostas 5xx ou timeout são reprocessadas. Cada tentativa usa um novo X-Webhook-Delivery; o mesmo evento mantém o mesmo X-Webhook-Id, quando disponível.

Mensagens

Envio e consulta de mensagens

Listar mensagens de API enviadas por canal

Retorna a lista de mensagens enviadas pela API através de um canal específico (appId) ou número de origem associado.
A rota suporta paginação e permite consultar o histórico de mensagens enviadas, incluindo metadados sobre o envio, status de entrega (ack), payload da requisição e resposta do provedor (ex: WhatsApp Cloud API).

Cada item retornado representa uma mensagem enviada pelo sistema, com dados completos sobre:

  • Identificadores internos e externos (IDs do WhatsApp, appId, tenant).
  • Status de entrega e logs de confirmação (ack, ackLog).
  • Conteúdo e componentes da mensagem (texto, botões, rodapé).
  • Informações do remetente, destinatário e tenant.
  • Payload da requisição original enviada ao broker e a resposta recebida.

Limite de requisições (rate limit):

  • Máximo de 100 requisições a cada 1 minuto.
Authorizations:
bearerAuth
path Parameters
mobile
required
string

Identificador do canal (appId) ou número do remetente configurado no broker.

query Parameters
limit
integer
Default: 10
offset
integer
Default: 0
Example: offset=200

Número de registros a serem ignorados antes de iniciar a listagem.
Usado para paginação em conjunto com o parâmetro limit.

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": [
    ]
}

Listar mensagens por número de destino

Retorna a lista de mensagens enviadas pela API através do número de destino.

Limite de requisições (rate limit):

  • Máximo de 100 requisições a cada 1 minuto.
Authorizations:
bearerAuth
path Parameters
destination
required
string
query Parameters
limit
integer
Default: 10
offset
integer
Default: 0
Example: offset=200

Número de registros a serem ignorados antes de iniciar a listagem.
Usado para paginação em conjunto com o parâmetro limit.

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Templates

Gerenciamento e envio de templates

Listar templates cadastrados

Retorna a lista de templates cadastrados na Meta.

  • Meta Cloud API (WhatsApp): Informe appId via query para filtrar os templates do aplicativo específico (requisito da Meta).
  • O retorno é um array de templates com nome, idioma, status de aprovação, categoria e componentes (ex.: BODY com placeholders {{1}}, {{2}} etc).

Limite de requisições (rate limit):

  • Máximo de 10 requisições a cada 1 minuto.
Authorizations:
bearerAuth
path Parameters
broker
required
string
Value: "wppCloudAPI"
query Parameters
appId
required
string
Example: appId=123456789012345

Identificador do aplicativo na Meta Cloud API. Obrigatório quando broker=meta (ou equivalente) e a integração exigir app por escopo.

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": [
    ]
}

Envia mensagem de template

Envia uma mensagem de template (mensagem pré-aprovada pela Meta/WhatsApp) pelo broker Meta Cloud API. Templates são usados para iniciar ou retomar conversas fora da janela de 24h e para comunicações padronizadas (notificações, alertas, confirmações etc.). A propriedade template deve seguir obrigatoriamente o formato e as regras da documentação oficial da Meta: https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates. Apenas templates previamente aprovados e ativos podem ser utilizados.

Limite de requisições (rate limit):

  • Máximo de 500 requisições a cada 1 minuto.
Authorizations:
bearerAuth
path Parameters
broker
required
string
Value: "wppCloudAPI"
Request Body schema: application/json
required
One of
type
required
string
Value: "apiTemplate"

Tipo de operação; para Meta Cloud use sempre apiTemplate.

broker
required
string
Value: "wppCloudAPI"

Broker de envio; atualmente suportado: wppCloudAPI (Meta Cloud API).

appId
required
string

Phone Number ID do seu canal (número do WhatsApp Business na Meta).

source
required
string

Número do remetente (seu canal) em formato E.164 (ex.: 5511999991234).

destination
required
string

Número do destinatário em formato E.164 (ex.: 5511912341234).

token
required
string

Token do Graph API (Meta Cloud) com permissões para envio.

required
object

Dados do template conforme a documentação oficial da Meta: https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates. Deve referenciar um template aprovado e ativo na sua conta WhatsApp Business. Campos mínimos: - name: nome do template aprovado. - language: código no formato <lang>_<REGION> (ex.: pt_BR). - components: lista de componentes compatíveis (corpo, cabeçalho, mídia, botões, variáveis, ações como flow etc.) exatamente como definido no template aprovado.

Responses

Request samples

Content type
application/json
{
  • "type": "apiTemplate",
  • "broker": "wppCloudAPI",
  • "appId": "317774448096214",
  • "source": "5511999991234",
  • "destination": "5511912341234",
  • "token": "EAA...",
  • "template": {
    }
}

Response samples

Content type
application/json
{
  • "status": true,
  • "data": {
    }
}

Brokers

Informações sobre brokers conectados (status, lista)

Listar brokers configurados

Retorna a lista de brokers configurados na plataforma, incluindo dados técnicos e de identificação necessários para integração com os canais de mensagens.

Limite de requisições (rate limit):

  • Máximo de 10 requisições a cada 1 minuto.
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": [
    ]
}

Contatos

Consulta e cadastro de contatos

Listar contatos cadastrados

Retorna uma lista de contatos cadastrados na plataforma.
A listagem pode ser paginada com limit e offset, e filtrada pelo período de criação/atualização utilizando startTime e endTime.

Observações:

  • O parâmetro limit possui limite máximo de 1000 registros por requisição.
  • Caso seja informado um valor superior a 1000, automaticamente será considerado 1000.
  • O retorno inclui metadados como count (quantidade retornada) e countTotal (quantidade total de registros no banco).

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
query Parameters
limit
integer <= 1000
Default: 100

Número máximo de contatos a serem retornados por requisição (máx. 1000).

offset
integer
Default: 0
Example: offset=200

Número de registros a serem ignorados antes de iniciar a listagem.
Usado para paginação em conjunto com o parâmetro limit.

startTime
string <date>
Example: startTime=2023-03-01

Data inicial de cadastro do contato.
Se informado, endTime também deve ser informado.

endTime
string <date>
Example: endTime=2024-03-31

Data final de cadastro do contato.
Se informado, startTime também deve ser informado.

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": [
    ],
  • "count": 100,
  • "countTotal": 29034
}

Criar contato

Cria um novo contato na plataforma.

Detalhes:

  • É necessário informar pelo menos name e type.
  • O campo email deve ser válido quando informado.
  • As tags devem conter IDs válidos de tags previamente cadastradas.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.

Observações adicionais:

  • Em caso de duplicidade de celular, o sistema retornará erro 409.
  • As respostas seguem o padrão StandardResponse, com o objeto criado em data.
Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string
type
required
string

PF/PJ (case-insensitive)

cpf
string
celular
string
telefoneFixo
string
email
string <email>
departamento
string
funcao
string
Array of objects
tags
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "Fulana 5 de Tal",
  • "type": "pf",
  • "cpf": "813.844.599-87",
  • "celular": "48 98888-9999",
  • "telefoneFixo": "+34 654232147",
  • "email": "[email protected]",
  • "departamento": "Dep Teste",
  • "funcao": "Função teste",
  • "notes": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Obter contato por ID

Retorna dados do contato.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Atualizar contato parcialmente

Atualiza parcial de um contato existente. Todos os campos são opcionais.

Se o campo name for enviado, ele não pode ser vazio.

Se o campo tags for enviado, deve conter um array com IDs válidos de tags. E tais tags serão adicionadas ao contato (não substituem as existentes).

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string non-empty
type
string

PF/PJ (case-insensitive)

cpf
string
celular
string
telefoneFixo
string
email
string <email>
departamento
string
funcao
string
Array of objects
tags
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "Fulana de Tal (atualizado)",
  • "email": "[email protected]",
  • "notes": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Remover tags de contato

Remove tags de um contato existente.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
tags
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Obter contato por telefone celular

Retorna dados do contado onde a busca é pelo número de celular.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
path Parameters
cellphone
required
string

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Tags

Consulta de tags

Obter tag por ID

Retorna dados da TAG.

Limite de requisições (rate limit):

  • Máximo de 100 requisições a cada 1 minuto.
Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Listar todas as tags

Retorna lista de TAGs cadastradas no sistema.

Limite de requisições (rate limit):

  • Máximo de 100 requisições a cada 1 minuto.
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Protocolos

Consulta de protocolos e conversas

Listar protocolos

Retorna lista de protocolos.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
query Parameters
limit
integer
Default: 10
offset
integer
Default: 0
Example: offset=200

Número de registros a serem ignorados antes de iniciar a listagem.
Usado para paginação em conjunto com o parâmetro limit.

state
string
Enum: "open" "closed"

Filtrar por estado do protocolo

startTime
string <date>
Example: startTime=2023-03-01

Data inicial de cadastro do contato.
Se informado, endTime também deve ser informado.

endTime
string <date>
Example: endTime=2024-03-31

Data final de cadastro do contato.
Se informado, startTime também deve ser informado.

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Obter protocolo e mensagens

Retorna os dados de um protocolo e a lista de mensagens relacionadas. Use este endpoint para inspecionar o histórico de atendimento (bot e humano), filas, tags e motivos de encerramento.

Limite de requisições (rate limit):

  • Máximo de 100 requisições a cada 1 minuto.

Observações:

  • O campo messages é retornado em ordem cronológica crescente (mais antigo → mais recente).
  • Os horários estão em ISO 8601 (UTC).
Authorizations:
bearerAuth
path Parameters
protocolNumber
required
string
Example: 17585415876230366

Número do protocolo (string numérica gerada pelo sistema).

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": {
    }
}

Listar protocolos abertos por número alvo

Retorna protocolos abertos onde o número alvo é o número de WhatsApp usado na conversa.

Limite de requisições (rate limit):

  • Máximo de 100 requisições a cada 1 minuto.
Authorizations:
bearerAuth
path Parameters
phoneNumber
required
string

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Boards

Gerenciamento de boards de tarefas

Listar boards

Retorna a lista de boards do tenant autenticado.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
query Parameters
limit
integer
Default: 10
offset
integer
Default: 0
Example: offset=200

Número de registros a serem ignorados antes de iniciar a listagem.
Usado para paginação em conjunto com o parâmetro limit.

closed
boolean

Filtrar boards abertos/fechados.

state
string

Filtrar por estado do board.

name
string

Filtrar por nome com busca parcial.

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": [
    ],
  • "count": 1,
  • "countTotal": 1
}

Criar board

Cria um novo board para o tenant autenticado.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string [ 3 .. 120 ] characters
description
string <= 500 characters
closed
boolean
state
string
object
members
Array of strings
Array of objects
tags
Array of strings
createdUser
string
updatedUser
string

Responses

Request samples

Content type
application/json
{
  • "name": "Operacao Comercial",
  • "description": "Board para acompanhar o funil comercial",
  • "state": "ABERTO",
  • "prefs": {
    },
  • "members": [
    ],
  • "memberships": [
    ],
  • "tags": [
    ],
  • "createdUser": "67c8a5d4f31a2b0012345678"
}

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Obter board por ID

Retorna os dados de um board específico.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Atualizar board parcialmente

Atualiza parcialmente um board existente.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string [ 3 .. 120 ] characters
description
string <= 500 characters
closed
boolean
state
string
object
members
Array of strings
Array of objects
tags
Array of strings
updatedUser
string
closedUser
string
closedAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "name": "Operacao Comercial BR",
  • "description": "Board atualizado para o time Brasil",
  • "updatedUser": "67c8a5d4f31a2b0012345678",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

TaskList

Gerenciamento de listas de tarefas vinculadas a um board

Listar taskLists por board

Retorna as taskLists do tenant autenticado, sempre filtradas por board.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
query Parameters
limit
integer
Default: 10
offset
integer
Default: 0
Example: offset=200

Número de registros a serem ignorados antes de iniciar a listagem.
Usado para paginação em conjunto com o parâmetro limit.

board
required
string

ID do board dono das taskLists.

closed
boolean

Filtrar taskLists abertas/fechadas.

name
string

Filtrar por nome com busca parcial.

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": [
    ],
  • "count": 1,
  • "countTotal": 1
}

Criar taskList

Cria uma nova taskList vinculada a um board. Se position não for enviada, a API usa a maior posição atual do board e soma +1.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string [ 2 .. 120 ] characters
board
required
string
position
integer >= 0
closed
boolean
createdUser
string
updatedUser
string

Responses

Request samples

Content type
application/json
{
  • "name": "Novos Leads",
  • "board": "67c8b1f0f31a2b0012345801",
  • "createdUser": "67c8a5d4f31a2b0012345678"
}

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Obter taskList por ID

Retorna os dados de uma taskList específica.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Atualizar taskList parcialmente

Atualiza parcialmente uma taskList existente.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string [ 2 .. 120 ] characters
board
string
position
integer >= 0
closed
boolean
updatedUser
string

Responses

Request samples

Content type
application/json
{
  • "name": "Leads Qualificados",
  • "board": "67c8b1f0f31a2b0012345801",
  • "position": 1,
  • "updatedUser": "67c8a5d4f31a2b0012345678"
}

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Tasks

Gerenciamento de tasks vinculadas a uma taskList

Listar tasks por taskList

Retorna as tasks do tenant autenticado, sempre filtradas por list.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
query Parameters
limit
integer
Default: 10
offset
integer
Default: 0
Example: offset=200

Número de registros a serem ignorados antes de iniciar a listagem.
Usado para paginação em conjunto com o parâmetro limit.

list
required
string

ID da taskList dona das tasks.

protocol
string
contact
string
state
string
status
string
closed
boolean
title
string

Filtrar por título com busca parcial.

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": [
    ],
  • "count": 1,
  • "countTotal": 1
}

Criar task

Cria uma nova task vinculada a uma taskList e ao board correspondente. Se position não for enviada, a API usa a maior posição atual da taskList e soma +1.

Validações adicionais:

  • deadline, quando enviada, deve conter uma data válida.
  • deadline aceita YYYY-MM-DD ou date-time em ISO 8601.
  • deadline: null remove o valor atual.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
Request Body schema: application/json
required
title
required
string [ 3 .. 160 ] characters
description
string <= 2000 characters
board
required
string
list
required
string
position
integer >= 0
state
string
status
string
closed
boolean
priority
string
Enum: "Baixa" "Média" "Alta" "Crítica"
string or string or null (TaskDeadlineField)
protocol
string or null
contact
string or null
companies
Array of strings
tags
Array of strings
responsible
string or null
participants
Array of strings
Array of objects (TaskNote)
closeBoard
boolean
createdUser
string
updatedUser
string

Responses

Request samples

Content type
application/json
{
  • "title": "Entrar em contato com cliente premium",
  • "description": "Priorizar contato via WhatsApp no inicio da tarde",
  • "board": "67c8b1f0f31a2b0012345801",
  • "list": "67c8b2b8f31a2b0012345802",
  • "priority": "Alta",
  • "status": "open",
  • "state": "ABERTO",
  • "contact": "67c8b3def31a2b0012345803",
  • "protocol": "67c8b45af31a2b0012345804",
  • "responsible": "67c8a5d4f31a2b0012345678",
  • "participants": [
    ],
  • "tags": [
    ],
  • "notes": [
    ],
  • "deadline": "2026-03-20",
  • "createdUser": "67c8a5d4f31a2b0012345678"
}

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Obter task por ID

Retorna os dados de uma task específica.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Atualizar task parcialmente

Atualiza parcialmente uma task existente.

Validações adicionais:

  • deadline, quando enviada, deve conter uma data válida.
  • deadline aceita YYYY-MM-DD, date-time ISO 8601, null ou string vazia para limpeza.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
title
string [ 3 .. 160 ] characters
description
string <= 2000 characters
board
string
list
string
position
integer >= 0
state
string
status
string
closed
boolean
priority
string
Enum: "Baixa" "Média" "Alta" "Crítica"
string or string or string or null

Aceita YYYY-MM-DD, date-time ISO 8601, null ou string vazia para limpar o valor.

protocol
string or null
contact
string or null
companies
Array of strings
tags
Array of strings
responsible
string or null
participants
Array of strings
Array of objects (TaskNote)
closeBoard
boolean
updatedUser
string
closedUser
string
closedAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "title": "Retornar cliente premium",
  • "description": "Contato reagendado para o fim da tarde",
  • "board": "67c8b1f0f31a2b0012345801",
  • "list": "67c8b2b8f31a2b0012345802",
  • "position": 2,
  • "priority": "Crítica",
  • "deadline": "2026-03-20T18:00:00.000Z",
  • "updatedUser": "67c8a61ef31a2b0012345680"
}

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Remover task

Remove uma task existente.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Usuários

Listagem de usuários

Listar usuários

Retorna lista de usuários cadastrados.

Limite de requisições (rate limit):

  • Máximo de 20 requisições a cada 1 minuto.
Authorizations:
bearerAuth
query Parameters
limit
integer <= 1000
Default: 10

Máximo 1000 (default 10). Ordenação por nome asc.

offset
integer
Default: 0

Registros a pular

ativo
boolean

Filtrar por status (true/false)

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "data": { }
}

Uso

Métricas de uso da API

Métricas de uso

Esta rota retorna métricas de uso da API em nível de tenant, rota ou identidade. É possível filtrar por período (dia/mês), intervalo de datas, rotas, status HTTP, método de requisição e tipo de identidade.

Limite de requisições (rate limit):

  • Máximo de 10 requisições a cada 1 minuto.
Authorizations:
bearerAuth
query Parameters
period
required
string
Enum: "day" "month"
Example: period=month
start
required
string <date>
Example: start=2025-09-01

Data inicial (AAAA-MM-DD)

end
required
string <date>
Example: end=2025-09-30

Data final (AAAA-MM-DD)

routeContains
string
Example: routeContains=/msg/template
statusClass
string
Enum: "2xx" "4xx" "5xx"
Example: statusClass=2xx
identityType
string
Example: identityType=tenant
identityValue
string
Example: identityValue=5deab0f9b7a6ac4236b5a179
method
string
Enum: "GET" "POST" "PATCH"
Example: method=POST
sort
string
Example: sort=countTotal:-1
page
integer
Default: 1
Example: page=1
limit
integer
Default: 20
Example: limit=20

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "filters": {
    },
  • "totals": {
    },
  • "data": [
    ]
}

Webhooks

Contratos dos eventos HTTP enviados pela Mais Chat para endpoints configurados pelos clientes.

Webhooks são enviados para endpoints HTTP configurados pelo cliente. Cada entrega é um POST com corpo JSON no envelope padrão:

{
  "event": "newProtocol",
  "entry": {},
  "timestamp": 1719320400000
}

Campos do envelope:

  • event: nome do evento enviado.
  • entry: conteúdo específico do evento.
  • timestamp: epoch em milissegundos do momento de montagem do envelope.

Headers padrão:

  • Content-Type: sempre application/json.
  • X-Webhook-Event: nome do evento enviado.
  • X-Webhook-Delivery: UUID da tentativa de entrega.
  • X-Webhook-Id: identificador do evento de origem, quando disponível, para idempotência.
  • X-Webhook-Signature: assinatura HMAC-SHA256 quando há secret.

Retry e idempotência:

  • Responda 2xx para confirmar recebimento.
  • Respostas 4xx indicam rejeição definitiva e não são reprocessadas.
  • Respostas 5xx ou timeout são reprocessadas.
  • Cada tentativa possui novo X-Webhook-Delivery.
  • O mesmo evento mantém o mesmo X-Webhook-Id, quando disponível.
  • Use X-Webhook-Id como chave de idempotência.

Eventos disponíveis:

  • Protocolo: newProtocol, closedProtocol, queueProtocol, transferProtocol, tagsProtocol.
  • Contato: newContact, updateContact.
  • Sistêmicos: validacao, edicao.

Receber evento newProtocol Webhook

Evento enviado quando um protocolo é aberto.

Authorizations:
bearerAuth
header Parameters
X-Webhook-Event
required
string
Enum: "newProtocol" "closedProtocol" "queueProtocol" "transferProtocol" "tagsProtocol" "newContact" "updateContact" "validacao" "edicao"

Nome do evento enviado, igual ao campo event do corpo.

X-Webhook-Delivery
required
string <uuid>

UUID da tentativa de entrega. Cada retry recebe um novo valor.

X-Webhook-Id
string

Identificador do evento de origem, quando disponível. Use como chave de idempotência.

X-Webhook-Signature
string^sha256=.+$

Assinatura sha256=<hmac> do corpo bruto, enviada quando o webhook possui secret.

Request Body schema: application/json
required

Envelope JSON do evento newProtocol.

event
required
string

Nome do evento enviado.

Value: "newProtocol"
required
object

Conteúdo específico do evento.

timestamp
required
integer <int64>

Epoch em milissegundos do momento de montagem do envelope.

Responses

Request samples

Content type
application/json
{
  • "event": "newProtocol",
  • "entry": {
    },
  • "timestamp": 1719320460000
}

Receber evento queueProtocol Webhook

Evento enviado quando um protocolo entra em uma fila. Usa o mesmo formato de entry de newProtocol.

Authorizations:
bearerAuth
header Parameters
X-Webhook-Event
required
string
Enum: "newProtocol" "closedProtocol" "queueProtocol" "transferProtocol" "tagsProtocol" "newContact" "updateContact" "validacao" "edicao"

Nome do evento enviado, igual ao campo event do corpo.

X-Webhook-Delivery
required
string <uuid>

UUID da tentativa de entrega. Cada retry recebe um novo valor.

X-Webhook-Id
string

Identificador do evento de origem, quando disponível. Use como chave de idempotência.

X-Webhook-Signature
string^sha256=.+$

Assinatura sha256=<hmac> do corpo bruto, enviada quando o webhook possui secret.

Request Body schema: application/json
required

Envelope JSON do evento queueProtocol.

event
required
string

Nome do evento enviado.

Value: "queueProtocol"
required
object

Conteúdo específico do evento.

timestamp
required
integer <int64>

Epoch em milissegundos do momento de montagem do envelope.

Responses

Request samples

Content type
application/json
{
  • "event": "queueProtocol",
  • "entry": {
    },
  • "timestamp": 1719320405000
}

Receber evento transferProtocol Webhook

Evento enviado quando um protocolo é transferido para outra fila ou usuário. Usa o mesmo formato de entry de newProtocol.

Authorizations:
bearerAuth
header Parameters
X-Webhook-Event
required
string
Enum: "newProtocol" "closedProtocol" "queueProtocol" "transferProtocol" "tagsProtocol" "newContact" "updateContact" "validacao" "edicao"

Nome do evento enviado, igual ao campo event do corpo.

X-Webhook-Delivery
required
string <uuid>

UUID da tentativa de entrega. Cada retry recebe um novo valor.

X-Webhook-Id
string

Identificador do evento de origem, quando disponível. Use como chave de idempotência.

X-Webhook-Signature
string^sha256=.+$

Assinatura sha256=<hmac> do corpo bruto, enviada quando o webhook possui secret.

Request Body schema: application/json
required

Envelope JSON do evento transferProtocol.

event
required
string

Nome do evento enviado.

Value: "transferProtocol"
required
object

Conteúdo específico do evento.

timestamp
required
integer <int64>

Epoch em milissegundos do momento de montagem do envelope.

Responses

Request samples

Content type
application/json
{
  • "event": "transferProtocol",
  • "entry": {
    },
  • "timestamp": 1719320460000
}

Receber evento tagsProtocol Webhook

Evento enviado quando as tags de um protocolo são alteradas. Usa o mesmo formato de entry de newProtocol.

Authorizations:
bearerAuth
header Parameters
X-Webhook-Event
required
string
Enum: "newProtocol" "closedProtocol" "queueProtocol" "transferProtocol" "tagsProtocol" "newContact" "updateContact" "validacao" "edicao"

Nome do evento enviado, igual ao campo event do corpo.

X-Webhook-Delivery
required
string <uuid>

UUID da tentativa de entrega. Cada retry recebe um novo valor.

X-Webhook-Id
string

Identificador do evento de origem, quando disponível. Use como chave de idempotência.

X-Webhook-Signature
string^sha256=.+$

Assinatura sha256=<hmac> do corpo bruto, enviada quando o webhook possui secret.

Request Body schema: application/json
required

Envelope JSON do evento tagsProtocol.

event
required
string

Nome do evento enviado.

Value: "tagsProtocol"
required
object

Conteúdo específico do evento.

timestamp
required
integer <int64>

Epoch em milissegundos do momento de montagem do envelope.

Responses

Request samples

Content type
application/json
{
  • "event": "tagsProtocol",
  • "entry": {
    },
  • "timestamp": 1719320460000
}

Receber evento closedProtocol Webhook

Evento enviado no encerramento de um protocolo. Adiciona motivo, data de encerramento e mensagens normalizadas.

Authorizations:
bearerAuth
header Parameters
X-Webhook-Event
required
string
Enum: "newProtocol" "closedProtocol" "queueProtocol" "transferProtocol" "tagsProtocol" "newContact" "updateContact" "validacao" "edicao"

Nome do evento enviado, igual ao campo event do corpo.

X-Webhook-Delivery
required
string <uuid>

UUID da tentativa de entrega. Cada retry recebe um novo valor.

X-Webhook-Id
string

Identificador do evento de origem, quando disponível. Use como chave de idempotência.

X-Webhook-Signature
string^sha256=.+$

Assinatura sha256=<hmac> do corpo bruto, enviada quando o webhook possui secret.

Request Body schema: application/json
required

Envelope JSON do evento closedProtocol.

event
required
string

Nome do evento enviado.

Value: "closedProtocol"
required
object (ClosedProtocolEntry)

Conteúdo específico do evento.

timestamp
required
integer <int64>

Epoch em milissegundos do momento de montagem do envelope.

Responses

Request samples

Content type
application/json
{
  • "event": "closedProtocol",
  • "entry": {
    },
  • "timestamp": 1719322200000
}

Receber evento newContact Webhook

Evento enviado quando um contato é criado.

Authorizations:
bearerAuth
header Parameters
X-Webhook-Event
required
string
Enum: "newProtocol" "closedProtocol" "queueProtocol" "transferProtocol" "tagsProtocol" "newContact" "updateContact" "validacao" "edicao"

Nome do evento enviado, igual ao campo event do corpo.

X-Webhook-Delivery
required
string <uuid>

UUID da tentativa de entrega. Cada retry recebe um novo valor.

X-Webhook-Id
string

Identificador do evento de origem, quando disponível. Use como chave de idempotência.

X-Webhook-Signature
string^sha256=.+$

Assinatura sha256=<hmac> do corpo bruto, enviada quando o webhook possui secret.

Request Body schema: application/json
required

Envelope JSON do evento newContact.

event
required
string

Nome do evento enviado.

Value: "newContact"
required
object

Conteúdo específico do evento.

timestamp
required
integer <int64>

Epoch em milissegundos do momento de montagem do envelope.

Responses

Request samples

Content type
application/json
{
  • "event": "newContact",
  • "entry": {
    },
  • "timestamp": 1719319800000
}

Receber evento updateContact Webhook

Evento enviado quando um contato é atualizado. Usa o mesmo formato de entry de newContact.

Authorizations:
bearerAuth
header Parameters
X-Webhook-Event
required
string
Enum: "newProtocol" "closedProtocol" "queueProtocol" "transferProtocol" "tagsProtocol" "newContact" "updateContact" "validacao" "edicao"

Nome do evento enviado, igual ao campo event do corpo.

X-Webhook-Delivery
required
string <uuid>

UUID da tentativa de entrega. Cada retry recebe um novo valor.

X-Webhook-Id
string

Identificador do evento de origem, quando disponível. Use como chave de idempotência.

X-Webhook-Signature
string^sha256=.+$

Assinatura sha256=<hmac> do corpo bruto, enviada quando o webhook possui secret.

Request Body schema: application/json
required

Envelope JSON do evento updateContact.

event
required
string

Nome do evento enviado.

Value: "updateContact"
required
object

Conteúdo específico do evento.

timestamp
required
integer <int64>

Epoch em milissegundos do momento de montagem do envelope.

Responses

Request samples

Content type
application/json
{
  • "event": "updateContact",
  • "entry": {
    },
  • "timestamp": 1719321000000
}

Receber evento validacao Webhook

Handshake enviado ao cadastrar ou revalidar a URL do webhook.

Authorizations:
bearerAuth
header Parameters
X-Webhook-Event
required
string
Enum: "newProtocol" "closedProtocol" "queueProtocol" "transferProtocol" "tagsProtocol" "newContact" "updateContact" "validacao" "edicao"

Nome do evento enviado, igual ao campo event do corpo.

X-Webhook-Delivery
required
string <uuid>

UUID da tentativa de entrega. Cada retry recebe um novo valor.

X-Webhook-Id
string

Identificador do evento de origem, quando disponível. Use como chave de idempotência.

X-Webhook-Signature
string^sha256=.+$

Assinatura sha256=<hmac> do corpo bruto, enviada quando o webhook possui secret.

Request Body schema: application/json
required

Envelope JSON do evento sistêmico validacao.

event
required
string
Enum: "validacao" "edicao"

Nome do evento enviado.

required
object

Conteúdo específico do evento.

timestamp
required
integer <int64>

Epoch em milissegundos do momento de montagem do envelope.

Responses

Request samples

Content type
application/json
{
  • "event": "validacao",
  • "entry": {
    },
  • "timestamp": 1719319000000
}

Receber evento edicao Webhook

Notificação best-effort enviada ao salvar uma edição do webhook.

Authorizations:
bearerAuth
header Parameters
X-Webhook-Event
required
string
Enum: "newProtocol" "closedProtocol" "queueProtocol" "transferProtocol" "tagsProtocol" "newContact" "updateContact" "validacao" "edicao"

Nome do evento enviado, igual ao campo event do corpo.

X-Webhook-Delivery
required
string <uuid>

UUID da tentativa de entrega. Cada retry recebe um novo valor.

X-Webhook-Id
string

Identificador do evento de origem, quando disponível. Use como chave de idempotência.

X-Webhook-Signature
string^sha256=.+$

Assinatura sha256=<hmac> do corpo bruto, enviada quando o webhook possui secret.

Request Body schema: application/json
required

Envelope JSON do evento sistêmico edicao.

event
required
string
Enum: "validacao" "edicao"

Nome do evento enviado.

required
object

Conteúdo específico do evento.

timestamp
required
integer <int64>

Epoch em milissegundos do momento de montagem do envelope.

Responses

Request samples

Content type
application/json
{
  • "event": "edicao",
  • "entry": {
    },
  • "timestamp": 1719319000000
}