curl --request POST \
--url https://app.metricaas.com.br/v1/conversas/{id}/mensagens \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"text": "Oi, Maria! O plano anual sai por R$ 1.188,00. Quer o link de pagamento?"
}
'{
"id": "0d9e8f7a-6b5c-4d3e-8f21-a0b1c2d3e4f5",
"conversation_id": "7b0c2e4a-1f3d-4c55-9a10-2d6f8e9b3c71",
"status": "sent",
"duplicate": true
}{
"id": "0d9e8f7a-6b5c-4d3e-8f21-a0b1c2d3e4f5",
"conversation_id": "7b0c2e4a-1f3d-4c55-9a10-2d6f8e9b3c71",
"status": "pending",
"duplicate": false
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "about:blank",
"title": "IA pausada nesta conversa",
"status": 409,
"detail": "A IA foi pausada em 2026-10-21T13:55:00.000Z por joana@empresa.com.br. Um humano está cuidando desta conversa. Mande \"forcar\": true para enviar mesmo assim."
}{
"type": "about:blank",
"title": "Requisição inválida",
"status": 422,
"errors": [
{
"field": "media_url",
"message": "só a URL devolvida por POST /v1/midia"
}
]
}{
"type": "about:blank",
"title": "Limite de envios",
"status": 429,
"detail": "Limite de 30 envios por minuto para este token. Tente de novo em 42 s."
}Responde ao lead
Exige inbox:operate e um token write. A mensagem entra na fila de
envio e sai pela conexão de WhatsApp ou Instagram da empresa; acompanhe o
resultado em GET /mensagens/{id}.
Idempotency-Key é obrigatório. Use um valor por mensagem (o id da
execução do seu fluxo, por exemplo). Repetir a chamada com a mesma chave
devolve 200 com a mesma mensagem e duplicate: true — nada é enviado
de novo. A chave vale para UMA conversa: reusá-la noutra conversa é
422, e a resposta não diz qual mensagem a usou. O provedor de WhatsApp não deduplica: sem a chave, um retry
manda a mesma mensagem duas vezes ao lead.
O que o envio NÃO faz: não assume a conversa, não tira da fila do time, não muda o estado de atendimento e não conta como primeira resposta do time. O tempo da primeira resposta da IA é medido à parte.
Limites: 30 envios por minuto por token e 1.000 por dia (de Brasília)
por empresa. A repetição com a mesma chave não conta, e um envio
recusado (409, 422) também não. POST /midia conta no limite por
minuto.
curl --request POST \
--url https://app.metricaas.com.br/v1/conversas/{id}/mensagens \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"text": "Oi, Maria! O plano anual sai por R$ 1.188,00. Quer o link de pagamento?"
}
'{
"id": "0d9e8f7a-6b5c-4d3e-8f21-a0b1c2d3e4f5",
"conversation_id": "7b0c2e4a-1f3d-4c55-9a10-2d6f8e9b3c71",
"status": "sent",
"duplicate": true
}{
"id": "0d9e8f7a-6b5c-4d3e-8f21-a0b1c2d3e4f5",
"conversation_id": "7b0c2e4a-1f3d-4c55-9a10-2d6f8e9b3c71",
"status": "pending",
"duplicate": false
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "about:blank",
"title": "IA pausada nesta conversa",
"status": 409,
"detail": "A IA foi pausada em 2026-10-21T13:55:00.000Z por joana@empresa.com.br. Um humano está cuidando desta conversa. Mande \"forcar\": true para enviar mesmo assim."
}{
"type": "about:blank",
"title": "Requisição inválida",
"status": 422,
"errors": [
{
"field": "media_url",
"message": "só a URL devolvida por POST /v1/midia"
}
]
}{
"type": "about:blank",
"title": "Limite de envios",
"status": 429,
"detail": "Limite de 30 envios por minuto para este token. Tente de novo em 42 s."
}Authorizations
Authorization: Bearer mcp_… — gere em Configurações → Tokens de API.
O token de API tem modo read ou write. Um token read responde 403
a qualquer verbo que não seja GET. As capacidades do token são a
interseção com as da pessoa de quem ele herda o papel: se ela perder
acesso na grade de Equipe, o token perde junto, sem ninguém revogar nada.
Token de agência (gerado no console da agência): vale para as
empresas da agência, e a empresa de cada chamada vai no header
X-Empresa: <slug da empresa>. Sem o header, 401. Num token de
empresa o header é opcional e, se vier, tem de ser a própria empresa. O
modo read vale igual: um token de agência de leitura só faz GET —
é o token para pôr numa função que só consulta.
Headers
Body
Até 4.096 caracteres, depois de aparar espaços. Obrigatório quando não há mídia; com mídia, vira a legenda.
4096Response
Esta Idempotency-Key já foi usada nesta empresa. É a mesma mensagem,
com o status de agora; nada foi enviado de novo.