The Conversation module serves as a dedicated input type in Zurvey.io. It is built specifically to process textual input in a conversational format, meaning that uploaded data must follow a predefined structure.
Data is accepted through a dedicated API endpoint designed for this purpose.
Proper structuring of input data ensures accurate analysis and aggregation; datasets that do not meet these structural requirements cannot be processed.
Key Concepts
The following terms are used throughout the knowledge base to describe elements of a conversation dataset:
- Message – A single text entry or utterance, uniquely attributed to one participant in the conversation.
- Role – Identifies the speaker of each message. Acceptable values are "customer" or "agent".
- Conversation – A complete discussion thread consisting of multiple messages, identified by a unique Conversation ID.
Input Data Format
Unlike other input types in Zurvey.io that analyze individual customer feedback items, the Conversation module focuses on dialogues between multiple participants.
Insights are generated on two levels:
- Conversation level – Aggregated analysis across the full interaction.
- Role level – Insights filtered by participant type (customer or agent).
To ensure accurate aggregation and analysis, the dataset must include the following fields:
|
Field |
Description |
Type / Accepted Values |
Mandatory |
|
Conversation ID |
Unique identifier of the conversation. |
ID |
Yes |
|
Role differentiator |
Defines whether the message was sent by a customer or agent. |
agent / customer / undefined |
Yes |
|
Message |
The textual content of the conversation. |
text |
Yes |
|
Timestamp |
Unix timestamp used to calculate conversation duration, generate time-series charts, and analyze conversation flow. |
Unix timestamp |
Yes |
|
Agent ID |
Unique identifier for the agent (email, phone number, or system ID). Used for reports and comparisons. |
ID |
Yes |
|
Agent type |
Distinguishes between human and chatbot agents. |
human / bot |
Yes |
|
Agent name |
Display name of the agent. Used for identification and dashboard searches. |
text |
No |
|
Customer ID |
Unique identifier for the customer (email, phone number, or system ID). Required for customer-level reporting. |
ID |
Yes |
|
Customer name |
Display name of the customer. Used for identification and dashboard searches. |
text |
No |
Limitations
- Only two roles are supported: customer and agent. Records without a valid role or with an undefined value will be stored but excluded from role-based aggregation.
- Each conversation should have at least one customer message and one agent message, conversations with no valid aggregatable message will not be saved.
- Conversations submitted without a Conversation ID or customer id will not be saved.
- Each message should have non-empty text, role, timestamp and agent id properties provided to be considered valid. Agent properties are defined on message-level in case of multi-agent conversations.