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.
GET /api/v1/conversationsScope inbox:read
Conversations sorted by latest activity. Filter by channel, accountId, leadId or unread=true. Private conversations are never returned.
Name In Type Description cursorquery string Opaque cursor from the previous page's nextCursor. limitquery integer Page size. 1 to 100. Default 50. channelquery string The channel. One of linkedin, instagram, whatsapp, telegram, facebook. accountIdquery string (uuid) Only this connected account. leadIdquery string (uuid) Only this lead. unreadquery boolean true returns only conversations with unread messages.
curl -s "https://app.graphkit.com/api/v1/conversations" \
-H "Authorization: Bearer $GRAPHKIT_API_KEY "
Field Type Description dataarray of object The page of results, newest first. data[].idstring (uuid) UUID. data[].channelstring The channel. One of linkedin, instagram, whatsapp, telegram, facebook. data[].accountIdstring (uuid) Only this connected account. data[].leadIdstring (uuid) or null Only this lead. data[].campaignIdstring (uuid) or null Campaign id. data[].isUnreadboolean data[].unreadCountinteger data[].lastMessageAtstring (date-time) or null data[].lastMessagePreviewstring or null data[].lastMessageDirectionstring or null One of inbound, outbound. data[].archivedboolean data[].createdAtstring (date-time) When it was created (RFC 3339, UTC). nextCursorstring or null Pass 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
}
Status Code and meaning 401 invalid_api_key: the key is missing, unknown or revoked.403 insufficient_scope: the key lacks the scope this endpoint needs.429 rate_limited: more than 300 requests in a minute; wait for Retry-After.
GET /api/v1/conversations/{id}/messagesScope inbox:read
Messages of one conversation, newest first.
Name In Type Description idpath string (uuid) The resource id. cursorquery string Opaque cursor from the previous page's nextCursor. limitquery integer Page size. 1 to 100. Default 50.
curl -s "https://app.graphkit.com/api/v1/conversations/0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99/messages" \
-H "Authorization: Bearer $GRAPHKIT_API_KEY "
Field Type Description dataarray of object The page of results, newest first. data[].idstring (uuid) UUID. data[].directionstring inbound from the lead, outbound from the account. One of inbound, outbound.data[].bodystring data[].statusstring Current status. data[].attachmentsarray of object data[].sentByUserIdstring (uuid) or null The teammate who sent it, for manual outbound messages. data[].fromCampaignboolean Sent by a campaign step rather than a person. data[].errorstring or null data[].sentAtstring (date-time) nextCursorstring or null Pass 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
}
Status Code and meaning 401 invalid_api_key: the key is missing, unknown or revoked.403 insufficient_scope: the key lacks the scope this endpoint needs.404 not_found: no such resource in this key's workspace.429 rate_limited: more than 300 requests in a minute; wait for Retry-After.
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.
Name In Type Description idpath string (uuid) The resource id. Idempotency-Keyheader string Replays 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.
Field Type Required Description bodystring Yes
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."}'
Field Type Description idstring (uuid) UUID. directionstring inbound from the lead, outbound from the account. One of inbound, outbound.bodystring statusstring Current status. attachmentsarray of object sentByUserIdstring (uuid) or null The teammate who sent it, for manual outbound messages. fromCampaignboolean Sent 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"
}
Status Code and meaning 401 invalid_api_key: the key is missing, unknown or revoked.403 insufficient_scope: the key lacks the scope this endpoint needs.404 not_found: no such resource in this key's workspace.400 empty_message: The body is empty.400 message_too_long: Longer than the channel allows.409 lead_opted_out: The lead opted out; GraphKit will not message them.409 account_unavailable: The account is paused, disconnected or needs reconnecting.409 conversation_read_only: The conversation cannot be replied to.409 key_owner_missing: The user who created the key no longer exists. Create a new key.429 rate_limited: more than 300 requests in a minute; wait for Retry-After.