Consultar limites atuais de novas conversas no WhatsApp
GET /instance/wa_messages_limits
Consulta o estado atual de limitação do WhatsApp para a conta atualmente conectada.
Este endpoint é útil para:
- diagnosticar erros de envio com
provider_code: 463 - verificar se o WhatsApp indica que a conta atualmente conectada pode iniciar novas conversas
- exibir informações de suporte antes de campanhas ou envios de alto volume
A resposta consolida duas fontes internas do WhatsApp:
new_chat_message_capping: limite de mensagens para iniciar novas conversasreachout_timelock: restrição temporária para iniciar novas conversas
Observações:
- este endpoint depende de sessão ativa e conectada
- se o WhatsApp não retornar os dados esperados, a resposta pode marcar os blocos como indisponíveis via
available: falseelookup_error messagedescreve o estado atual da conta atualmente conectadaprovider_messagedetalha o motivo reportado pelo WhatsApp quando houver restrição ativa
Autenticação
[
{
"token": []
}
]
{
"token": {
"name": "token",
"type": "apiKey",
"in": "header"
}
}
Respostas
{
"200": {
"description": "Diagnóstico atual dos limites de novas conversas da conta atualmente conectada",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"example": "whatsapp"
},
"reachable": {
"type": "boolean",
"description": "Indica se ao menos uma das consultas ao WhatsApp retornou dados úteis",
"example": true
},
"can_send_new_messages": {
"type": [
"boolean",
"null"
],
"description": "Indica se o WhatsApp sinaliza que a conta atualmente conectada pode iniciar novas conversas.\nPode ser `null` quando não foi possível concluir o diagnóstico.\n",
"example": false
},
"error_key": {
"type": "string",
"description": "Chave de erro derivada do diagnóstico atual",
"example": "WHATSAPP_REACHOUT_TIMELOCK"
},
"message": {
"type": "string",
"description": "Mensagem técnica principal em inglês",
"example": "WhatsApp indicates that the currently connected account is under a temporary restriction for starting new conversations. This is not an internal API error."
},
"message_ptbr": {
"type": "string",
"description": "Mensagem principal traduzida para pt-BR",
"example": "O WhatsApp indica que a conta atualmente conectada está sob uma restrição temporária para iniciar novas conversas. Isso não é um erro interno da API."
},
"provider_message": {
"type": "string",
"description": "Motivo detalhado reportado pelo WhatsApp em inglês",
"example": "WhatsApp reported that the currently connected account is under a temporary restriction for starting new conversations, usually related to sending volume or quality."
},
"provider_message_ptbr": {
"type": "string",
"description": "Motivo detalhado reportado pelo WhatsApp em pt-BR",
"example": "O WhatsApp informou que a conta atualmente conectada está sob uma restrição temporária para iniciar novas conversas, normalmente relacionada a volume ou qualidade de envios."
},
"diagnostics_endpoint": {
"type": "string",
"example": "/instance/wa_messages_limits"
},
"new_chat_message_capping": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"example": true
},
"status": {
"type": "string",
"example": "CAPPED"
},
"used_quota": {
"type": "integer",
"example": 10
},
"total_quota": {
"type": "integer",
"example": 10
},
"cycle_start": {
"type": "string",
"format": "date-time"
},
"cycle_end": {
"type": "string",
"format": "date-time"
},
"server_sent_at": {
"type": "string",
"format": "date-time"
},
"ote_status": {
"type": "string",
"example": "EXHAUSTED"
},
"mv_status": {
"type": "string",
"example": "ACTIVE"
},
"lookup_error": {
"type": "string"
}
}
},
"reachout_timelock": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"example": true
},
"active": {
"type": "boolean",
"example": true
},
"until": {
"type": "string",
"format": "date-time"
},
"enforcement_type": {
"type": "string",
"example": "BIZ_QUALITY"
},
"lookup_error": {
"type": "string"
}
}
}
}
},
"examples": {
"restricted": {
"summary": "Conta conectada com restrição ativa",
"value": {
"provider": "whatsapp",
"reachable": true,
"can_send_new_messages": false,
"error_key": "WHATSAPP_REACHOUT_TIMELOCK",
"message": "WhatsApp indicates that the currently connected account is under a temporary restriction for starting new conversations. This is not an internal API error.",
"message_ptbr": "O WhatsApp indica que a conta atualmente conectada está sob uma restrição temporária para iniciar novas conversas. Isso não é um erro interno da API.",
"provider_message": "WhatsApp reported that the currently connected account is under a temporary restriction for starting new conversations, usually related to sending volume or quality.",
"provider_message_ptbr": "O WhatsApp informou que a conta atualmente conectada está sob uma restrição temporária para iniciar novas conversas, normalmente relacionada a volume ou qualidade de envios.",
"diagnostics_endpoint": "/instance/wa_messages_limits",
"new_chat_message_capping": {
"available": true,
"status": "CAPPED",
"used_quota": 10,
"total_quota": 10,
"cycle_end": "2026-04-30T23:59:59Z",
"ote_status": "EXHAUSTED",
"mv_status": "ACTIVE"
},
"reachout_timelock": {
"available": true,
"active": true,
"until": "2026-04-07T12:00:00Z",
"enforcement_type": "BIZ_QUALITY"
}
}
},
"unrestricted": {
"summary": "Conta conectada sem restrições",
"value": {
"provider": "whatsapp",
"reachable": true,
"can_send_new_messages": true,
"message": "No WhatsApp restriction for starting new conversations was detected for the currently connected account.",
"message_ptbr": "Nenhuma restrição de envio de novas conversas foi identificada no WhatsApp para a conta atualmente conectada.",
"diagnostics_endpoint": "/instance/wa_messages_limits",
"new_chat_message_capping": {
"available": true,
"status": "NONE",
"used_quota": 2,
"total_quota": 10
},
"reachout_timelock": {
"available": true,
"active": false
}
}
}
}
}
}
},
"401": {
"description": "Token inválido ou ausente",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "invalid token"
}
}
}
}
}
},
"500": {
"description": "Erro interno ao consultar os limites",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "No session"
}
}
}
}
}
}
}