API RU
Early access. API keys are issued on request. How to get a key

Conversations

Saved messages of an account's conversation with a lead: outbound sequence steps, manual messages and replies.

Endpoints

#The Message object

A message from the saved conversation with a lead. The archive may be incomplete: see meta.completeness.

Attributes

  • objectstring
    Object type, always message.
  • idstring
    Opaque, stable message ID. Do not parse its format.
  • directionstring
    outbound: from the account to the lead; inbound: from the lead. Values: outbound inbound
  • authorstring
    campaign: a sequence step; manager: a manual message; lead: a lead reply; unknown: not determined. Values: campaign manager lead unknown
  • sent_atstring (date-time) or null
    When the message was sent or received. null if unknown.
  • statestring
    sent: sending confirmed; received: incoming message saved; unknown: outcome not confirmed. Values: sent received unknown
  • media_kindstring
    Attachment type. Files and links to them are not returned. Values: none photo video voice audio document sticker animation video_note contact location poll other unknown
  • textstring or null
    Saved text, up to 4000 characters. null if the text is unavailable. Up to 4000 characters.
  • text_truncatedboolean or null
    true: the text is shortened; false: the text is complete; null: completeness is unknown.
  • text_unavailableboolean
    true if the text is not returned. The reason is in text_unavailable_reason.
  • text_unavailable_reasonstring or null
    not_saved: the text was not saved; ownership_unproven: it is not proven that the message belongs to this conversation; source_conflict: sources disagree; purged: the text was deleted after the retention period. Values: not_saved ownership_unproven source_conflict purged
Message
{
  "object": "message",
  "id": "m_6b2e9f403a7c4d158e921c5a7f3b9d08",
  "direction": "outbound",
  "author": "campaign",
  "sent_at": "2026-10-26T07:30:00.000Z",
  "state": "sent",
  "media_kind": "none",
  "text": "Good afternoon, Anna! I'm writing from Example: could you tell me who handles outreach at your company?",
  "text_truncated": false,
  "text_unavailable": false,
  "text_unavailable_reason": null
}

#List lead conversation

GET/v1/leads/{id}/messages

Saved messages of the conversation with a lead, oldest first. Requires the messages:read permission and "Message text" enabled on the key. The archive may be incomplete: see meta.completeness.

Permission
messages:read and “Message text” enabled on the key
Request weight
3

Parameters

  • idstring (uuid), pathrequired
    Lead ID.
  • limitinteger, queryoptional
    Number of objects to return per page. From 1 to 100. Defaults to 50.
  • cursorstring, queryoptional
    The next_cursor value from the previous response. Other filters must match the first request.

Response

A list: object, data (an array of Message objects), has_more, next_cursor, meta. See Pagination.

The meta field

  • completenessobject
    How complete the saved conversation archive with the lead is. Completeness is not calculated yet: overall and inbound are returned as partial, outbound as unknown.
    Child attributes
    • overallstring
      Overall completeness: complete, partial or unknown. Values: complete partial unknown
    • inboundstring
      Completeness of inbound messages. Values: complete partial unknown
    • outboundstring
      Completeness of outbound messages. Values: complete partial unknown
    • available_fromstring (date-time) or null
      Start of the period covered by the data. null if unknown.
    • available_tostring (date-time) or null
      End of the period covered by the data. null if unknown.
    • observed_atstring (date-time)
      Time the server read the data.

Endpoint-specific errors

  • cursor_mismatch: The cursor is corrupted, was issued for a different route or filters, or the key's permissions and scope have changed.
  • scope_required: The key does not have permission for this read. Texts also require "Message text" to be enabled.
  • not_found: The object was not found or is outside the key's scope. An unknown path also returns 404.
  • cursor_expired: The cursor expired: 15 minutes for lists, 30 days for the event feed.

Common errors are described in Errors.

Request
curl https://api.melioralab.io/v1/leads/5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31/messages \
  -H "Authorization: Bearer $MELIORA_API_KEY"
Response
{
  "object": "list",
  "data": [
    {
      "object": "message",
      "id": "m_6b2e9f403a7c4d158e921c5a7f3b9d08",
      "direction": "outbound",
      "author": "campaign",
      "sent_at": "2026-10-26T07:30:00.000Z",
      "state": "sent",
      "media_kind": "none",
      "text": "Good afternoon, Anna! I'm writing from Example: could you tell me who handles outreach at your company?",
      "text_truncated": false,
      "text_unavailable": false,
      "text_unavailable_reason": null
    },
    {
      "object": "message",
      "id": "m_c7a1d3e59b2f4a68b4d05e8f2a6c1b97",
      "direction": "inbound",
      "author": "lead",
      "sent_at": "2026-10-26T09:12:00.000Z",
      "state": "received",
      "media_kind": "none",
      "text": "Hello! That's me, let's have a call tomorrow.",
      "text_truncated": null,
      "text_unavailable": false,
      "text_unavailable_reason": null
    },
    {
      "object": "message",
      "id": "m_a3f8c6e27d1b4e949c058b2d4f7a6e13",
      "direction": "inbound",
      "author": "lead",
      "sent_at": "2026-10-26T09:13:30.000Z",
      "state": "received",
      "media_kind": "photo",
      "text": null,
      "text_truncated": null,
      "text_unavailable": true,
      "text_unavailable_reason": "not_saved"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "meta": {
    "completeness": {
      "overall": "partial",
      "inbound": "partial",
      "outbound": "unknown",
      "available_from": "2026-10-26T07:30:00.000Z",
      "available_to": "2026-10-27T09:15:42.000Z",
      "observed_at": "2026-10-27T09:15:42.000Z"
    }
  }
}