Download OpenAPI specification:
Documentação pública da Mais Chat API.
API REST para uso restrito a clientes da Mais Chat.
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.
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.
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:
Limite de requisições (rate limit):
| mobile required | string Identificador do canal (appId) ou número do remetente configurado no broker. |
| limit | integer Default: 10 |
| offset | integer Default: 0 Example: offset=200 Número de registros a serem ignorados antes de iniciar a listagem. |
{- "status": true,
- "data": [
- {
- "_id": "abc1234567890fakeid",
- "type": "wppCloudAPI",
- "from": "55999998888",
- "to": "5541999887766",
- "message": "Olá João, seu pedido #12345 foi confirmado!",
- "ack": "2",
- "ackLog": [
- {
- "ack": "1",
- "createdAt": "2025-09-23T10:00:00.000Z"
}, - {
- "ack": "2",
- "createdAt": "2025-09-23T10:01:10.000Z"
}
], - "components": [
- {
- "type": "BODY",
- "text": "Olá João, seu pedido #12345 foi confirmado!"
}, - {
- "type": "FOOTER",
- "text": "Obrigado por comprar conosco!"
}, - {
- "type": "BUTTONS",
- "buttons": [
- {
- "type": "text",
- "text": "Ver detalhes",
- "sub_type": "url",
- "index": "0",
- "buttonText": "Acompanhar pedido",
}
]
}
], - "payload": {
- "request": {
- "type": "apiTemplate",
- "broker": "wppCloudAPI",
- "appId": "111111111111111",
- "source": "55999998888",
- "destination": "5541999887766",
- "template": {
- "name": "pedido_confirmado",
- "language": "pt_BR",
- "components": [
- {
- "type": "body",
- "parameters": [
- {
- "type": "text",
- "text": "12345"
}
]
}
]
}
}, - "response": {
- "messaging_product": "whatsapp",
- "contacts": [
- {
- "input": "5541999887766",
- "wa_id": "5541999887766"
}
], - "messages": [
- {
- "id": "wamid.fakeMessageId123",
- "message_status": "accepted"
}
]
}
}, - "tenant": {
- "_id": "fakeTenantId123",
- "name": "Loja Exemplo",
- "id": "fakeTenantId123"
}, - "createdAt": "2025-09-23T10:00:00.000Z",
- "updatedAt": "2025-09-23T10:01:10.000Z"
}
]
}Retorna a lista de mensagens enviadas pela API através do número de destino.
Limite de requisições (rate limit):
| destination required | string |
| limit | integer Default: 10 |
| offset | integer Default: 0 Example: offset=200 Número de registros a serem ignorados antes de iniciar a listagem. |
{- "status": true,
- "data": { }
}Retorna a lista de templates cadastrados na Meta.
appId via query para filtrar os templates do aplicativo específico (requisito da Meta).{{1}}, {{2}} etc).Limite de requisições (rate limit):
| broker required | string Value: "wppCloudAPI" |
| appId required | string Example: appId=123456789012345 Identificador do aplicativo na Meta Cloud API. Obrigatório quando |
{- "status": true,
- "data": [
- {
- "name": "saudacao",
- "parameter_format": "POSITIONAL",
- "components": [
- {
- "type": "BODY",
- "text": "Olá {{1}}, me chamo {{2}} da Mais Chat.",
- "example": {
- "body_text": [
- [
- "João",
- "Maria"
]
]
}
}
], - "language": "pt_BR",
- "status": "APPROVED",
- "category": "MARKETING",
- "id": "1511471309205472"
}
]
}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):
| broker required | string Value: "wppCloudAPI" |
| type required | string Value: "apiTemplate" Tipo de operação; para Meta Cloud use sempre |
| broker required | string Value: "wppCloudAPI" Broker de envio; atualmente suportado: |
| 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: - |
{- "type": "apiTemplate",
- "broker": "wppCloudAPI",
- "appId": "317774448096214",
- "source": "5511999991234",
- "destination": "5511912341234",
- "token": "EAA...",
- "template": {
- "name": "flow_meta_2",
- "language": "pt_BR",
- "components": [
- {
- "type": "header",
}, - {
- "type": "body",
- "parameters": [
- {
- "type": "text",
- "text": "João"
}
]
}, - {
- "type": "button",
- "sub_type": "flow",
- "index": "0",
- "parameters": [
- {
- "type": "action",
- "action": {
- "flow_token": "{\"flowId\": 3293039314163350}"
}
}
]
}
]
}
}{- "status": true,
- "data": {
- "messaging_product": "whatsapp",
- "contacts": [
- {
- "input": "5511912341234",
- "wa_id": "5511912341234"
}
], - "messages": [
- {
- "id": "wamid.HBgMNTU0ODg4MTU2NTg2FQIAERgSQjQ3MzM1QUZGRDlDMkQxNTkyAA==",
- "message_status": "accepted"
}
], - "msgId": "66be3b896671d540a47be362"
}
}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):
{- "status": true,
- "data": [
- {
- "version": null,
- "_id": "65eb2a5529408895f2afc3da",
- "broker": "wppCloudAPI",
- "name": "Exemplo - Cloud",
- "app": "Exemplo Tecnologia",
- "appId": "234057352740299",
- "wabaId": "267173379104556",
- "number": "5511912341234",
- "token": "EAA..."
}
]
}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:
limit possui limite máximo de 1000 registros por requisição.count (quantidade retornada) e countTotal (quantidade total de registros no banco).Limite de requisições (rate limit):
| 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. |
| startTime | string <date> Example: startTime=2023-03-01 Data inicial de cadastro do contato. |
| endTime | string <date> Example: endTime=2024-03-31 Data final de cadastro do contato. |
{- "status": true,
- "data": [
- {
- "linked": [ ],
- "externalCode": null,
- "countryCode": "55",
- "tags": [
- {
- "_id": "5f91c4a9fccea6157cf2f",
- "tag": "NOVO"
}, - {
- "_id": "5f1e829f48cb380741e5cecd",
- "tag": "LEAD"
}
], - "_id": "68d215cd92eeb37882463a09",
- "name": "Pedro Augusto",
- "celular": "11912341234",
- "notes": [
- {
- "_id": "68d215cd79eeb3278d461a01",
- "type": "text",
- "date": "2025-09-23T03:36:45.124Z",
- "text": "<div><b>Contato cadastrado automaticamente</b></div><p>Este contato foi cadastrado automaticamente pelo canal WhatsApp Business.</p>"
}
], - "createdAt": "2025-09-23T03:36:45.138Z",
- "updatedAt": "2025-09-23T03:36:45.625Z",
- "address": [ ],
- "id": "68d2895cd79eeb37222425a03"
}
], - "count": 100,
- "countTotal": 29034
}Cria um novo contato na plataforma.
Detalhes:
name e type.email deve ser válido quando informado.tags devem conter IDs válidos de tags previamente cadastradas.Limite de requisições (rate limit):
Observações adicionais:
409.StandardResponse, com o objeto criado em data.| name required | string |
| type required | string PF/PJ (case-insensitive) |
| cpf | string |
| celular | string |
| telefoneFixo | string |
string <email> | |
| departamento | string |
| funcao | string |
Array of objects | |
| tags | Array of strings |
{- "name": "Fulana 5 de Tal",
- "type": "pf",
- "cpf": "813.844.599-87",
- "celular": "48 98888-9999",
- "telefoneFixo": "+34 654232147",
- "departamento": "Dep Teste",
- "funcao": "Função teste",
- "notes": [
- {
- "type": "text",
- "text": "Cadastro automático via formulário"
}, - {
- "type": "text",
- "text": "Modelo de interesse xxxx"
}
], - "tags": [
- "5e42ab48a61cfa56d01c508e",
- "60c0cd228e0e1d4a5d68d26a"
]
}{- "status": true,
- "data": { }
}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):
| id required | string |
| name | string non-empty |
| type | string PF/PJ (case-insensitive) |
| cpf | string |
| celular | string |
| telefoneFixo | string |
string <email> | |
| departamento | string |
| funcao | string |
Array of objects | |
| tags | Array of strings |
{- "name": "Fulana de Tal (atualizado)",
- "notes": [
- {
- "type": "text",
- "text": "Ajuste de cadastro pelo time comercial"
}
], - "tags": [
- "60c0cd228e0e1d4a5d68d26a"
]
}{- "status": true,
- "data": { }
}Retorna dados do contado onde a busca é pelo número de celular.
Limite de requisições (rate limit):
| cellphone required | string |
{- "status": true,
- "data": { }
}Retorna lista de protocolos.
Limite de requisições (rate limit):
| limit | integer Default: 10 |
| offset | integer Default: 0 Example: offset=200 Número de registros a serem ignorados antes de iniciar a listagem. |
| state | string Enum: "open" "closed" Filtrar por estado do protocolo |
| startTime | string <date> Example: startTime=2023-03-01 Data inicial de cadastro do contato. |
| endTime | string <date> Example: endTime=2024-03-31 Data final de cadastro do contato. |
{- "status": true,
- "data": { }
}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):
Observações:
messages é retornado em ordem cronológica crescente (mais antigo → mais recente).| protocolNumber required | string Example: 17585415876230366 Número do protocolo (string numérica gerada pelo sistema). |
{- "status": true,
- "data": {
- "_id": "6ab13713fab6bcd272025a00",
- "channel": "web",
- "channelNumber": null,
- "chatId": null,
- "protocol_number": "17585415876230366",
- "attendant": {
- "_id": "6ab198a96054aa45422ba100",
- "name": "Ana Souza"
}, - "contact": {
- "_id": "6aa214678ff52271edc7ce01",
- "name": "João Pereira",
- "address": null
}, - "human": true,
- "receptive": true,
- "tags": [
- {
- "_id": "659feb1f49c7f81ec701de01",
- "tag": "SUPORTE - APP WEB"
}
], - "queue": {
- "_id": "60d0f2a53c9b6c57b6d37301",
- "name": "SAC",
- "description": "Fila de atendimento geral"
}, - "state_protocol": "closed",
- "countMessages": 10,
- "messages": [
- {
- "id": "6ab13713fab6bc4eb0025a01",
- "ack": null,
- "ackLog": [ ],
- "hasQuotedMsg": false,
- "human": false,
- "template": false,
- "wppId": null,
- "direction": "incoming",
- "message_type": "text",
- "createdAt": "2025-09-22T11:46:27.639Z",
- "message": "Olá, bom dia!"
}, - {
- "id": "6ab13713fab6bc2dd6025a02",
- "ack": "2",
- "ackLog": [ ],
- "hasQuotedMsg": false,
- "human": false,
- "template": false,
- "wppId": null,
- "direction": "outgoing",
- "message_type": "text",
- "createdAt": "2025-09-22T11:46:27.703Z",
- "message": "Para agilizar, descreva o assunto e aguarde um atendente, por favor."
}, - {
- "id": "6ab13713fab6bcb968025a03",
- "ack": "0",
- "ackLog": [ ],
- "hasQuotedMsg": false,
- "human": false,
- "template": false,
- "wppId": null,
- "direction": "outgoing",
- "message_type": "note",
- "createdAt": "2025-09-22T11:46:27.741Z",
- "message": "Direcionado pelo bot para a fila: SAC."
}, - {
- "id": "6ab1371d5ce68b0e5dc37004",
- "ack": null,
- "ackLog": [ ],
- "hasQuotedMsg": false,
- "human": true,
- "template": false,
- "wppId": null,
- "direction": "incoming",
- "message_type": "text",
- "createdAt": "2025-09-22T11:46:37.694Z",
- "message": "Preciso de ajuda para criar um novo template."
}, - {
- "id": "6ab13787d2a9b395fe6b9f05",
- "ack": "0",
- "ackLog": [ ],
- "hasQuotedMsg": false,
- "human": true,
- "template": false,
- "wppId": null,
- "direction": "outgoing",
- "message_type": "note",
- "createdAt": "2025-09-22T11:48:23.125Z",
- "message": "Protocolo assumido pela agente Ana Souza."
}, - {
- "id": "6ab137eb0fc4693df670ef06",
- "ack": "1",
- "ackLog": [ ],
- "hasQuotedMsg": false,
- "human": true,
- "template": false,
- "wppId": null,
- "direction": "outgoing",
- "message_type": "text",
- "createdAt": "2025-09-22T11:50:03.755Z",
- "message": "Bom dia! Vou verificar para você."
}, - {
- "id": "6ab137ee6f0f41e2285c9507",
- "ack": "1",
- "ackLog": [ ],
- "hasQuotedMsg": false,
- "human": true,
- "template": false,
- "wppId": null,
- "direction": "outgoing",
- "message_type": "text",
- "createdAt": "2025-09-22T11:50:06.899Z",
- "message": "Um instante, por gentileza."
}, - {
- "id": "6ab1388bf9d6cc5a4a4acf08",
- "ack": null,
- "ackLog": [ ],
- "hasQuotedMsg": false,
- "human": true,
- "template": false,
- "wppId": null,
- "direction": "incoming",
- "message_type": "text",
- "createdAt": "2025-09-22T11:52:43.130Z",
- "message": "Enviei os detalhes por e-mail."
}, - {
- "id": "6ab13b7c17e7d5411fd5b009",
- "ack": "1",
- "ackLog": [ ],
- "hasQuotedMsg": false,
- "human": true,
- "template": false,
- "wppId": null,
- "direction": "outgoing",
- "message_type": "text",
- "createdAt": "2025-09-22T12:05:16.628Z",
- "message": "Template criado e ativo. Qualquer ajuste, me avise."
}, - {
- "id": "6ab18ac38291321c7490400a",
- "ack": "0",
- "ackLog": [ ],
- "hasQuotedMsg": false,
- "human": true,
- "template": false,
- "wppId": null,
- "direction": "outgoing",
- "message_type": "note",
- "createdAt": "2025-09-22T17:43:31.311Z",
- "message": "Protocolo encerrado pela agente Ana Souza."
}
], - "reason": {
- "protocolReason": {
- "reasonParent": null,
- "reasonNote": "",
- "_id": "6ab18ac3be4c840257583caa",
- "reasonName": "Resolvido"
}, - "reason": "660d2ef2eca7d763c325abdb",
- "motive": null
}, - "createdAt": "2025-09-22T11:46:27.628Z",
- "humanDate": "2025-09-22T11:46:27.698Z",
- "queueDate": "2025-09-22T11:46:27.698Z",
- "attendanceDate": "2025-09-22T11:48:19.962Z",
- "closeDate": "2025-09-22T17:43:31.270Z"
}
}Retorna protocolos abertos onde o número alvo é o número de WhatsApp usado na conversa.
Limite de requisições (rate limit):
| phoneNumber required | string |
{- "status": true,
- "data": { }
}Retorna lista de usuários cadastrados.
Limite de requisições (rate limit):
| 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) |
{- "status": true,
- "data": { }
}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):
| 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 |
{- "meta": {
- "page": 1,
- "limit": 20,
- "totalItems": 7,
- "totalPages": 1,
- "hasNext": false,
- "hasPrev": false,
- "sort": {
- "countTotal": -1
}
}, - "filters": {
- "period": "month",
- "startKey": "202509",
- "endKey": "202509",
- "tenant": "",
- "identityType": null,
- "identityValue": null,
- "routeId": null,
- "routeContains": null,
- "method": null,
- "statusClass": null,
- "minCount": 0
}, - "totals": {
- "countTotal": 1988,
- "count2xx": 1887,
- "count4xx": 98,
- "count5xx": 1,
- "countRateLimited": 0,
- "sumDurMs": 2075522,
- "avgDurMs": 1044
}, - "data": [
- {
- "_id": "68b56dede86f53954c04eb43",
- "identityType": "tenant",
- "identityValue": "5deab0f9b7a6ac4236b5a179",
- "key": "202509",
- "method": "POST",
- "period": "month",
- "routeId": "POST:/v2/msg/template/:broker",
- "tenant": "5deab0f9b7a6ac4236b5a179",
- "count2xx": 1690,
- "count4xx": 0,
- "count5xx": 0,
- "countRateLimited": 0,
- "countTotal": 1690,
- "avgDurMs": 873,
- "sumDurMs": 1475115,
- "createdAt": "2025-09-01T09:57:01.076Z",
- "updatedAt": "2025-09-23T11:33:17.046Z"
}
]
}