Fetch Conversations

warning

Inbox management is not available on the Basic plan. Upgrade to Intermediate, Growth or Business plan to access this endpoint.

Overview

The Fetch Conversations endpoint returns conversations for one connected Facebook, Instagram, or WhatsApp account, sorted by the most recent update. Select an account in your UI and pass its social_account_id.

Base URL:

https://message.oneupapp.io

Endpoint

GET /api/conversations

Request Parameters

Parameter	Required	Description
`apiKey`	Yes	Your personal API key generated from the API Access page. Passed as a query parameter.
`platform`	No	The social platform: `facebook`, `instagram`, or `whatsapp`. Omit to include all platforms.
`social_account_id`	Yes	The selected social account ID. Maximum: 255 characters.
`status`	No	The conversation status: `open` (default), `closed`, `spam`, or `all`.
`search`	No	Search message text and participant names. Maximum: 255 characters.
`per_page`	No	Number of results per page. Default: `20`. Maximum: `100`.
`cursor`	No	The `meta.next_cursor` value from the previous response. Omit for the first page.

Facebook and Instagram accounts are synced automatically when needed. Initial loading retrieves up to 20 recent conversations for the selected account and up to 20 messages per conversation, subject to platform limits. WhatsApp must already be connected in Inbox and receives new messages through webhooks. Reading conversations does not mark messages as read.

The results match Social Inbox: conversations without messages are omitted. When the platform creates multiple conversation IDs for the same participant, the newest conversation represents the thread and unread_count combines the unread messages from those duplicate conversations.

Sample Request

curl --location --request GET \
"https://message.oneupapp.io/api/conversations?apiKey=YOUR_API_KEY&social_account_id=104040148726689"

With filters:

curl --location --request GET \
"https://message.oneupapp.io/api/conversations?apiKey=YOUR_API_KEY&social_account_id=17841473238379938&platform=instagram&status=all"

With pagination:

curl --location --request GET \
"https://message.oneupapp.io/api/conversations?apiKey=YOUR_API_KEY&social_account_id=104040148726689&per_page=20&cursor=NEXT_CURSOR"

Sample Response

{
  "message": "OK",
  "error": false,
  "data": [
    {
      "id": 123,
      "social_account_id": "104040148726689",
      "conversation_id": "t_987654321",
      "link": null,
      "updated_time": "2026-09-28 10:00:00",
      "platform": "facebook",
      "status": "open",
      "unread_count": 0,
      "latest_message": {
        "id": 456,
        "conversation_id": "t_987654321",
        "message_id": "m_123456",
        "sender_id": "104040148726689",
        "receiver_id": "987654321",
        "sender_name": "My Page",
        "receiver_name": "Jane Doe",
        "message": "Thanks for contacting us!",
        "attachments": null,
        "template": null,
        "profile_image": null,
        "is_read": 1,
        "created_time": "2026-09-28 10:00:00"
      }
    }
  ],
  "meta": {
    "next_cursor": null,
    "has_more": false,
    "sync_status": "idle",
    "refresh": []
  }
}

202 Accepted — Connected accounts are being synced. The response includes Retry-After: 5:

{
  "message": "Your accounts are being synced. Repeat this request shortly. No message has been sent.",
  "error": false,
  "data": null,
  "meta": {
    "sync_status": "pending"
  }
}

Wait at least five seconds, then repeat the request. Account sync runs automatically when needed.

Pagination

Use the meta.next_cursor value from the response as the next request’s cursor parameter, keeping the same filters. It returns null when there are no more results. Pagination retrieves stored conversations; it does not import older history from the platform.

When stored conversations run out, use Load More Conversations to fetch five more conversations from the platform for the selected account.

Response Fields

Conversation Object

Field	Description
`id`	The conversation ID used in API requests.
`social_account_id`	The social account ID that owns the conversation. WhatsApp uses the business phone number ID.
`conversation_id`	The platform-specific conversation identity.
`link`	Link to the conversation on the platform, when available.
`updated_time`	The last update time, formatted as `YYYY-MM-DD HH:MM:SS`.
`platform`	The platform name: `facebook`, `instagram`, or `whatsapp`.
`status`	The conversation status: `open`, `closed`, or `spam`.
`unread_count`	The number of unread incoming messages.
`latest_message`	The latest message in the conversation, or `null`.

Message Object

Field	Description
`id`	The internal message ID.
`conversation_id`	The platform-specific conversation identity.
`message_id`	The platform-specific message ID.
`sender_id`	The sender’s platform ID.
`receiver_id`	The recipient’s platform ID.
`sender_name`	The sender’s display name, when available.
`receiver_name`	The recipient’s display name, when available.
`message`	The message text.
`attachments`	Attachment details, when available.
`template`	WhatsApp template details, when available.
`profile_image`	Profile image, when available.
`is_read`	Local read status: `0` for unread or `1` for read.
`created_time`	The message creation time, formatted as `YYYY-MM-DD HH:MM:SS`.

Pagination and Sync Status

Field	Description
`meta.next_cursor`	The cursor for the next page, or `null`.
`meta.has_more`	Whether more results are available.
`meta.sync_status`	Account sync status: `pending`, `complete`, `failed`, or `idle`.
`meta.refresh`	Refresh status by account ID: `pending`, `complete`, or `failed`. An empty array is returned when no status is available.

Sync and refresh statuses are available for ten minutes. Once they expire, the sync status returns to idle. Use Force Refresh Conversations to request recent activity.

Error Responses

Status	When
`401`	Missing or invalid `apiKey`.
`403`	Inbox management is unavailable on the Basic plan.
`404`	The requested resource was not found or does not belong to the authorized user.
`422`	Invalid or missing parameters.
`429`	The limit of 60 requests per minute per API key was exceeded. Wait for the `Retry-After` interval.
`503`	API key verification or account sync is temporarily unavailable.

✅ Result: You have successfully retrieved your inbox conversations!

Overview​

Endpoint​

Request Parameters​

Sample Request​

Sample Response​

Pagination​

Response Fields​

Conversation Object​

Message Object​

Pagination and Sync Status​

Error Responses​