Newsletter
Discussions management
  • Home
  • Discussions management

Introduction

order.jpg

Last update :

Toolbox / Tips

The Discussion API enables Octopia sellers to manage communication threads between customers, the seller, and support teams. It is designed to support relationship management by allowing sellers to open, view, and respond to discussions regarding their orders or offers.

Discussions are structured around typologies and subtypologies, providing a classification system for the nature of each message. Sellers can exchange messages, add attachments, and track the state of each discussion to ensure timely handling of customer concerns.

Attribute

Description

isOpen

Boolean indicating if the discussion is currently open or closed.

typologyCode / subTypologyCode

Type and sub-type of the discussion (e.g., Order, broken-product).

graduation

Level of severity or escalation: Discussion, Claim, Level_1.

discussionId

Unique identifier for the discussion.

receiver

Target user of a message (e.g., Customer, GrcOperator).

hasRead

Boolean flag indicating if a message has been read.

Seller Workflow

discussion.png

In this section we will look at how to manage the following cases and ensure maximum control of CRM activities:

Count Discussions

Prerequisites

  • Optionally use filters like salesChannel, graduationCode, processStatus, or isOpen.

Enable sellers to estimate how many discussions match given criteria — without retrieving full discussion content.
Useful to:

  • Monitor overall workload (e.g. “How many open claims do I have across all channels?”),

  • Build dashboards with metrics (trends over time),

  • Trigger alerts or SLAs if number of untreated discussions exceeds threshold,

  • Optimize UIs by displaying counts instead of full lists when detail isn’t needed.

Functional Rules

  • Supports filtering by salesChannel, graduationCode, processStatus, and isOpen only.

  • Query limits: none specified, but count endpoint is lightweight (no message bodies, no attachments).

  • Performance constraint: should return quickly as it only aggregates metadata.

  • If filters are invalid (wrong date range, unsupported status values), returns 400.

  • Missing required headers (e.g. sellerId) returns 401 or 403.

Endpoint to use

Important notes

  • Combine with filters to segment metrics (e.g., by typology).

  • Returns only the discussionsCount field (integer).

List discussions using filters

Allow the seller to retrieve all discussions matching business filters such as order ID, typology, process status, and open/closed state.
Common use cases include:

  • Displaying the seller’s active discussions by typology or status,

  • Filtering for SLA tracking (e.g. “Which discussions remain open for more than X days?”),

  • Retrieving only recently updated discussions for performance reasons,

  • Identifying unresolved issues per channel or customer segment.

Functional Rules

  • Supports date filtering (updatedAtMin, updatedAtMax) and pagination (pageIndex, pageSize).

  • Sorting available via sort=asc|desc:updatedAt (default is descending).

  • Use includeMessages=FirstMessage|LastMessage to retrieve a message preview.

  • Accepts filtering by: discussionId, salesChannel, typologyCode, subTypologyCode, orderSellerId, processStatus, isOpen.

  • Maximum search period is 6 months.

Endpoint to use

Important notes

  • Always use updatedAtMin/Max to avoid large unbounded queries.

  • Use includeMessages to reduce API calls when showing previews.

  • Handle 400 errors from invalid date formats or missing salesChannel.

Sub-case Get discussion subtypologies

Prerequisites

  • Sales channel, order status, typologyCode must be provided.

Allow the seller to fetch the list of available subtypologies used to classify a discussion based on the order context and sales channel.
This enables:

  • Dynamically loading values in form dropdowns,

  • Preventing invalid subtypology values when creating a discussion,

  • Determining whether a given subtypology is open to sellers or customers.

Functional Rules

  • Requires combination of salesChannel, typologyCode, and orderStatus.

  • Optional filtering by userType (Seller, Customer).

  • Returned list includes typologyCode, subTypologyCode, activation state, and allowed user types.

  • Only enabled subtypologies (state: true) should be used.

Endpoint to use

Important notes

  • The response includes whether a subtypology is enabled (state: true/false).

  • Use this list to feed form dropdowns before calling POST /discussions.

  • Returns userType eligibility (Seller, Customer).

Get Discussion Details

Prerequisites

  • Must know the discussion ID to retrieve.

Allow the seller to retrieve complete information about a specific discussion including the subject, status, participants, and all messages exchanged.
Typical use cases include:

  • Accessing full context before replying,

  • Reviewing historical messages and metadata,

  • Checking available actions (e.g. auto-close),

  • Verifying if attachments or customer responses are present.

Functional Rules

  • Requires a valid discussionId.

  • Response includes the discussion metadata, messages (with metadata only for attachments), available actions, and eligible receivers.

  • Messages are returned in full (not paginated).

Endpoint to use

Important notes

  • Always validate existence first with search endpoint.

  • attachments returned are metadata only.

Get Attachments Metadata

Prerequisites

  • Must pass either discussionId, messageId, or attachmentId.

Retrieve metadata for files attached to a specific message or discussion.
Use cases include:

  • Listing attachments available for download in a seller dashboard,

  • Verifying if required documents were sent (e.g. invoice, image),

Functional Rules

  • You must specify at least one filter: discussionId, messageId, or attachmentId.

  • Returned metadata includes attachmentName, fileFormat, IDs, and linkage (to message/discussion).

  • Returns the file as base64 string in content node

  • If no filter is passed or query is ambiguous, API returns 400.

Endpoint to use

Important notes

  • Validate inputs: at least one of the three filters is required.

  • Use this endpoint before attempting to download via another service.

  • Attachments include filename, type, and IDs.

Create a Discussion

Prerequisites

Allow the seller to open a new dialog with customer (or Grc Operator) tied to a specific order or product issue.
Use cases include:

  • Reporting a damaged product,

  • Requesting order cancellation or investigating a delay,

  • Escalations or product warranty issues.

Functional Rules

  • Must supply valid subtypology (from the typologies endpoint) and valid order referencing the seller.

  • Character limits apply: subject between 5–50 chars, message body between 13–5000 chars.

  • Attachments rules: max 3 attachments per message; max size per message 4MB.

  • If sales channel does not support discussion initiation an error is returned.

Endpoint to use

Request Body Example:

{
  "subject": "Broken product",
  "orderId": "SALESC123456789",
  "salesChannel": "SALESC",
  "subtypologyCode": "broken-product",
  "productId": "pm5972a",
  "message": {
    "body": "product received is broken",
    "receiver": "Customer"
  }
}

Important notes

  • Avoid duplicates by checking existing discussions via GET /discussions.

  • Max 3 attachments per message (4 MB total).

  • Subject: 5–50 characters. Message body: 13–5000 characters.

Sub-case Get Sales Channel Configuration

Prerequisites

  • Must know sales channel ID.

  • Use before allowing sellers to open discussions.

Allow the seller to verify whether a sales channel allows initiating a discussion, and identify the available recipients.
Useful for:

  • Enabling or disabling “create discussion” options dynamically in the UI,

  • Displaying allowed user types (Customer, Grc Operator) per channel,

  • Preventing API calls to unsupported channels.

Functional Rules

  • Requires sellerId and salesChannelId.

  • Returns a config object including:

    • isEnabled: whether seller-initiated discussions are allowed,

    • allowedReceivers: list of eligible recipient user types.

  • Should be cached per session or sales channel to avoid repeated calls.

Endpoint to use

Important notes

  • If isEnabled: false, discussion creation cannot be made by the seller.

  • Use allowedReceivers to pre-fill messaging interface.

  • Can be cached for seller session duration.

Send a Message in a Discussion

Prerequisites

  • Discussion must already exist.

  • Must know the ID and target receiver(s).

Allow the seller to respond within an ongoing discussion with a new message and optional attachments.
Typical business needs include:

  • Answering a customer question or claim,

  • Sending a document (invoice, delivery proof),

  • Continuing a multi-step support conversation.

Functional Rules

  • Message must include body text (13–5000 characters) and valid receiver (type and ID).

  • Up to 3 attachments allowed per message, total size must not exceed 4MB.

  • salesChannel must match the discussion context.

  • API returns the messageId on success.

Endpoint to use

Request Body Example:

{
  "body": "Please find attached invoice.",
  "discussionId": "507f1f77bcf86cd799439011",
  "salesChannel": "CASIFR",
  "receivers": [
    {
      "userId": "123",
      "userType": "Customer"
    }
  ]
}

Important notes

  • Max 3 attachments per message (4 MB total).

  • Fields body, discussionId, receivers, salesChannel are mandatory.

  • 201 Created returns messageId.

Mark Message as Read

Prerequisites

  • Message must exist and messageId must be known.

Allow the seller to mark a specific message as read, confirming that it was seen and processed.
Helps to:

  • Track message read status in internal tools,

  • Drive notification logic or SLA compliance,

  • Clear unread indicators in UIs.

Functional Rules

  • Only the hasRead property can be updated.

  • Requires PATCH body with JSON operation format (opt, path, value).

  • Returns 204 No Content on success.

Endpoint to use

Request Body Example:

[
  {
    "opt": "replace",
    "path": "/hasRead",
    "value": "true"
  }
]

Important notes

  • Only the hasRead field can be modified.

  • Useful for UI read/unread indicators.

  • Returns 204 No Content on success.

Close a Discussion

Prerequisites

  • Must know the discussion ID.

  • Use only if business logic allows closing (based on typology/config).

Allow the seller to formally close an ongoing discussion when the issue has been resolved or no further action is needed.
Useful to:

  • Finalize customer support cases,

  • Prevent further messages from being exchanged,

  • Improve back-office clarity and reduce clutter.

Functional Rules

  • isOpen is updated to false via PATCH operation.

  • Endpoint only supports one operation: replace /isOpen value.

  • If already closed, request is rejected (400).

  • Returns 204 No Content on success.

Endpoint to use

Aucun endpoint trouvé avec l'operationId « patch-discussions-discussionId ».

Request Body Example:

[
  {
    "opt": "replace",
    "path": "/isOpen",
    "value": "false"
  }

Important notes

  • Do not close already closed discussions (avoid 400 errors).

  • A 204 is returned when successful.

FAQ

 What is a “discussion” in Octopia?

A discussion is a structured communication thread between the seller and the buyer (and optionally Grc Operator) related to an order or product issue. It is used for customer support purposes such as complaints, product issues, or general inquiries.

 When and why should I create a discussion?

When available (see sales channel configuration)

You should create a discussion when:

  • You want to proactively communicate about an issue (e.g., delay, substitution).

  • You need a written trace for post-order matters tied to a specific typology.

 What are typologies and subtypologies used for?

Typologies classify discussions by topic (e.g., Order issue, questions on a published offer), while subtypologies provide a more granular classification (e.g., broken-product, missing-accessory, any compatible product or shipping issue). These are used for routing, analytics, and business rules.

Use GET /typologies to retrieve the valid list based on the sales channel and order context.

 Can a seller initiate a discussion?

Yes — but only if the sales channel configuration allows it.

You must first call GET /sales-channel-configurations/{salesChannelId} to check whether seller-initiated discussions are enabled. If not, discussions must be initiated by the customer.

 Can multiple discussions be created for the same order/product?

No — only one discussion per (order, subtypology, product) is allowed.

If you try to create a duplicate, the API will return 409 Conflict with the Location of the existing discussion.

 What happens automatically when I create a discussion?

An initial message is automatically included in the thread at creation, based on the payload. This kickstarts the exchange.

 What does “isOpen” mean?

This boolean field indicates whether the discussion is still active. When set to false, the thread is closed.

Reopening conditions include customer message or volontary reopening by the seller.

Use PATCH /discussions/{id} to close/open a discussion.

 What are typical seller actions in the discussion lifecycle?

  1. Search for discussions (e.g. open claims)

  2. View the latest messages and details

  3. Respond or upload supporting documents

  4. Close the thread once resolved

 Can Octopia or a GRC operator intervene in discussions?

Yes — discussions can be escalated internally. When graduation=Claim or Level_1, an internal GRC team may step in and respond through the API.

 Are there any size or format restrictions for messages or attachments?

  • Message body: min 13, max 5000 characters

  • Subject: 5–50 characters

  • Attachments: max 3 per message, total size ≤ 4 MB, supported formats: PDF, JPG, PNG, etc.