EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Lendo o histórico de DMs do Instagram: a API de Conversas

A API de Conversas do Instagram lê o histórico de DMs de uma conta profissional em graph.instagram.com. GET /me/conversations?platform=instagram lista as conversas com seus updated_time, GET /<CONVERSATION_ID>?fields=messages lista as mensagens de uma conversa por ID e horário, e GET /<MESSAGE_ID>?fields=id,created_time,from,to,message retorna uma mensagem. Os detalhes ficam disponíveis para as 20 mensagens mais recentes de cada conversa.

O easyCoexistence repassa novas DMs do Instagram ao seu endpoint assim que chegam e responde com send_social_dm dentro da janela de 24 horas, pelo Claude, pelo ChatGPT ou pelo seu próprio código, pela API oficial da Meta; ele não tem ferramenta para o histórico da Conversations API.

20

Mensagens mais recentes por conversa cujos detalhes a API retorna; as mais antigas respondem com um erro informando que foram excluídas.

30 days

Inatividade após a qual as conversas na pasta Solicitações deixam de ser retornadas.

2/sec

Chamadas à API de Conversas que um app pode fazer por segundo para cada conta profissional do Instagram.

2 permissions

instagram_business_basic e instagram_business_manage_messages, com um token de alguém que pode gerenciar as mensagens da conta.

Como listar as conversas de uma conta?

Com GET /me/conversations, ou /<IG_ID>/conversations, e platform=instagram, usando um token de acesso do Instagram User de alguém que pode gerenciar mensagens na conta. Cada item do array data é uma conversa, com seu id e updated_time.

Listing conversations
GET https://graph.instagram.com/me/conversations
  ?platform=instagram
  &access_token=<ACCESS_TOKEN>

{
  "data": [
    { "id": "<CONVERSATION_ID>", "updated_time": "<UPDATED_TIME>" }
  ]
}

Como encontrar a conversa com uma pessoa?

Adicione user_id com o ID com escopo do Instagram da pessoa, o IGSID que chega como sender.id quando ela envia mensagem para a conta, e a resposta retorna o id dessa conversa. Assim, um evento de webhook vira sua conversa, sem percorrer toda a lista.

One person's conversation
GET https://graph.instagram.com/me/conversations
  ?user_id=<IGSID>
  &access_token=<ACCESS_TOKEN>

Como ler as mensagens?

Em duas etapas. GET /<CONVERSATION_ID>?fields=messages lista as mensagens da conversa por id e created_time, que são os campos padrão. Depois, GET /<MESSAGE_ID> com fields=id,created_time,from,to,message retorna uma mensagem: quem enviou e para quem, cada um com um username e um ID, e seu texto.

A conversation's messages, then one message
GET https://graph.instagram.com/<CONVERSATION_ID>
  ?fields=messages
  &access_token=<ACCESS_TOKEN>

GET https://graph.instagram.com/<MESSAGE_ID>
  ?fields=id,created_time,from,to,message
  &access_token=<ACCESS_TOKEN>

Até onde é possível ler?

O guia e a visão geral da Meta definem quatro limites para o que é retornado:

  • Detalhes de mensagens: as 20 mensagens mais recentes de cada conversa; pedir uma mais antiga retorna um erro informando que ela foi excluída.
  • Solicitações: conversas na pasta Solicitações sem atividade por 30 dias não são retornadas.
  • Compartilhamentos: uma publicação ou Reel compartilhado volta apenas como URL da imagem ou do vídeo.
  • Limite de taxa: 2 chamadas por segundo para cada conta profissional do Instagram.

O que é necessário?

Com o Instagram Login, as permissões instagram_business_basic e instagram_business_manage_messages e um token de alguém que pode gerenciar mensagens na conta. O Acesso Standard basta para contas que você possui ou gerencia e adicionou ao app; atender outras contas exige o Acesso Avançado. A conta também precisa ter a opção Permitir acesso a mensagens ativada nas configurações do app do Instagram.

Por que manter um registro a partir dos webhooks?

Como a API retorna detalhes apenas das 20 últimas mensagens de cada conversa, o histórico completo precisa ser armazenado conforme acontece. O webhook de mensagens entrega as DMs assim que chegam, com o IGSID da pessoa como sender.id, e as mensagens que a conta envia também chegam, com os IDs invertidos, para que os dois lados da conversa possam ser registrados.

Como ler o histórico de DMs pelo easyCoexistence?

Ele repassa DMs em vez de ler o histórico. Novas DMs chegam ao seu endpoint assim que são recebidas, depois de você definir um com set_social_webhook_destination, e são repassadas sem guardar cópia; send_social_dm responde dentro da janela de atendimento de 24 horas, pelo Claude, pelo ChatGPT ou pelo seu próprio código. Nenhuma ferramenta chama me/conversations, então as mensagens anteriores são lidas no app do Instagram ou guardadas pelo seu próprio sistema conforme chegam.

Erros comuns

  • Esperar a conversa inteira pela API. Os detalhes param nas 20 mensagens mais recentes, então armazene as DMs do webhook de mensagens assim que chegam.
  • Consultar as conversas em busca de novas DMs. A API permite 2 chamadas por segundo por conta, enquanto o webhook de mensagens entrega cada DM assim que chega.
  • Procurar uma solicitação de mensagem antiga. Conversas em Solicitações com 30 dias de inatividade deixam de ser retornadas.
  • Interpretar o erro de excluída como exclusão pela pessoa. A Meta responde assim para qualquer mensagem mais antiga que as 20 mais recentes.
Fazendo isso com o EasyCoexistence

De US$ 9 a US$ 0.75 por número conectado por mês, caindo conforme você adiciona números, com os primeiros 3 dias grátis.

O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.

Perguntas frequentes

Posso exportar o histórico completo de DMs de uma conta do Instagram?

Não por completo pela API: ela lista as conversas, mas retorna detalhes das 20 mensagens mais recentes de cada uma. Um registro completo vem de armazenar as DMs conforme o webhook as entrega.

A leitura de mensagens pela API as marca como lidas?

Não. A Meta informa que as mensagens entregues pela API não são marcadas como lidas no app do Instagram até que uma resposta seja enviada.

A API de Conversas funciona com o Instagram Login?

Sim. O guia da Meta para ela foi escrito para o Instagram Login, com chamadas ao graph.instagram.com e as permissões instagram_business_*.

Como obter o username de uma pessoa a partir de uma conversa?

Solicite from em uma mensagem, que retorna o username e o ID do remetente. A User Profile API retorna mais, como o nome, a partir do IGSID da pessoa, depois que ela enviou mensagem para a conta.

Continue lendo

Conecte seu primeiro canal em dois minutos.

Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.

  • 3 dias grátis
  • Cancele quando quiser
  • Só APIs oficiais
  • Monitorado 24/7

Verificado em