Mensagens diretas

Liste as conversas de uma conta, leia uma conversa e responda dentro da janela de 24 horas da Meta.

Leitura e resposta de mensagens diretas do Instagram, ao vivo da Meta. Nada é guardado pela Postmatic.

Permissão

A conta precisa ter sido conectada com instagram_business_manage_messages. Sem ela, as rotas respondem 403 PERMISSION_REQUIRED: reconecte a conta por Contas.

Conversas

GET /v1/messages?accountId=…

curl "https://api.uat.postmatic.dev/v1/messages?accountId=int_…&limit=20" -H "x-access-key: pm_live_…"

json

{
  "success": true, "accountId": "int_…", "selfId": "1784…", "selfUsername": "acme.brand",
  "conversations": [{
    "id": "aWdfZ…", "updatedTime": "2026-09-09T12:00:00+0000",
    "participants": [{ "id": "1784…", "username": "acme.brand", "name": "Acme", "profilePictureUrl": null }, { "id": "1234…", "username": "ana", "name": "Ana", "profilePictureUrl": "https://…" }],
    "lastMessage": { "id": "aWdf…", "text": "oi, tem em azul?", "from": { "id": "1234…", "username": "ana" }, "timestamp": "2026-09-09T12:00:00+0000" }
  }],
  "nextCursor": "QVFIU…"
}

O recipientId para responder é o participante cujo id é diferente de selfId.

Ler uma conversa

GET /v1/messages/:conversationId?accountId=…&limit=25&cursor=… devolve messages (mais recentes primeiro) e nextCursor.

Responder

POST /v1/messages

curl -X POST https://api.uat.postmatic.dev/v1/messages \
  -H "x-access-key: pm_live_…" -H "content-type: application/json" \
  -d '{ "accountId": "int_…", "recipientId": "1234…", "text": "Temos sim! Quer que eu separe?" }'

Responde 201 com messageId. Texto de 1 a 1000 caracteres.

A janela de 24 horas

A Meta só permite enviar até 24 horas depois da última mensagem do destinatário. A Postmatic verifica isso antes de enviar: fora da janela, ou sem nenhuma mensagem anterior dele, a resposta é 409 MESSAGE_WINDOW_CLOSED com details.recipientId e details.lastInboundAt (ou null). Não há como iniciar uma conversa pela API.