API atual/Referência completa/WhatsApp: caixa de entrada

Responder ao cliente

Envia texto ou mídia em uma conversa e baixa a mídia que o cliente mandou.

Quando um atendente assume uma conversa, ele responde por estas rotas. A resposta sai pelo número da conversa (o do seller, se houver). Só funciona dentro da janela de 24 horas aberta pela última mensagem do cliente; depois disso a Meta recusa texto livre e a rota devolve 502 (use um template, em Mensagens enviadas).

Responder com texto

Envia o texto, registra a mensagem na conversa como enviada manualmente e desliga o assistente da conversa.

POST/api/v1/admin/whatsapp/threads/{id}/replyAdmin

Envia uma mensagem de texto ao cliente da conversa

Parâmetros de caminho

idstringobrigatório

UUID da conversa.

Corpo da requisição

bodystringobrigatório

Texto da mensagem. Não pode ser vazio nem só espaços.

Exemplo de requisição (Responder com texto)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/threads/014ff6d8-8ff0-40da-82ce-e5a349b57be6/reply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Oi! Sim, temos a camisa M. Posso enviar o link?"
  }'

Resposta (Responder com texto)

200Enviada

json

{
  "success": true,
  "message": {
    "id": 2090,
    "phone_number": "+5511999990428",
    "message_type": "text",
    "params": {
      "body": "Oi! Sim, temos a camisa M. Posso enviar o link?"
    },
    "status": "sent",
    "whatsapp_message_id": "wamid.HBgNNTUxMTk5OTk5MDQyOBUCABEYEg"
  }
}

Campos da resposta

successboolean

true.

messageobject

A mensagem registrada. Veja Mensagens enviadas para os campos.

Erros (Responder com texto)

Status	Quando	Corpo
400	Corpo inválido ou `body` vazio.	`{"error":"body required"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_orders"}` ou `{"error":"admin access required"}`
404	A conversa não existe.	`{"error":"thread not found"}`
502	A Meta recusou o envio (por exemplo, fora da janela de 24 horas).	`{"error":"Cloud API send failed: ..."}`

Responder com mídia

Envia um arquivo que a Meta busca em uma URL pública. Primeiro envie o arquivo à loja (mídia da plataforma) e use a URL pública resultante. Diferente da resposta de texto, esta rota não desliga o assistente.

POST/api/v1/admin/whatsapp/threads/{id}/reply-mediaAdmin

Envia imagem, vídeo, áudio ou documento ao cliente

Parâmetros de caminho

idstringobrigatório

UUID da conversa.

Corpo da requisição

media_urlstringobrigatório

URL pública (HTTP ou HTTPS) que a Meta consegue abrir.

media_typestringobrigatório

imagevideoaudiodocument

Tipo da mídia.

captionstring

Legenda. Vale para imagem, vídeo e documento; é ignorada em áudio.

idempotency_keystring

Reservado. Hoje é aceito mas não evita envio duplicado.

Exemplo de requisição (Responder com mídia)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/threads/014ff6d8-8ff0-40da-82ce-e5a349b57be6/reply-media" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "media_url": "https://minhaloja.io.venddor.com.br/uploads/catalogo.pdf",
    "media_type": "document",
    "caption": "Nosso catálogo"
  }'

Resposta (Responder com mídia)

200Enviada

json

{
  "success": true,
  "message": {
    "id": 2091,
    "thread_id": "014ff6d8-8ff0-40da-82ce-e5a349b57be6",
    "direction": "outbound",
    "message_type": "document",
    "media_url": "https://minhaloja.io.venddor.com.br/uploads/catalogo.pdf",
    "status": "S",
    "sent_manually": true
  }
}

Campos da resposta

successboolean

true.

messageobject

A mensagem registrada na conversa.

Erros (Responder com mídia)

Status	Quando	Corpo
400	`media_url` ausente, `media_type` não suportado ou conversa sem telefone.	`{"error":"whatsapp media reply: media_url required","message":null}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_orders"}` ou `{"error":"admin access required"}`
404	A conversa não existe.	`{"error":"thread not found"}`
502	A Meta recusou o envio (URL inacessível, fora da janela...). A resposta traz o erro e a mensagem registrada com falha.	`{"error":"...","message":{}}`

Baixar a mídia de uma mensagem

Entrega o arquivo que o cliente enviou, com o Content-Type correto. A primeira chamada busca na Meta e guarda uma cópia; as seguintes saem do cache da plataforma (Cache-Control: private, max-age=3600). Mensagens cuja mídia é um link externo respondem com redirecionamento 302.

GET/api/v1/admin/whatsapp/media/{message_id}Admin

Devolve os bytes da mídia (imagem, áudio, documento) de uma mensagem

Parâmetros de caminho

message_idintegerobrigatório

Id numérico da mensagem (campo id das mensagens da conversa).

Exemplo de requisição (Baixar a mídia de uma mensagem)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/media/2027" \
  -H "Authorization: Bearer $TOKEN" \
  -o anexo.bin

Resposta (Baixar a mídia de uma mensagem)

200Arquivo

http

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Disposition: inline; filename="foto.jpg"
Cache-Control: private, max-age=3600

<bytes da imagem>

Erros (Baixar a mídia de uma mensagem)

Status	Quando	Corpo
400	`message_id` não numérico, mensagem sem mídia, esquema de URL não suportado ou id de mídia ausente.	`{"error":"message has no media"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_orders"}` ou `{"error":"admin access required"}`
404	Mensagem inexistente.	`{"error":"message not found"}`
502	Falha ao buscar a mídia na Meta (por exemplo, a mídia expirou).	`{"error":"media fetch failed: ..."}`
503	Token da API do WhatsApp não configurado.	`{"error":"whatsapp api token not configured"}`

Veja também

API atual/Referência completa/WhatsApp: caixa de entrada

Responder ao cliente

Envia texto ou mídia em uma conversa e baixa a mídia que o cliente mandou.

Responder com texto

Envia o texto, registra a mensagem na conversa como enviada manualmente e desliga o assistente da conversa.

POST/api/v1/admin/whatsapp/threads/{id}/replyAdmin

Envia uma mensagem de texto ao cliente da conversa

Parâmetros de caminho

idstringobrigatório

UUID da conversa.

Corpo da requisição

bodystringobrigatório

Texto da mensagem. Não pode ser vazio nem só espaços.

Exemplo de requisição (Responder com texto)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/threads/014ff6d8-8ff0-40da-82ce-e5a349b57be6/reply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Oi! Sim, temos a camisa M. Posso enviar o link?"
  }'

Resposta (Responder com texto)

200Enviada

json

{
  "success": true,
  "message": {
    "id": 2090,
    "phone_number": "+5511999990428",
    "message_type": "text",
    "params": {
      "body": "Oi! Sim, temos a camisa M. Posso enviar o link?"
    },
    "status": "sent",
    "whatsapp_message_id": "wamid.HBgNNTUxMTk5OTk5MDQyOBUCABEYEg"
  }
}

Campos da resposta

successboolean

true.

messageobject

A mensagem registrada. Veja Mensagens enviadas para os campos.

Erros (Responder com texto)

Status	Quando	Corpo
400	Corpo inválido ou `body` vazio.	`{"error":"body required"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_orders"}` ou `{"error":"admin access required"}`
404	A conversa não existe.	`{"error":"thread not found"}`
502	A Meta recusou o envio (por exemplo, fora da janela de 24 horas).	`{"error":"Cloud API send failed: ..."}`

Responder com mídia

POST/api/v1/admin/whatsapp/threads/{id}/reply-mediaAdmin

Envia imagem, vídeo, áudio ou documento ao cliente

Parâmetros de caminho

idstringobrigatório

UUID da conversa.

Corpo da requisição

media_urlstringobrigatório

URL pública (HTTP ou HTTPS) que a Meta consegue abrir.

media_typestringobrigatório

imagevideoaudiodocument

Tipo da mídia.

captionstring

Legenda. Vale para imagem, vídeo e documento; é ignorada em áudio.

idempotency_keystring

Reservado. Hoje é aceito mas não evita envio duplicado.

Exemplo de requisição (Responder com mídia)

bash

curl -X POST "$BASE_URL/api/v1/admin/whatsapp/threads/014ff6d8-8ff0-40da-82ce-e5a349b57be6/reply-media" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "media_url": "https://minhaloja.io.venddor.com.br/uploads/catalogo.pdf",
    "media_type": "document",
    "caption": "Nosso catálogo"
  }'

Resposta (Responder com mídia)

200Enviada

json

{
  "success": true,
  "message": {
    "id": 2091,
    "thread_id": "014ff6d8-8ff0-40da-82ce-e5a349b57be6",
    "direction": "outbound",
    "message_type": "document",
    "media_url": "https://minhaloja.io.venddor.com.br/uploads/catalogo.pdf",
    "status": "S",
    "sent_manually": true
  }
}

Campos da resposta

successboolean

true.

messageobject

A mensagem registrada na conversa.

Erros (Responder com mídia)

Status	Quando	Corpo
400	`media_url` ausente, `media_type` não suportado ou conversa sem telefone.	`{"error":"whatsapp media reply: media_url required","message":null}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_orders"}` ou `{"error":"admin access required"}`
404	A conversa não existe.	`{"error":"thread not found"}`
502	A Meta recusou o envio (URL inacessível, fora da janela...). A resposta traz o erro e a mensagem registrada com falha.	`{"error":"...","message":{}}`

Baixar a mídia de uma mensagem

GET/api/v1/admin/whatsapp/media/{message_id}Admin

Devolve os bytes da mídia (imagem, áudio, documento) de uma mensagem

Parâmetros de caminho

message_idintegerobrigatório

Id numérico da mensagem (campo id das mensagens da conversa).

Exemplo de requisição (Baixar a mídia de uma mensagem)

bash

curl "$BASE_URL/api/v1/admin/whatsapp/media/2027" \
  -H "Authorization: Bearer $TOKEN" \
  -o anexo.bin

Resposta (Baixar a mídia de uma mensagem)

200Arquivo

http

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Disposition: inline; filename="foto.jpg"
Cache-Control: private, max-age=3600

<bytes da imagem>

Erros (Baixar a mídia de uma mensagem)

Status	Quando	Corpo
400	`message_id` não numérico, mensagem sem mídia, esquema de URL não suportado ou id de mídia ausente.	`{"error":"message has no media"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.	`{"error":"module_disabled","module":"whatsapp-commerce"}` ou `{"error":"insufficient privileges","required":"manage_orders"}` ou `{"error":"admin access required"}`
404	Mensagem inexistente.	`{"error":"message not found"}`
502	Falha ao buscar a mídia na Meta (por exemplo, a mídia expirou).	`{"error":"media fetch failed: ..."}`
503	Token da API do WhatsApp não configurado.	`{"error":"whatsapp api token not configured"}`