Skip to content
↑↓ navigate↵ openEsc close
Bahasa IndonesiaEnglish

API reference

Chat

Buyer conversations, replies, internal notes, and labels.

List chat conversations

GET/v1/chat/conversations

Inbox, most recent activity first.

Scopes:chat:read

Query parameters

  • storeIdstringoptional

    format: uuid

  • filterstringoptional

    One of:allunreadneeds_humanopenresolvedlate

  • assigneestringoptional

    me, unassigned, or a user id.

    max length 40

  • labelstringoptional

    max length 40

  • qstringoptional

    max length 100

  • beforestringoptional

    format: date-time

  • limitintegeroptional

    min 1 · max 100

Response200 · application/json

OK

  • itemsarray<ChatConversation>required
    Show 22 child attributes
    • contactIdstringrequirednullable

      format: uuid

    • assignedUserIdstringrequirednullable

      format: uuid

    • labelsarray<string>required
    • waitingSincestringrequirednullable

      Oldest unanswered buyer message; null when the shop spoke last.

      format: date-time

    • latebooleanrequired

      Waiting longer than the tenant's response target.

    • idstringrequired

      format: uuid

    • storeIdstringrequired

      format: uuid

    • storeNamestringrequired
    • marketplacestringrequired

      One of:tiktokshopeelazadatokopedia

    • externalConversationIdstringrequired
    • buyerNamestringrequirednullable
    • buyerAvatarstringrequirednullable
    • canSendbooleanrequired

      False when the marketplace does not allow the shop to message this buyer.

    • unreadCountintegerrequired
    • lastMessageAtstringrequirednullable

      format: date-time

    • lastMessagePreviewstringrequirednullable
    • lastMessageRolestringrequirednullable

      One of:buyershopagentsystemrobot

    • statusstringrequired

      One of:openresolved

    • needsHumanbooleanrequired
    • handoffReasonstringrequirednullable
    • agentPausedbooleanrequired
    • hasDraftbooleanrequired
Example request · curl
curl "https://api.comnethub.app/v1/chat/conversations?limit=20" \
  -H "Authorization: Bearer $THECOMNET_API_KEY"

Get chat conversation

GET/v1/chat/conversations/{conversationId}

Conversation with messages, agent draft, and buyer orders.

Scopes:chat:read

Path parameters

  • conversationIdstringrequired

    format: uuid

Response200 · application/json

OK

  • contactIdstringrequirednullable

    format: uuid

  • assignedUserIdstringrequirednullable

    format: uuid

  • labelsarray<string>required
  • waitingSincestringrequirednullable

    Oldest unanswered buyer message; null when the shop spoke last.

    format: date-time

  • latebooleanrequired

    Waiting longer than the tenant's response target.

  • idstringrequired

    format: uuid

  • storeIdstringrequired

    format: uuid

  • storeNamestringrequired
  • marketplacestringrequired

    One of:tiktokshopeelazadatokopedia

  • externalConversationIdstringrequired
  • buyerNamestringrequirednullable
  • buyerAvatarstringrequirednullable
  • canSendbooleanrequired

    False when the marketplace does not allow the shop to message this buyer.

  • unreadCountintegerrequired
  • lastMessageAtstringrequirednullable

    format: date-time

  • lastMessagePreviewstringrequirednullable
  • lastMessageRolestringrequirednullable

    One of:buyershopagentsystemrobot

  • statusstringrequired

    One of:openresolved

  • needsHumanbooleanrequired
  • handoffReasonstringrequirednullable
  • agentPausedbooleanrequired
  • hasDraftbooleanrequired
  • notesarray<ChatNote>required
    Show 5 child attributes
    • idstringrequired

      format: uuid

    • userIdstringrequirednullable

      format: uuid

    • userNamestringrequirednullable
    • bodystringrequired
    • createdAtstringrequired

      format: date-time

  • messagesarray<ChatMessage>required

    Oldest first, at most the latest 200.

    Show 9 child attributes
    • idstringrequired

      format: uuid

    • rolestringrequired

      One of:buyershopagentsystemrobot

    • senderNamestringrequirednullable
    • typestringrequired

      Marketplace message type, e.g. TEXT, IMAGE, ORDER_CARD, PRODUCT_CARD.

    • textstringrequirednullable
    • contentobject (map)required

      Parsed marketplace content (url for images, order_id for order cards, ...).

    • sentByUserIdstringrequirednullable

      format: uuid

    • sentByAgentbooleanrequired
    • createdAtstringrequired

      format: date-time

  • draftReplystringrequirednullable
  • draftRunIdstringrequirednullable

    format: uuid

  • lastRunChatAgentRunrequirednullable
    Show 12 child attributes
    • idstringrequired

      format: uuid

    • conversationIdstringrequired

      format: uuid

    • modestringrequired

      One of:offsuggestauto

    • outcomestringrequired

      One of:repliedsuggestedhandoffskippederror

    • replystringrequirednullable
    • reasonstringrequirednullable
    • toolsarray<ChatAgentToolCall>required
      Show 3 child attributes
      • namestringrequired
      • inputobject (map)required
      • okbooleanrequired
    • modelstringrequirednullable
    • inputTokensintegerrequirednullable
    • outputTokensintegerrequirednullable
    • cacheReadTokensintegerrequirednullable
    • createdAtstringrequired

      format: date-time

  • buyerOrdersarray<ChatBuyerOrder>required
    Show 7 child attributes
    • orderIdstringrequired

      format: uuid

    • externalOrderIdstringrequired
    • statusstringrequired
    • marketplaceStatusstringrequirednullable
    • totalstring (decimal)required

      Decimal string with two fraction digits.

    • currencystringrequired
    • placedAtstringrequired

      format: date-time

Example request · curl
curl "https://api.comnethub.app/v1/chat/conversations/$CONVERSATION_ID" \
  -H "Authorization: Bearer $THECOMNET_API_KEY"

Update chat conversation

PATCH/v1/chat/conversations/{conversationId}

Resolve or reopen, clear the handoff flag, pause the agent.

Scopes:chat:write

Path parameters

  • conversationIdstringrequired

    format: uuid

Request bodyapplication/json

  • assignedUserIdstringoptionalnullable

    format: uuid

  • labelsarray<string>optional

    max items 20

  • statusstringoptional

    One of:openresolved

  • needsHumanbooleanoptional

    Clears the handoff flag.

    One of:false

  • agentPausedbooleanoptional

Response200 · application/json

OK

  • contactIdstringrequirednullable

    format: uuid

  • assignedUserIdstringrequirednullable

    format: uuid

  • labelsarray<string>required
  • waitingSincestringrequirednullable

    Oldest unanswered buyer message; null when the shop spoke last.

    format: date-time

  • latebooleanrequired

    Waiting longer than the tenant's response target.

  • idstringrequired

    format: uuid

  • storeIdstringrequired

    format: uuid

  • storeNamestringrequired
  • marketplacestringrequired

    One of:tiktokshopeelazadatokopedia

  • externalConversationIdstringrequired
  • buyerNamestringrequirednullable
  • buyerAvatarstringrequirednullable
  • canSendbooleanrequired

    False when the marketplace does not allow the shop to message this buyer.

  • unreadCountintegerrequired
  • lastMessageAtstringrequirednullable

    format: date-time

  • lastMessagePreviewstringrequirednullable
  • lastMessageRolestringrequirednullable

    One of:buyershopagentsystemrobot

  • statusstringrequired

    One of:openresolved

  • needsHumanbooleanrequired
  • handoffReasonstringrequirednullable
  • agentPausedbooleanrequired
  • hasDraftbooleanrequired
Example request · curl
curl -X PATCH "https://api.comnethub.app/v1/chat/conversations/$CONVERSATION_ID" \
  -H "Authorization: Bearer $THECOMNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "assignedUserId": "0192f0c4-8d1e-7a4b-9c3e-5f6a7b8c9d0e",
  "labels": [
    "string"
  ],
  "status": "open",
  "needsHuman": false,
  "agentPaused": true
}'

Send chat message

POST/v1/chat/conversations/{conversationId}/messages

Send a text reply through the marketplace.

Scopes:chat:write

Path parameters

  • conversationIdstringrequired

    format: uuid

Request bodyapplication/json

  • textstringrequired

    min length 1 · max length 2000

  • fromDraftbooleanoptional

    Clears the agent draft after sending.

Response201 · application/json

OK

  • idstringrequired

    format: uuid

  • rolestringrequired

    One of:buyershopagentsystemrobot

  • senderNamestringrequirednullable
  • typestringrequired

    Marketplace message type, e.g. TEXT, IMAGE, ORDER_CARD, PRODUCT_CARD.

  • textstringrequirednullable
  • contentobject (map)required

    Parsed marketplace content (url for images, order_id for order cards, ...).

  • sentByUserIdstringrequirednullable

    format: uuid

  • sentByAgentbooleanrequired
  • createdAtstringrequired

    format: date-time

Example request · curl
curl -X POST "https://api.comnethub.app/v1/chat/conversations/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $THECOMNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "string"
}'

Add chat note

POST/v1/chat/conversations/{conversationId}/notes

Add an internal note (never sent to the buyer).

Scopes:chat:write

Path parameters

  • conversationIdstringrequired

    format: uuid

Request bodyapplication/json

  • bodystringrequired

    min length 1 · max length 2000

Response201 · application/json

OK

  • idstringrequired

    format: uuid

  • userIdstringrequirednullable

    format: uuid

  • userNamestringrequirednullable
  • bodystringrequired
  • createdAtstringrequired

    format: date-time

Example request · curl
curl -X POST "https://api.comnethub.app/v1/chat/conversations/$CONVERSATION_ID/notes" \
  -H "Authorization: Bearer $THECOMNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "string"
}'

List chat labels

GET/v1/chat/labels

Labels in use on conversations.

Scopes:chat:read

Response200 · application/json

OK

  • itemsarray<string>required
Example request · curl
curl "https://api.comnethub.app/v1/chat/labels" \
  -H "Authorization: Bearer $THECOMNET_API_KEY"

Mark chat read

POST/v1/chat/conversations/{conversationId}/read

Mark buyer messages read at the marketplace.

Scopes:chat:write

Path parameters

  • conversationIdstringrequired

    format: uuid

Response204

OK

No response body.

Example request · curl
curl -X POST "https://api.comnethub.app/v1/chat/conversations/$CONVERSATION_ID/read" \
  -H "Authorization: Bearer $THECOMNET_API_KEY"

List chat quick replies

GET/v1/chat/quick-replies

Saved replies.

Scopes:chat:read

Response200 · application/json

OK

  • itemsarray<ChatQuickReply>required
    Show 3 child attributes
    • idstringrequired

      format: uuid

    • shortcutstringrequired
    • bodystringrequired
Example request · curl
curl "https://api.comnethub.app/v1/chat/quick-replies" \
  -H "Authorization: Bearer $THECOMNET_API_KEY"