Skip to content

Get Conversation Messages API

The Get Conversation Messages API lets a developer retrieve messages in a conversation through one exact operation: GET /v1/messages/{conversationId}. Use this page to build a client that supplies the required path and query values, sends the documented authorization header, and parses the documented success and error response shapes without guessing at fields that the contract does not define.

Get messages in a conversation — operation summary and exact endpoint

Get messages in a conversation is the operation summary for this endpoint. The exact request line is GET /v1/messages/{conversationId}, where conversationId is the platform conversation ID placed in the path. The origin is represented as {{API_BASE_URL}} in examples on this page, so the path itself remains unchanged. Before calling the endpoint, confirm that you have a conversationId, a platform value, and an accountId, because all three are required by the contract. The optional limit and after values control the requested page size and pagination input, but the source contract does not define the format of after or the ordering of returned messages, so a client should treat those behaviours as unspecified rather than assuming them.

Authorization

Send the access key in the x-access-key header. The authorization contract names the credential accessKey and the header x-access-key, with the token supplied as the header value. A request that omits this header does not match the documented authorization contract. Keep the token out of query parameters and out of logged URLs, and check the header name exactly, including its lowercase spelling, when debugging a failed request.

Path and query parameters field map

The path contains one required parameter, conversationId, typed as a string and described as the platform conversation ID. Replace the placeholder in the path with that value for the conversation you want to read. The query string then carries the remaining required and optional inputs. The platform parameter is required and must be one of the documented enum values, instagram or twitter. The accountId parameter is required, typed as a string, and described as the integration ID. The limit parameter is optional, typed as an integer, defaults to 25, and must fall within the range 1 <= value <= 100 when supplied. The after parameter is optional and typed as a string. A practical input check is to validate conversationId, platform, and accountId for presence before sending, validate platform against the two enum values, and validate limit as an integer in range before adding it to the query string.

Request example

Start with the minimal request shown in the request example titled Minimal request for Get Conversation Messages API, which includes the required platform and accountId query values. Then add limit and after only when you need to control the page size or supply a pagination input, as shown in the request example titled Request with limit and after. When you receive a response, branch on the HTTP status first and on the success field second. For a 200 response, read the messages array and the nextCursor field. For any documented error status, read the message field and do not assume a specific cause, because the contract shows the shape of the error body without defining individual message values.

200 response field map and worked example

A 200 response is an application/json object with a required boolean success field, a required messages array, and a required nextCursor field that may be a string or null. Each item in messages is an object with a required string id, a required text field that may be a string or null, a required from object, and a required timestamp field that may be a string or null in date-time format. The from object contains a required id that may be a string or null and a required name that may be a string or null. In a client, guard every nullable field before rendering or storing it, because null is a valid value for text, from.id, from.name, timestamp, and nextCursor. The worked parsing example in the response example titled 200 response example shows one message with its sender object, timestamp, and nextCursor, which is the shape your parser should expect.

Error status matrix 400, 402, 403, 404 and 502

The documented error statuses are 400, 402, 403, 404, and 502, each with an application/json body shaped as an object with a required boolean success field and a required string message field. The error matrix below lists each status with that exact shape and deliberately does not assign a specific cause or message value to any status, because those details are not defined in the contract. In client code, handle each status explicitly, surface the returned message to the caller or operator, and avoid retry logic that assumes a cause the contract does not state. A 502 in particular should be treated as a documented status to handle, not as evidence about the underlying platform.

Pagination inputs limit and after

Pagination inputs are limit and after. The limit parameter is optional, defaults to 25, and accepts integers from 1 to 100 inclusive. The after parameter is optional and typed as a string. The 200 response returns nextCursor, typed as string or null, alongside the messages array. The contract does not state that nextCursor is passed back as after, nor does it define the format of after, so a client should store nextCursor from a response and only use it as an after value if that behaviour is confirmed during implementation and testing. Until then, document the assumption in your own code comments and verify it against the implemented service rather than treating it as guaranteed.

Path and query parameters
ParameterLocationTypeRequiredConstraints / description
conversationIdpathstringrequiredPlatform conversation ID.
platformquerystringrequired"instagram" | "twitter"
accountIdquerystringrequiredIntegration ID.
limitqueryintegeroptionalDefault 25; range 1 <= value <= 100
afterquerystringoptionalNo format defined in source contract

Exact contract values preserved; origin modularised as {{API_BASE_URL}}.

200 response fields
FieldTypeRequiredNotes
successbooleanrequired
messagesarray<object>required
messages[].idstringrequiredPlatform message ID
messages[].textstring | nullrequiredNullable
messages[].fromobjectrequired
messages[].from.idstring | nullrequiredNullable
messages[].from.namestring | nullrequiredNullable
messages[].timestampstring | nullrequiredNullable; date-time format when a string
nextCursorstring | nullrequiredNullable

Nullable types preserved from typed contract.

Documented error statuses
StatusContent typeBody shapeSpecific message value
400application/json{ success: boolean, message: string }Not defined
402application/json{ success: boolean, message: string }Not defined
403application/json{ success: boolean, message: string }Not defined
404application/json{ success: boolean, message: string }Not defined
502application/json{ success: boolean, message: string }Not defined

Specific message values and causes are not defined in the source contract and are not invented here.

Input contract checklist
CheckExpected value
conversationId present in pathrequired string
platform present in query"instagram" | "twitter"
accountId present in queryrequired string
limit if suppliedinteger, default 25, range 1 <= value <= 100
after if suppliedoptional string
Authorization headerx-access-key: <token>

Checklist derived directly from the preserved contract.

Minimal request for Get Conversation Messages API
curl -X GET "{{API_BASE_URL}}/v1/messages/{conversationId}?platform=instagram&accountId=string"
Request with limit and after
curl -X GET "{{API_BASE_URL}}/v1/messages/{conversationId}?platform=instagram&accountId=string&limit=25&after=string" -H "x-access-key: <token>"
200 response example
{
  "success": true,
  "messages": [
    {
      "id": "string",
      "text": "string",
      "from": {
        "id": "string",
        "name": "string"
      },
      "timestamp": "2019-08-24T14:15:22Z"
    }
  ],
  "nextCursor": "string"
}
Error response example for 400, 402, 403, 404 and 502
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
conversationId#1conversationIdstring__0YesPlatform conversation ID.
platform#2platformstring__0Yeskind: schemaValueIn; value: "instagram" | "twitter"
accountId#3accountIdstring__0YesIntegration ID.
limit#4limitinteger__0Nokind: schemaDefault; value: 25 | kind: schemaRange; value: 1 <= value <= 100
after#5afterstring__0No
response#6responseobject__0
response#6response.successboolean__1Yes
response#6response.messagesarray<object>__2Yes
response#6response.messages[]object__3
response#6response.messages[].idstring__4YesPlatform message ID
response#6response.messages[].textstring | null__5Yes
response#6response.messages[].text[variant1]string__5_type:string
response#6response.messages[].text[variant2]null__5_type:null
response#6response.messages[].fromobject__6Yes
response#6response.messages[].from.idstring | null__7Yes
response#6response.messages[].from.id[variant1]string__7_type:string
response#6response.messages[].from.id[variant2]null__7_type:null
response#6response.messages[].from.namestring | null__8Yes
response#6response.messages[].from.name[variant1]string__8_type:string
response#6response.messages[].from.name[variant2]null__8_type:null
response#6response.messages[].timestampstring | null__9Yeskind: schemaFormat; value: date-time
response#6response.messages[].timestamp[variant1]string__9_type:stringkind: schemaFormat; value: date-time
response#6response.messages[].timestamp[variant2]null__9_type:nullkind: schemaFormat; value: date-time
response#6response.nextCursorstring | null__10Yes
response#6response.nextCursor[variant1]string__10_type:string
response#6response.nextCursor[variant2]null__10_type:null
response#7responseobject__0
response#7response.successboolean__1Yes
response#7response.messagestring__2Yes