Conversations
Request conversation history
Requests older history for provider=whatsapp private chats only, excluding whatsapp-protocol. account_id must be one non-empty path segment without whitespace or slashes, including encoded slashes; invalid paths return 400 invalid_request. Subscribe to conversation.history first; available batches arrive asynchronously with data.history.source=on_demand. HTTP 202 and status=accepted acknowledge acceptance only, not messages or completion. request_id is for HTTP troubleshooting, not a task ID or callback correlation. Batches may be multiple, duplicate, late, or absent. To continue, use the earliest received native content message with complete id, sent_at and direction as before; exclude type=call synthetic records and do not add type to before. There is no next-page cursor or completion status: empty or short batches and timeouts do not prove the end of history. Callbacks may arrive after HTTP timeouts; do not retry automatically. 400 may return invalid_request, provider_invalid_request (including synthetic call anchors), or unsupported_conversation_type for groups/channels. Other providers return 501 unsupported_by_provider. A valid account path for a missing account or one outside the workspace returns 404 account_not_found (numeric_code=20020); unclassified internal errors return 500 request_conversation_history_failed (numeric_code=37016).
https://api.unifyport.ai/v1/accounts/{account_id}/conversations/history/requestBefore you call
Use a server-side X-Api-Key for the workspace that owns the resource. Replace every placeholder before running a sample.
Prepare your parameters
- account_id
- Use data.id from account creation or an account query. Account identifiers belong to the workspace selected by X-Api-Key. Get account
Request parameters
Headers
X-Api-KeyWorkspace API key. The workspace is resolved from this header.
Content-TypeUse application/json when sending a JSON request body.
Path parameters
account_idIdentifier used in the conversations route.
Request body
conversation_idStandard WhatsApp private-chat LID matching ^[0-9]+@lid$, for the conversation containing before. Phone numbers and other conversation types are not accepted.
pattern: ^[0-9]+@lid$
beforeobjectrequiredPosition of one native content message in the same conversation; all fields must come from that message and cannot be null. Synthetic type=call records are invalid even with all three fields. Do not include type in the request.
beforePosition of one native content message in the same conversation; all fields must come from that message and cannot be null. Synthetic type=call records are invalid even with all three fields. Do not include type in the request.
message_idNative content message id containing a non-whitespace character. Synthetic call record IDs are invalid even after trimming. Do not substitute the top-level event id or HTTP request_id.
minLength: 1 · pattern: \S
sent_atRFC3339 send time of that message, with Unix seconds greater than 0. Do not substitute event occurred_at or the current time.
format: date-time
directionMessage direction relative to this account: inbound for received, outbound for sent.
enum: inbound, outbound
limitRequested count, not a guaranteed result count. Defaults to 50 only when omitted; null, 0, non-integers and values above 50 return invalid_request. Valid range: 1..50.
minimum: 1 · maximum: 50
Understand the result
Use the documented response fields and HTTP status. Successful 204 responses have no body; use X-Request-Id for diagnosis. Follow the related operations for the next step.
Response 202 Accepted
{
"request_id": "<REQUEST_ID>",
"data": {
"status": "accepted",
"conversation_id": "100000000000002@lid",
"limit": 50
}
}
Response body
statusaccepted confirms request acceptance only, not receipt of history or completion.
enum: accepted
conversation_idStandard conversation ID for this history request.
limitEffective requested count limit for this history request, from 1 to 50.
minimum: 1 · maximum: 50
Responses
202202 Accepted
Request succeeded. See the example response body.
400Bad Request
The request body, path, or parameters are invalid.
401Unauthorized
The X-Api-Key header is missing or invalid.
404Not Found
The requested provider resource could not be found.
409Conflict
The requested operation conflicts with an existing provider account or resource.
500Internal Server Error
The service encountered an unexpected error.
501Not Implemented
The selected provider does not implement this operation.
502Bad Gateway
The provider adapter or upstream provider could not complete the operation.
If the request fails
Inspect HTTP status and error.code/numeric_code, and keep request_id for diagnosis. Correct invalid parameters, complete required authorization or check runtime state as appropriate. Confirm the outcome before retrying a send or another write. Error reference
- invalid_request · 10000 · 400
- Check required fields, formats and channel conditions, then correct the request.
- invalid_api_key · 11001 · 401
- Check X-Api-Key and whether the workspace is active.