Reference

Conversations

Read inbox conversations and messages, and send replies.

Conversations are the unified inbox: every chat of every connected account, on every channel. Conversations on accounts marked private are never visible to API keys. Replies follow the same rules as the inbox composer.

List conversations

GET/api/v1/conversationsScope inbox:read

Conversations sorted by latest activity. Filter by channel, accountId, leadId or unread=true. Private conversations are never returned.

Parameters

NameInTypeDescription
cursorquerystringOpaque cursor from the previous page's nextCursor.
limitqueryintegerPage size. 1 to 100. Default 50.
channelquerystringThe channel. One of linkedin, instagram, whatsapp, telegram, facebook.
accountIdquerystring (uuid)Only this connected account.
leadIdquerystring (uuid)Only this lead.
unreadquerybooleantrue returns only conversations with unread messages.

Example request

curl -s "https://app.graphkit.com/api/v1/conversations" \
  -H "Authorization: Bearer $GRAPHKIT_API_KEY"

Response 200

FieldTypeDescription
dataarray of objectThe page of results, newest first.
data[].idstring (uuid)UUID.
data[].channelstringThe channel. One of linkedin, instagram, whatsapp, telegram, facebook.
data[].accountIdstring (uuid)Only this connected account.
data[].leadIdstring (uuid) or nullOnly this lead.
data[].campaignIdstring (uuid) or nullCampaign id.
data[].isUnreadboolean
data[].unreadCountinteger
data[].lastMessageAtstring (date-time) or null
data[].lastMessagePreviewstring or null
data[].lastMessageDirectionstring or nullOne of inbound, outbound.
data[].archivedboolean
data[].createdAtstring (date-time)When it was created (RFC 3339, UTC).
nextCursorstring or nullPass back as cursor for the next page; null on the last page.
{
  "data": [
    {
      "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
      "channel": "linkedin",
      "accountId": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
      "leadId": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
      "campaignId": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
      "isUnread": false,
      "unreadCount": 0,
      "lastMessageAt": "2026-11-15T10:04:05Z",
      "lastMessagePreview": "Thanks, happy to chat next week.",
      "lastMessageDirection": "inbound",
      "archived": false,
      "createdAt": "2026-11-15T10:04:05Z"
    }
  ],
  "nextCursor": null
}

Errors

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

List messages

GET/api/v1/conversations/{id}/messagesScope inbox:read

Messages of one conversation, newest first.

Parameters

NameInTypeDescription
idpathstring (uuid)The resource id.
cursorquerystringOpaque cursor from the previous page's nextCursor.
limitqueryintegerPage size. 1 to 100. Default 50.

Example request

curl -s "https://app.graphkit.com/api/v1/conversations/0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99/messages" \
  -H "Authorization: Bearer $GRAPHKIT_API_KEY"

Response 200

FieldTypeDescription
dataarray of objectThe page of results, newest first.
data[].idstring (uuid)UUID.
data[].directionstringinbound from the lead, outbound from the account. One of inbound, outbound.
data[].bodystring
data[].statusstringCurrent status.
data[].attachmentsarray of object
data[].sentByUserIdstring (uuid) or nullThe teammate who sent it, for manual outbound messages.
data[].fromCampaignbooleanSent by a campaign step rather than a person.
data[].errorstring or null
data[].sentAtstring (date-time)
nextCursorstring or nullPass back as cursor for the next page; null on the last page.
{
  "data": [
    {
      "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
      "direction": "inbound",
      "body": "Thanks, happy to chat next week.",
      "status": "active",
      "attachments": [],
      "sentByUserId": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
      "fromCampaign": false,
      "error": null,
      "sentAt": "2026-11-15T10:04:05Z"
    }
  ],
  "nextCursor": null
}

Errors

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
404not_found: no such resource in this key's workspace.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

Send a reply

POST/api/v1/conversations/{id}/messagesScope inbox:write

Queues a reply from the conversation's own account, with the same rules as the inbox composer: channel message limits, opt-outs and account status all apply. The response is 202 with the pending message; it is sent in the background.

The reply is attributed to the user who created the API key. Subscribe to message.sent to learn when it was delivered.

Parameters

NameInTypeDescription
idpathstring (uuid)The resource id.
Idempotency-KeyheaderstringReplays the stored response for 24 hours (header Idempotent-Replayed: true). Reusing a key with a different request is 422; while the first request runs, 409. Up to 255 characters.

Request body

FieldTypeRequiredDescription
bodystringYes

Example request

curl -s -X POST "https://app.graphkit.com/api/v1/conversations/0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99/messages" \
  -H "Authorization: Bearer $GRAPHKIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"body":"Thanks Jane, Tuesday at 10:00 works. I will send an invite."}'

Response 202

FieldTypeDescription
idstring (uuid)UUID.
directionstringinbound from the lead, outbound from the account. One of inbound, outbound.
bodystring
statusstringCurrent status.
attachmentsarray of object
sentByUserIdstring (uuid) or nullThe teammate who sent it, for manual outbound messages.
fromCampaignbooleanSent by a campaign step rather than a person.
errorstring or null
sentAtstring (date-time)
{
  "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
  "direction": "inbound",
  "body": "Thanks, happy to chat next week.",
  "status": "active",
  "attachments": [],
  "sentByUserId": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
  "fromCampaign": false,
  "error": null,
  "sentAt": "2026-11-15T10:04:05Z"
}

Errors

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
404not_found: no such resource in this key's workspace.
400empty_message: The body is empty.
400message_too_long: Longer than the channel allows.
409lead_opted_out: The lead opted out; GraphKit will not message them.
409account_unavailable: The account is paused, disconnected or needs reconnecting.
409conversation_read_only: The conversation cannot be replied to.
409key_owner_missing: The user who created the key no longer exists. Create a new key.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

On this page