Retrieve chats & messages

Learn how to retrieve Facebook chats and messages with Unipile API.

List inboxes

A Facebook account organizes its conversations in several inboxes. To list them, use List all Inboxes.

Inbox IDDescription
INBOXPrimary inbox
PENDINGMessage requests
OTHEROther inbox
SPAMSpam conversations
ARCHIVEDArchived conversations
HIDDENHidden conversations
PAGE_<page_id>_INBOXInbox of an activated Facebook Page

List chats

To list the chats of the personal account, use List all Chats. It does not include the chats of Pages. Up to 100 chats can be retrieved per page.

const { data } = await messagingApi.getChatsList({
  path: {
    account_id: "acc_123456789",
  },
  query: {
    limit: 20,
  },
});
chats = messaging_api.get_chats_list(
    "acc_123456789",
    limit=20,
)
curl --request GET \
     --url 'https://api.unipile.com/v2/acc_123456789/chats?limit=20' \
     --header 'X-API-KEY: api-key' \
     --header 'accept: application/json'

To list the chats of a single inbox, use List inbox Chats.

const { data } = await messagingApi.getInboxChatsList({
  path: {
    account_id: "acc_123456789",
    inbox_id: "PENDING",
  },
});
chats = messaging_api.get_inbox_chats_list("PENDING", "acc_123456789")
curl --request GET \
     --url https://api.unipile.com/v2/acc_123456789/inboxes/PENDING/chats \
     --header 'X-API-KEY: api-key' \
     --header 'accept: application/json'

To get a single chat, use Get a Chat. To find the existing chat with a person, use Find Chats by User: it returns an empty list if there is none.


List messages

To list the messages of a chat, newest first, use List all Chat Messages. Up to 100 messages can be retrieved per page.

const { data } = await messagingApi.getMessagesList({
  path: {
    account_id: "acc_123456789",
    chat_id: "chat_id",
  },
  query: {
    limit: 20,
  },
});
messages = messaging_api.get_messages_list(
    "chat_id",
    "acc_123456789",
    limit=20,
)
curl --request GET \
     --url 'https://api.unipile.com/v2/acc_123456789/chats/chat_id/messages?limit=20' \
     --header 'X-API-KEY: api-key' \
     --header 'accept: application/json'

To download a file from a message, use Get a Message Attachment.

📘

Past messages of encrypted chats

Personal chats are end-to-end encrypted. Their past messages and files can only be read if the history was unlocked when the account was linked. See Encrypted chats.


List contacts

List all Contacts returns the contacts Messenger ranks on the right column of the Facebook home page, up to limit. This list has no pagination, and it is empty for accounts Facebook does not show contacts to.


Be notified about new messages

To be notified about new messages, set up a Webhook that listens for message.new events.

🚧

Matching webhooks with chats

For the same conversation, the chat_id returned by the API can differ from the one carried by a webhook event. Take this into account if you use it to match events with your stored chats.


Did this page help you?