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

Mais Chat API (3.0.0)

Download OpenAPI specification:

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

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.

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.

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

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

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": [
    ]
}