Starts a discussion thread on a conversation item with a first comment. Each item can have only one thread.
POST/v2/api/threads
Behavior
Starts a discussion thread on a conversation item. content becomes the thread's first comment, and the response is the full thread including that comment.
Each item can have only one thread. If one already exists, the request returns 409 with code THREAD_ALREADY_EXISTS — find it with GET /v2/api/threads and add a comment instead.
Mentions
Mention teammates inline in content with @[Display Name](usr-xxxx) — see the mentions guide.
Errors
Status
Code
When
400
INVALID_THREAD_ENTITY_TYPE
entity_type is not one of CALL, TEXT_MESSAGE, CONVERSATION_NOTE
400
EMPTY_NOTE_CONTENT
content is missing or blank
400
NOTE_CONTENT_TOO_LONG
content exceeds 4,000 characters
404
CONVERSATION_ITEM_NOT_FOUND
No conversation item with this entity_id
409
THREAD_ALREADY_EXISTS
The item already has a thread
Authorization
Authorizationstring · headerrequired
Api-Key ak_live_…
Body
entity_typeenum<string>required
Type of the conversation item to attach the thread to.
CALLTEXT_MESSAGECONVERSATION_NOTE
entity_idstringrequired
ID of the conversation item (cll-*, msg-*, or not-*).
contentstringrequired
First comment text (max 4000 characters). Mention teammates inline with @[Name](usr-...).
Responses
201Thread created with its first comment
dataobject
10 fields
idstring
Thread ID (cth-*)
entity_typeenum<string>
Type of the conversation item the thread is attached to.
CALLTEXT_MESSAGECONVERSATION_NOTE
entity_idstring
ID of the conversation item (cll-*, msg-*, or not-*).
contact_numberstring
The contact's phone number (E.164).
resolvedboolean
resolved_atstring<date-time> | null
resolved_byobject
Author of a note or comment.
2 fields
idstring
namestring | null
comment_countinteger
created_atstring<date-time>
commentsobject[]
6 fields
idstring
Comment ID (thc-*)
contentstring
Comment text, with mentions inline as @[Name](usr-...).
userobject
Author of a note or comment.
2 fields
idstring
namestring | null
mentionsobject[]
3 fields
user_idstring
namestring | null
deletedboolean
true if the mentioned user has since been removed from the team.