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

Mais Chat API (3.3.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, filtrada pelo período de criação (startTime/endTime) e pelos campos do contato (tags, categoria, mês de aniversário, nome, celular, CPF/CNPJ e e-mail).

Todos os filtros são combináveis (E lógico / AND). Parâmetros desconhecidos ou com valores inválidos resultam em HTTP 400 — nunca são ignorados silenciosamente.

Observações:

  • O parâmetro limit possui limite máximo de 200 registros por requisição.
  • Caso seja informado um valor superior a 200, a requisição retorna erro 400.
  • O retorno inclui metadados como count (quantidade retornada) e countTotal (quantidade total de registros que atendem ao filtro).

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 10

Número máximo de registros retornados por requisição (mín. 1, máx. 200).

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.

name
string

Nome do contato (busca parcial, case-insensitive).

mobile
string

Número de celular (busca com e sem o nono dígito).

cpfCnpj
string

CPF ou CNPJ (com ou sem máscara).

email
string

E-mail do contato (busca parcial, case-insensitive).

tag
string

Uma ou mais tags de contato (ObjectId), separadas por vírgula. Ex.: id1,id2.

category
string
Enum: "PF" "PJ"

Categoria do contato — PF (pessoa física) ou PJ (pessoa jurídica).

birthMonth
integer [ 1 .. 12 ]

Mês de aniversário (1 a 12), derivado da data de nascimento.

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.

Todos os filtros são combináveis (E lógico / AND). Parâmetros desconhecidos ou com valores inválidos resultam em HTTP 400 — nunca são ignorados silenciosamente.

Limite de requisições (rate limit):

  • Máximo de 15 requisições a cada 5 segundos.
Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 10

Número máximo de registros retornados por requisição (mín. 1, máx. 200).

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 (aberto/fechado).

situation
string^[0-9a-fA-F]{24}$

Situação configurável do protocolo (ObjectId de uma situação cadastrada). Diferente de state (que trata apenas de aberto/fechado). Consulte os IDs disponíveis em GET /reason.

motive
string^[0-9a-fA-F]{24}$

Motivo de encerramento (ObjectId). Consulte os IDs disponíveis em GET /reason/motives.

attendanceState
string
Enum: "bot" "queue" "attendant"

Estado do atendimento:

  • bot: em atendimento automático;
  • queue: aguardando em fila;
  • attendant: em atendimento humano.
queue
string

Uma ou mais filas (ObjectId), separadas por vírgula. Ex.: id1,id2. Consulte os IDs disponíveis em GET /queue.

tag
string

Uma ou mais tags do protocolo (ObjectId), separadas por vírgula. Ex.: id1,id2.

contactName
string

Nome do contato (busca parcial, case-insensitive).

contactEmail
string

E-mail do contato (busca parcial, case-insensitive).

contactMobile
string

Celular do contato (busca parcial pelos dígitos).

attendant
string^[0-9a-fA-F]{24}$

Atendente (ObjectId do usuário).

role
string^[0-9a-fA-F]{24}$

Papel do atendente (ObjectId). Filtra protocolos de atendentes com esse papel.

channel
string

Canal do protocolo (ex.: wpp, web).

whatsappConnection
string

Conexão WhatsApp (número da conexão que originou o protocolo).

rating
string

Avaliação do atendimento.

receptive
boolean

Tipo de comunicação — true para receptivo, false para ativo.

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.

closeStartTime
string <date>

Data inicial de fechamento (YYYY-MM-DD). Se informado, closeEndTime também deve ser.

closeEndTime
string <date>

Data final de fechamento (YYYY-MM-DD). Se informado, closeStartTime também deve ser.

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": { }
}

Filas

Consulta de filas de atendimento (IDs para uso nos filtros de protocolos)

Listar filas de atendimento

Retorna as filas de atendimento do tenant, ordenadas por status (ativas primeiro) e nome. Use o _id retornado no filtro queue de GET /protocol.

Parâmetros desconhecidos ou com valores inválidos resultam em HTTP 400.

Limite de requisições (rate limit):

  • Máximo de 100 requisições a cada 1 minuto.
Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 10

Número máximo de registros retornados por requisição (mín. 1, máx. 200).

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.

status
boolean

true retorna apenas filas ativas; false, apenas inativas.

Responses

Response samples

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

Obter fila por ID

Retorna uma fila de atendimento pelo seu ID.

Limite de requisições (rate limit):

  • Máximo de 100 requisições a cada 1 minuto.
Authorizations:
bearerAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$

ObjectId da fila.

Responses

Response samples

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

Situações e Motivos

Consulta de situações e motivos de encerramento de protocolo (IDs para uso nos filtros)

Listar situações de protocolo

Retorna as situações de protocolo cadastradas (nível raiz), cada uma com seus motivos aninhados no campo childs (em ordem alfabética). Use o _id da situação no filtro situation e o _id do motivo no filtro motive de GET /protocol.

Parâmetros desconhecidos ou com valores inválidos resultam em HTTP 400.

Limite de requisições (rate limit):

  • Máximo de 100 requisições a cada 1 minuto.
Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 10

Número máximo de registros retornados por requisição (mín. 1, máx. 200).

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.

status
boolean

true retorna apenas registros ativos; false, apenas inativos.

Responses

Response samples

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

Listar motivos de encerramento

Retorna apenas os motivos (registros com situação-pai), com a situação populada em parent.

Parâmetros desconhecidos ou com valores inválidos resultam em HTTP 400.

Limite de requisições (rate limit):

  • Máximo de 100 requisições a cada 1 minuto.
Authorizations:
bearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 10

Número máximo de registros retornados por requisição (mín. 1, máx. 200).

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.

status
boolean

true retorna apenas registros ativos; false, apenas inativos.

search
string <= 60 characters

Busca parcial (case-insensitive) pelo nome do motivo.

reason
string^[0-9a-fA-F]{24}$

Restringe aos motivos de uma situação específica (ObjectId da situação).

Responses

Response samples

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

Obter situação/motivo por ID

Retorna uma situação ou motivo pelo seu ID. Quando for um motivo, a situação vem populada em parent.

Limite de requisições (rate limit):

  • Máximo de 100 requisições a cada 1 minuto.
Authorizations:
bearerAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$

ObjectId da situação ou motivo.

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
}