Force Refresh Conversations

warning

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

Overview

The Force Refresh Conversations endpoint refreshes recent conversations for one connected Facebook or Instagram account. It syncs the account first, then loads its recent conversations and messages.

Base URL:

https://message.oneupapp.io

Endpoint

POST /api/conversations/refresh

Request Parameters

Parameter	Required	Type	Description
apiKey	Yes	string	Your personal API key generated from the API Access page. Passed as a query parameter.
platform	No	string	The selected account's platform: facebook or instagram.
social_account_id	Yes	string	The selected social account ID. Maximum: 255 characters.
limit	No	integer	Number of recent conversations to fetch. Default: 20. Allowed range: 1–100.

Stored conversations remain available during the refresh. This loads recent activity rather than the full conversation history. WhatsApp receives updates through webhooks and does not support this endpoint. Each account can be refreshed once every 15 minutes, matching the Social Inbox refresh button.

Sample Request

curl --location --request POST \
"https://message.oneupapp.io/api/conversations/refresh?apiKey=YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
  "platform": "instagram",
  "social_account_id": "17841473238379938",
  "limit": 20
}'

Sample Response

202 Accepted — Account sync and conversation refresh requested. 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"
  }
}

If the same account is already being refreshed, the endpoint remains 202 Accepted and returns meta.refresh_status: "pending". It does not queue duplicate work.

429 Too Many Requests — The account was refreshed within the last 15 minutes. Use the Retry-After response header or meta.available_at before trying again:

{
  "message": "This account was refreshed recently. Try again after the cooldown.",
  "error": true,
  "data": null,
  "meta": {
    "refresh_status": "complete",
    "available_at": "2026-09-28T10:15:00+08:00"
  }
}

Response Fields

Field	Description
message	A message describing the refresh status.
error	false when the refresh request is accepted.
data	null while account sync is pending.
meta.sync_status	pending while the account sync is in progress.

Wait at least five seconds, then use Fetch Conversations to check meta.sync_status and each account’s meta.refresh status. Account sync can finish before conversation loading completes. Statuses expire after ten minutes. A failed refresh releases the cooldown so it can be retried immediately.

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 parameters or a WhatsApp refresh was requested.
429	The account is in its 15-minute refresh cooldown, or 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 requested a conversation refresh!