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.
Mensagens mais recentes por conversa cujos detalhes a API retorna; as mais antigas respondem com um erro informando que foram excluídas.
Inatividade após a qual as conversas na pasta Solicitações deixam de ser retornadas.
Chamadas à API de Conversas que um app pode fazer por segundo para cada conta profissional do Instagram.
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.
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.
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.
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.
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