Read the conversation graph across the contact center — conversations and their workitems, conversation history by participant, campaign and ticket scoped conversations, unread counts, conversation activity summaries, and the transcriptions and call recordings attached to a workitem.
openapi: 3.0.0
info:
title: Conversation API
version: 1.0.0
description: API for managing and retrieving conversation data.
servers:
- url: https://api.nextiva.com
description: Nextiva API Base URL
tags:
- name: Conversations
description: Operations related to conversations
paths:
/data/api/types/conversation:
get:
summary: Fetch all conversations
operationId: fetchConversations
tags:
- Conversations
description: 'Fetch conversations. This endpoint retrieves a paginated list of all conversations, allowing filtering
by rows and start index.
'
parameters:
- in: query
name: rows
schema:
type: integer
format: int32
default: 100
description: Number of items per page.
- in: query
name: start
schema:
type: integer
format: int32
default: 0
description: Pagination starting index.
responses:
'200':
description: A paginated list of conversations.
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsResponse'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/analytics/api/conversations/{conversationId}/workitems:
get:
summary: Fetch a conversation by ID, including its associated workitems
operationId: fetchConversationById
tags:
- Conversations
description: 'Fetches a conversation by its ID, including its associated workitems. This endpoint allows for filtering
by various parameters and different API versions.
'
parameters:
- in: path
name: conversationId
schema:
type: string
required: true
description: Unique identifier of the conversation.
- in: query
name: cursor
schema:
type: integer
format: int32
description: Cursor for pagination (for v2).
- in: query
name: includeCallRecordings
schema:
type: boolean
description: Whether to include call recordings.
- in: query
name: includeConversation
schema:
type: boolean
description: Whether to include conversation details.
- in: query
name: includeParentEngagement
schema:
type: boolean
description: Whether to include parent engagement details.
- in: query
name: includeSummary
schema:
type: boolean
description: Whether to include a summary.
- in: query
name: includeVoicemail
schema:
type: boolean
description: Whether to include voicemail.
- in: query
name: limit
schema:
type: integer
format: int32
default: 100
description: Number of items per page (for v2).
- in: query
name: mentioned
schema:
type: boolean
description: Filter messages that mention the logged user.
- in: query
name: rows
schema:
type: integer
format: int32
default: 100
description: Number of items per page (for v1).
- in: query
name: start
schema:
type: integer
format: int32
default: 0
description: Pagination starting index (for v1).
- in: query
name: version
schema:
type: string
enum:
- v1
- v2
default: v1
description: API version to use.
- in: query
name: workitemId
schema:
type: string
description: Filter by workitem ID.
responses:
'200':
description: A conversation object by ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationByIdResponse'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/analytics/api/conversations/{conversationId}/workitems/{workItemStatus}:
get:
summary: Fetch workitems within a conversation by their status
operationId: fetchConversationWorkItemsByStatus
tags:
- Conversations
description: 'Fetches a conversation''s messages with workItems only in a given status. This allows filtering workitems
within a specific conversation based on their status.
'
parameters:
- in: path
name: conversationId
schema:
type: string
required: true
description: Unique identifier of the conversation.
- in: path
name: workItemStatus
schema:
type: string
required: true
description: Status of the workitems to filter by (e.g., 'draft').
- in: query
name: rows
schema:
type: integer
format: int32
default: 100
description: Number of items per page.
- in: query
name: start
schema:
type: integer
format: int32
default: 0
description: Pagination starting index.
responses:
'200':
description: A paginated list of workitems filtered by status within a conversation.
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsResponse'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/analytics/api/campaigns/{campaignId}/recentconversationworkitems:
get:
summary: Fetch recent conversation workitems for a campaign
operationId: fetchConversationByCampaignId
tags:
- Campaigns
- Conversations
description: 'Fetches conversations associated with a specific campaign ID. This endpoint allows filtering conversations
by various criteria such as archived status, call types, and mentions.
'
parameters:
- in: path
name: campaignId
schema:
type: string
required: true
description: Unique identifier of the campaign.
- in: query
name: archived
schema:
type: boolean
description: Filter archived conversations.
- in: query
name: calls
schema:
type: boolean
description: Filter calls.
- in: query
name: conversationType
schema:
type: string
enum:
- contact_based
- shared_inbox_internal
- internal_chat
- channel
description: Filter by conversation type.
- in: query
name: draft
schema:
type: boolean
description: Filter draft conversations.
- in: query
name: inboundCalls
schema:
type: boolean
description: Filter inbound calls.
- in: query
name: latest
schema:
type: boolean
description: Filter latest conversations.
- in: query
name: limit
schema:
type: integer
format: int32
default: 100
description: Number of items to return.
- in: query
name: mentioned
schema:
type: boolean
description: Filter messages that have mentions.
- in: query
name: messages
schema:
type: boolean
description: Filter messages.
- in: query
name: missedCalls
schema:
type: boolean
description: Filter missed calls.
- in: query
name: offset
schema:
type: integer
format: int32
default: 0
description: Offset for pagination.
- in: query
name: outboundCalls
schema:
type: boolean
description: Filter outbound calls.
- in: query
name: read
schema:
type: boolean
description: Filter read messages.
- in: query
name: scope
schema:
type: string
enum:
- INTERNAL
- EXTERNAL
description: Filter by scope.
- in: query
name: totalUnread
schema:
type: boolean
description: Include unread count for each conversation.
- in: query
name: voicemails
schema:
type: boolean
description: Filter voicemails.
- in: query
name: workitem
schema:
type: string
description: Filter by workitem ID.
responses:
'200':
description: A paginated list of conversations related to a campaign.
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsResponse'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/analytics/api/recentConversationWorkitems:
get:
summary: Fetch recent conversation workitem engagements
operationId: fetchRecentConversationWorkitemEngagements
tags:
- Conversations
description: 'Fetches recent conversation workitem engagements based on provided parameters like cursor, filter type,
and limit. This helps in paginating and filtering recent conversation activity.
'
parameters:
- in: query
name: cursor
schema:
type: integer
format: int32
description: Cursor for pagination.
- in: query
name: filter
schema:
$ref: '#/components/schemas/ConversationFilterTabType'
description: Filter type for conversations.
- in: query
name: ignoreVoicemailTranscripts
schema:
type: boolean
description: Whether to ignore voicemail transcripts.
- in: query
name: limit
schema:
type: integer
format: int32
description: Number of items per page.
- in: query
name: tab
schema:
$ref: '#/components/schemas/ConversationFilterTabType'
description: Tab filter for conversations.
responses:
'200':
description: A paginated list of recent conversation workitem engagements.
content:
application/json:
schema:
$ref: '#/components/schemas/RecentConversationWorkitemEngagementsResponse'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/analytics/api/conversations/workitems:
get:
summary: Fetch conversation history by participant ID
operationId: fetchConversationHistoryByParticipantId
tags:
- Conversations
description: 'Fetches conversation messages between the logged user and the participants specified in the `participantIds`
array. This endpoint provides paginated history for specific participants.
'
parameters:
- in: query
name: pageNumber
schema:
type: integer
format: int32
default: 1
description: Page number for pagination.
- in: query
name: pageSize
schema:
type: integer
format: int32
default: 100
description: Number of items per page.
- in: query
name: participantIds
schema:
type: array
items:
type: string
description: IDs of the participants to filter by.
style: form
explode: true
responses:
'200':
description: A paginated list of conversation workitems for the specified participants.
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsResponseWithContactArray'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/analytics/api/tickets/{ticketId}/conversations:
get:
summary: Fetch conversations associated with a ticket
operationId: fetchTicketConversations
tags:
- Conversations
- Tickets
description: 'Fetches all conversations associated with a specific ticket ID. This provides a paginated list of conversations
relevant to a particular support ticket.
'
parameters:
- in: path
name: ticketId
schema:
type: string
required: true
description: Unique identifier of the ticket.
responses:
'200':
description: A paginated list of conversations related to a specific ticket.
content:
application/json:
schema:
$ref: '#/components/schemas/TicketConversationsResponse'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/data/api/types/conversation/unread/counts:
get:
summary: Fetch unread conversation counts
operationId: fetchUnreadCounts
tags:
- Conversations
description: 'Fetches unread counts for various types of conversations. This endpoint provides a summary of internal,
mentions, total, voice calls, and voicemails unread counts.
'
responses:
'200':
description: Unread counts for conversations.
content:
application/json:
schema:
$ref: '#/components/schemas/UnreadCounts'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/analytics/api/types/conversation/{conversationId}/workitems/{workitemId}/transcriptions-and-recordings:
get:
summary: Fetch transcriptions and recordings for a specific workitem within a conversation
operationId: fetchTranscriptionsAndRecordings
tags:
- Conversations
- Workitems
description: 'Fetches transcriptions and recordings associated with a specific workitem within a conversation. This
endpoint provides detailed media data for a workitem, useful for call analysis and quality assurance.
'
parameters:
- in: path
name: conversationId
schema:
type: string
required: true
description: Unique identifier of the conversation.
- in: path
name: workitemId
schema:
type: string
required: true
description: Unique identifier of the workitem.
- in: query
name: createdAt
schema:
type: integer
format: int64
description: Creation timestamp of the workitem.
responses:
'200':
description: Transcriptions and recordings data.
content:
application/json:
schema:
$ref: '#/components/schemas/TranscriptionsAndRecordingsResponse'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/analytics/api/conversationActivitySummary:
get:
summary: Fetch a summary of conversation activity (DEPRECATED)
operationId: fetchConversationActivitySummary
tags:
- Conversations
description: 'Fetches a summary of conversation activity, including categorized conversations and unread counts. This
endpoint is **DEPRECATED** and should be replaced by accessing the new v2 API via `sdk.getSchemaTypeClient()`.
'
responses:
'200':
description: A summary of conversation activity.
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationActivitySummaryResponse'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Conversation:
type: object
properties:
_id:
type: string
description: Internal unique identifier (MongoDB ID).
conversationId:
type: string
description: Public unique identifier for the conversation.
conversationType:
type: string
description: The type of conversation (e.g., 'contact_based', 'shared_inbox_internal').
createdAt:
type: integer
format: int64
description: Unix timestamp (ms) when the conversation was created.
createdBy:
type: string
description: Identifier of the entity that created the conversation.
deletedAt:
type: integer
format: int64
description: Unix timestamp (ms) if the conversation was soft-deleted.
description:
type: string
description: An optional description for the conversation.
id:
type: string
description: Alias for conversationId.
modifiedAt:
type: integer
format: int64
description: Unix timestamp (ms) when the conversation was last modified.
modifiedBy:
type: string
description: Identifier of the entity that last modified the conversation.
name:
type: string
description: A human-readable name or subject for the conversation.
objectType:
type: string
description: The type of object, will always be 'conversation'.
parentEngagementId:
type: string
description: The ID of the parent engagement.
parentTicketId:
type: string
description: The ID of the parent ticket.
parentWorkitemId:
type: string
description: The ID of the parent workitem associated with this conversation.
participants:
type: array
items:
$ref: '#/components/schemas/Participant'
description: An array of participants involved in the conversation.
phoneNumber:
type: string
description: The primary phone number associated with the conversation.
sharedInboxId:
type: string
description: The ID of the shared inbox, if applicable.
sharedInboxName:
type: string
description: The name of the shared inbox.
tenantId:
type: string
description: The ID of the tenant the conversation belongs to.
topicName:
type: string
description: The name of the topic, if applicable.
totalCount:
type: integer
format: int32
description: Total number of messages/events in the conversation.
unreadCount:
type: integer
format: int32
description: Number of unread messages/events.
Participant:
type: object
properties:
addedBy:
type: string
archivedAt:
type: integer
format: int64
contact:
$ref: '#/components/schemas/ContactPartial'
firstName:
type: string
id:
type: string
joinedAt:
type: integer
format: int64
lastName:
type: string
notifyByEmail:
type: boolean
notifyBySMS:
type: boolean
notifyByVoice:
type: boolean
notifyByWeb:
type: boolean
phoneNumber:
type: string
type:
type: string
user:
$ref: '#/components/schemas/UserParticipantDetails'
ContactPartial:
type: object
properties:
id:
type: string
email:
type: string
UserParticipantDetails:
type: object
properties:
_id:
type: string
addresses:
type: array
items:
type: string
firstName:
type: string
lastName:
type: string
personalInboxCampaignId:
type: string
phoneNumber:
type: string
username:
type: string
PaginatedResponse:
type: object
properties:
count:
type: integer
format: int32
description: Number of objects in the current page.
total:
type: integer
format: int32
description: Total number of objects matching the criteria.
objects:
type: array
items:
type: object
description: Array of objects.
ConversationsResponse:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/Workitem'
ConversationByIdResponse:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/Workitem'
engagementData:
type: array
items:
$ref: '#/components/schemas/EngagementData'
ConversationsResponseWithContactArray:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- type: object
properties:
objects:
type: array
items:
oneOf:
- $ref: '#/components/schemas/Workitem'
- $ref: '#/components/schemas/ContactArray'
ContactArray:
type: object
properties:
contacts:
type: array
items:
$ref: '#/components/schemas/Contact'
TicketConversationsResponse:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/Conversation'
RecentConversationWorkitemEngagementsResponse:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/EngagementData'
TranscriptionsAndRecordingsResponse:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- type: object
properties:
objects:
type: array
items:
type: object
properties:
callRecordingData:
type: array
items:
$ref: '#/components/schemas/ConversationCallRecordingData'
summary:
type: string
transcriptionMessages:
type: array
items:
$ref: '#/components/schemas/Message'
voicemailTranscript:
type: string
workitemId:
type: string
ConversationActivitySummary:
type: object
properties:
categories:
type: object
properties:
latestActivity:
type: array
items:
$ref: '#/components/schemas/Conversation'
unreadMessages:
type: array
items:
$ref: '#/components/schemas/Conversation'
unreadMissedCalls:
type: array
items:
$ref: '#/components/schemas/Conversation'
unreadVoicemails:
type: array
items:
$ref: '#/components/schemas/Conversation'
description: Categorized conversations by activity type.
totalUnreadCount:
type: integer
format: int32
description: Total number of unread items.
totalUnreadCountByFilter:
type: object
properties:
totalUnreadMessagesCount:
type: integer
format: int32
totalUnreadMissedCallsCount:
type: integer
format: int32
totalUnreadVoiceMailsCount:
type: integer
format: int32
description: Detailed unread counts by filter.
ConversationActivitySummaryResponse:
type: array
items:
$ref: '#/components/schemas/ConversationActivitySummary'
UnreadCounts:
type: object
properties:
internal:
type: integer
format: int32
mentions:
type: integer
format: int32
total:
type: integer
format: int32
voicecalls:
type: integer
format: int32
voicemails:
type: integer
format: int32
ConversationFilterTabType:
type: string
enum:
- ALL
- ARCHIVED
- CALLS
- CALLS_AND_TEXTS
- CHANNELS
- DRAFTS
- EXTERNAL
- INCOMING_CALLS
- INTERNAL
- MENTIONS
- MISSED_CALLS
- OUTGOING_CALLS
- TEXTS
- UNREAD
- VOICEMAILS
Workitem:
type: object
properties:
workitemId:
type: string
description: Unique identifier for the workitem.
Contact:
type: object
properties:
id:
type: string
description: Unique identifier for the contact.
EngagementData:
type: object
properties:
id:
type: string
description: Unique identifier for the engagement data.
Message:
type: object
properties:
messageId:
type: string
description: Unique identifier for the message.
ConversationCallRecordingData:
type: object
properties:
id:
type: string
url:
type: string
Error:
type: object
properties:
code:
type: string
message:
type: string
security:
- bearerAuth: []