Skip to content
ThreadkiteThreadkite Docs

Messages in a thread

GET
/v1/threads/{id}/messages
curl --request GET \
  --url 'https://api.threadkite.app/v1/threads/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/messages?limit=50' \
  --header 'Authorization: Bearer <token>'

Newest first; pass nextCursor back as cursor for older ones. Every message in a thread you can see is included.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 50 >= 1 <= 100
cursor

The nextCursor from the previous page

string
<= 500 characters

The nextCursor from the previous page

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
data
required

Newest first

Array<object>
object
id
required
string format: uuid
threadId
required
string format: uuid
chapterId
required

The chapter of the thread it is in

string format: uuid
kind
required
string
Allowed values: message note automated event
direction
required
string
Allowed values: in out internal
channel
required
string
Allowed values: email sms whatsapp chat phone form api marketplace visit messenger instagram internal
contactId
required
string format: uuid
nullable
locationId
required
string format: uuid
nullable
source
required
One of:
object
id
required
string format: uuid
key
required
string
name
required
string
logoUrl
required

Logo address; null shows an initial badge

string
nullable
isLead
required

Counts as a lead in reports

boolean
isTest
required

A made-up lead from “Send a test lead”, never counted

boolean
leadOverride
required

A person marked (true) or unmarked (false) it as a lead; null when the rule decided

boolean
nullable
leadType
required
string
nullable
items
required

The catalogue items the message named, in order

Array
One of: discriminator: type
object
id
required
string format: uuid
source
required

Where the item came from: manual, csv, api or an integration key

string
externalId
required

The item’s id in its source

string
locationId
required
string format: uuid
nullable
title
required

From the attributes

string
status
required

The availability: in_stock, out_of_stock, preorder or backorder for products; an industry pack’s item types have their own

string
price
required
One of:
object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
billing
required

How the price is charged: one_off (once), monthly (every month) or annual (every year)

string
Allowed values: one_off monthly annual
images
required

Image links, main image first

Array<string>
archivedAt
required

When it was removed from the catalogue (no longer in stock). Removed items stay on the leads and threads that mention them

string format: date-time
nullable
url
required

Advert or product page

string
nullable
addOn
required

Usually sold as an add-on to something else (a warranty, delivery, an onboarding package). Suggestions only

boolean
addOnFor
required

The item types it is usually added to; empty means anything

Array<string>
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
attributes
required
object
title
required

Google/Meta title

string
<= 150 characters
description

Google/Meta description

string
<= 5000 characters
link

Product page. Google/Meta link

string format: uri
imageLinks

Main image first. Google/Meta image_link and additional_image_link

Array<string>
<= 11 items
price
required

Google/Meta price

object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
salePrice

Google/Meta sale_price

object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
availability

Google/Meta availability

string
default: in_stock
Allowed values: in_stock out_of_stock preorder backorder
condition

Google/Meta condition

string
default: new
Allowed values: new refurbished used
brand

Google/Meta brand

string
<= 70 characters
gtin

GTIN-8, 12, 13 or 14. Google/Meta gtin

string
mpn

Google/Meta mpn

string
<= 70 characters
sku

Your own stock code

string
<= 100 characters
googleProductCategory

Google/Meta google_product_category

string
<= 750 characters
productType

Google/Meta product_type

string
<= 750 characters
itemGroupId

Shared by variants. Google/Meta item_group_id

string
<= 50 characters
size

Google/Meta size

string
<= 100 characters
colour

Google/Meta color

string
<= 100 characters
material

Google/Meta material

string
<= 200 characters
pattern

Google/Meta pattern

string
<= 100 characters
customLabel0

Google/Meta custom_label_0

string
<= 100 characters
customLabel1

Google/Meta custom_label_1

string
<= 100 characters
customLabel2

Google/Meta custom_label_2

string
<= 100 characters
customLabel3

Google/Meta custom_label_3

string
<= 100 characters
customLabel4

Google/Meta custom_label_4

string
<= 100 characters
type
required
string
Allowed values: product
subject
required
string
nullable
text
required
string
html
required
string
nullable
author
required
object
userId
required

Set when a person wrote it

string
nullable
name
required
string
nullable
status
required

Outbound: queued, sent, delivered, opened, read, failed… Inbound: received

string
nullable
statusAt
required
string format: date-time
nullable
failureReason
required

Why delivery failed, when the status is failed, bounced or complained

string
nullable
canRetry
required

Not sent after every retry: POST /v1/messages/{id}/retry tries again

boolean
automationKey
required
string
nullable
transactional
required
boolean
logged
required

Sent outside Threadkite and logged here

boolean
externalId
required
string
nullable
authVerdict
required

Email authentication: pass, fail, unverified

string
nullable
spamVerdict
required
string
nullable
responseSeconds
required

First reply: seconds it took

number
nullable
participants
required
Array<object>
object
role
required
string
Allowed values: from to cc bcc
address
required
string
name
required
string
nullable
contactId
required
string format: uuid
nullable
attachments
required
Array<object>
object
id
required
string format: uuid
fileName
required
string
mimeType
required
string
size
required
number
scanStatus
required
string
Allowed values: pending clean infected
inline
required

An inline image in the email’s HTML (a pasted photo, a signature logo), not a file attached

boolean
contentId
required

For an inline image: the Content-ID the HTML’s cid: image points at

string
nullable
skippedAttachments
required

Files the email came with that were not kept (a type we refuse, too large, or failed the virus check)

Array<object>
object
fileName
required
string
reason
required

Why it was not kept, in plain words

string
tracking
required
One of:
object
landingPageUrl
required
string
nullable
referrer
required
string
nullable
utmSource
required
string
nullable
utmMedium
required
string
nullable
utmCampaign
required
string
nullable
utmTerm
required
string
nullable
utmContent
required
string
nullable
utmId
required

The ad platform’s campaign id

string
nullable
clickId
required

The ad click id, as kind:value

string
nullable
campaign
required

The campaign the lead came from (its UTMs or its lead ad)

object
id
required
string format: uuid
name
required
string
trafficChannel
required

Where the visit came from, worked out when the lead arrived

string
nullable
Allowed values: paid_search paid_social display email sms affiliate organic_search organic_social referral direct other
consentCategories
required
Array<string>
nullable
data
required

Render-only extras, such as the fields of a form

object
key
additional properties
any
lead
required
One of:
object
format
required
string
Allowed values: adf labelled extracted sender
provider
required

The lead provider, as the email names it

string
nullable
forwardedBy
required
One of:
object
userId
required
string
nullable
name
required
string
forwardNote
required

What they wrote when forwarding it

string
nullable
needsSource
required

A forwarded lead whose real source nobody has picked yet

boolean
receivedLeadId
required
string format: uuid
nullable
reference
required
One of:
object
messageId
required
string format: uuid
threadId
required
string format: uuid
contactName
required
string
subject
required
string
nullable
appointment
required
One of:
object
id
required
string format: uuid
action
required

Events: booked, moved, cancelled, confirmed, completed, no_show. Messages to the customer: confirmation, reminder_day, reminder_soon, updated, cancelled.

string
call
required
One of:
object
direction
required
string
Allowed values: in out
outcome
required
string
nullable
Allowed values: answered missed voicemail failed
durationSeconds
required

Seconds talking

number
nullable
from
required

The caller (null when withheld or erased)

string
nullable
to
required

The number they called

string
nullable
menuChoice
required

The menu option the caller chose

string
nullable
forwardedTo
required

Numbers the call was forwarded to

Array<string>
voicemail
required

They left a voicemail

boolean
transcript
required

The voicemail, as text

string
nullable
hasRecording
required

GET /v1/messages/{id}/recording gives a link to play it

boolean
recordingHeldBy
required

The recording is held in this provider’s account and cannot be played here now (the connection is gone)

string
nullable
recordingSeconds
required
number
nullable
recordingPauses
required

When the recording was paused during the call (for card details); it has silence for each

Array<object>
object
pausedAt
required
string format: date-time
resumedAt
required
string format: date-time
nullable
recordingDeleted
required

The recording is no longer available (deleted at the end of the retention period, on erasure, or in the provider account)

boolean
source
required
One of:
object
id
required
string format: uuid
name
required
string
loggedFrom
required

Set for a call made outside a connected phone system and logged in the mobile or web app (POST /v1/threads/{id}/calls)

string
nullable
Allowed values: mobile web
loggedOutcome
required

For logged calls: what they picked after the call

string
nullable
Allowed values: answered no_answer voicemail wrong_number
callId
required

The call (GET /v1/calls/{id}); null for a call logged in the app with no phone system behind it

string format: uuid
nullable
summary
required

A short summary of the call, made from its recording

string
nullable
hasTranscript
required

GET /v1/calls/{id}/transcript gives who said what

boolean
disposition
required

For a call made in Threadkite: how it went, as the person said afterwards

string
nullable
Allowed values: answered no_answer voicemail wrong_number
notes
required

For a call made in Threadkite: the notes saved after it

string
nullable
suggestedContact
required
One of:
object
name
object
current
required
string
nullable
suggested
required
string
email
object
current
required
string
nullable
suggested
required
string
phone
object
current
required
string
nullable
suggested
required
string
company
object
current
required
string
nullable
suggested
required
string
companyId
required
string format: uuid
nullable
jobTitle
object
current
required
string
nullable
suggested
required
string
company
string
template
required
One of:
object
name
required
string
language
required
string
category
required
string
Allowed values: marketing utility authentication
video
One of:
object
id
required
string format: uuid
title
required
string
status
required

expired once it has been deleted (the message shows “Video expired”)

string
Allowed values: uploading processing ready failed expired
lengthSeconds
required
number
nullable
posterUrl
required

Signed poster image (valid a few hours), once the video is ready

string
nullable
opens
required

Times the watch page was opened

number
opened
required

They opened the watch page

boolean
started
required

They started watching

boolean
watched50
required

They watched at least half

boolean
watched90
required

They watched (nearly) all of it

boolean
record
required
One of:
object
recordId
required
string format: uuid
source
required
string
sourceName
required
string
type
required
string
icon
required
string
Allowed values: invoice quote signature document payment booking order link
label
required
string
url
required
string
nullable
status
required
string
nullable
tone
required
string
Allowed values: success warning danger neutral
amount
required
One of:
object
value
required

In major units

number
currency
required
string
details
required
object
key
additional properties
string
previousStatus
required

The status before this event

string
nullable
first
required

The first line about the record on this thread: shown as a card

boolean
late
required

Arrived late: older than the record’s state, changed nothing

boolean
text
required

The line for people

string
pin
required
One of:
object
at
required

When it was pinned

string format: date-time
by
required
One of:
object
id
required
string
name
required
string
redactedAt
required
string format: date-time
nullable
createdAt
required
string format: date-time
nextCursor
required

Pass as cursor for older messages; null at the start of the thread

string
nullable

Example 

{
  "data": [
    {
      "kind": "message",
      "direction": "in",
      "channel": "email",
      "source": {
        "key": "website-form",
        "name": "Website form"
      },
      "leadType": "quote",
      "items": [
        {
          "source": "my-dms",
          "externalId": "SKU-1042",
          "title": "Oak dining table",
          "status": "in_stock",
          "price": {
            "amountMinor": 1299500,
            "currency": "GBP"
          },
          "billing": "one_off",
          "addOnFor": [
            "product"
          ],
          "attributes": {
            "title": "Merino jumper",
            "price": {
              "amountMinor": 1299500,
              "currency": "GBP"
            },
            "salePrice": {
              "amountMinor": 1299500,
              "currency": "GBP"
            },
            "availability": "in_stock",
            "condition": "new"
          },
          "type": "product"
        }
      ],
      "text": "Is this still available?",
      "author": {
        "name": "James Patel"
      },
      "failureReason": "The address does not exist",
      "automationKey": "invoice",
      "participants": [
        {
          "role": "from",
          "address": "sarah.turner@example.co.uk"
        }
      ],
      "attachments": [
        {
          "fileName": "photo.jpg",
          "mimeType": "image/jpeg",
          "size": 182044,
          "scanStatus": "pending",
          "contentId": "ii_m1x2y3z40"
        }
      ],
      "skippedAttachments": [
        {
          "fileName": "video.mov",
          "reason": "video.mov is larger than 20 MB."
        }
      ],
      "tracking": {
        "clickId": "gclid:Cj0KCQjw",
        "campaign": {
          "name": "Spring sale"
        },
        "trafficChannel": "paid_search"
      },
      "lead": {
        "format": "adf",
        "forwardedBy": {
          "name": "Chris Moore"
        }
      },
      "reference": {
        "contactName": "James Turner"
      },
      "appointment": {
        "action": "booked"
      },
      "call": {
        "direction": "in",
        "outcome": "answered",
        "recordingHeldBy": "Twilio",
        "source": {
          "name": "Google Ads"
        },
        "loggedFrom": "mobile",
        "loggedOutcome": "answered",
        "disposition": "answered"
      },
      "template": {
        "name": "missed_call",
        "language": "en_GB",
        "category": "marketing"
      },
      "video": {
        "status": "uploading"
      },
      "record": {
        "icon": "invoice",
        "tone": "success",
        "amount": {
          "value": 289,
          "currency": "GBP"
        },
        "text": "Invoice INV-8812: Awaiting payment → Paid"
      },
      "pin": {
        "by": {
          "id": "usr_8f2c",
          "name": "James Patel"
        }
      }
    }
  ]
}

401

Section titled “401”

Missing or invalid API key

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

402

Section titled “402”

The organisation is on the Free plan (code upgrade_required)

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
feature
required

The feature that needs Pro

string
nullable
Allowed values: extraSeats connections aiAssistant aiReplies rules fullReports api inboxes bulkMessages videoMessages
upgradePath
required

Where to upgrade or pay, in the web app

string

Example 

{
  "statusCode": 402,
  "code": "upgrade_required",
  "message": "Connections are part of Pro. Upgrade to connect texts, calls and more.",
  "feature": "extraSeats",
  "upgradePath": "/settings/billing"
}

403

Section titled “403”

The key does not have the scope (or the person the permission)

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

404

Section titled “404”
Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

429

Section titled “429”

Rate limit reached

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
retryAfter
required

Seconds until another request will be accepted

number

Example 

{
  "statusCode": 429,
  "code": "rate_limited",
  "message": "Too many requests. Each key can make 120 requests a minute; try again in 12 seconds.",
  "retryAfter": 12
}