Conversations

Manage conversations and their labels.

ConversationsResource

ConversationsResource(http)

Bases: BaseResource

Synchronous conversations resource.

Initialize conversations resource with nested labels resource.

list

list(
    account_id: int,
    status: str = "open",
    assignee_type: str = "all",
    page: int = 1,
    inbox_id: int | None = None,
    team_id: int | None = None,
    labels: list[str] | None = None,
    q: str | None = None,
) -> list[Conversation]

List conversations with filters.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
status	str	Conversation status ('open', 'resolved', 'pending', 'snoozed')	'open'
assignee_type	str	Filter by assignee ('all', 'me', 'unassigned')	'all'
page	int	Page number for pagination	1
inbox_id	int | None	Filter by inbox ID (optional)	None
team_id	int | None	Filter by team ID (optional)	None
labels	list[str] | None	Filter by labels (optional)	None
q	str | None	Search query (optional)	None

Returns:

Type	Description
list[Conversation]	List of Conversation objects

Examples:

>>> conversations = client.conversations.list(
... account_id=1,
... status="open",
... assignee_type="me",
... page=1
... )

get

get(account_id: int, conversation_id: int) -> Conversation

Get conversation details.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
conversation_id	int	The conversation ID	required

Returns:

Type	Description
Conversation	Conversation object

Examples:

>>> conversation = client.conversations.get(account_id=1, conversation_id=42)

create

create(
    account_id: int,
    source_id: str,
    inbox_id: int,
    contact_id: int | None = None,
    **kwargs: Any,
) -> Conversation

Create a new conversation.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
source_id	str	Unique identifier for the conversation source	required
inbox_id	int	The inbox ID	required
contact_id	int | None	The contact ID (optional)	None
**kwargs	Any	Additional conversation attributes	{}

Returns:

Type	Description
Conversation	Created Conversation object

Examples:

>>> conversation = client.conversations.create(
... account_id=1,
... source_id="user-123",
... inbox_id=5,
... contact_id=100
... )

update

update(
    account_id: int,
    conversation_id: int,
    status: str | None = None,
    assignee_id: int | None = None,
    team_id: int | None = None,
    **kwargs: Any,
) -> Conversation

Update conversation.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
conversation_id	int	The conversation ID	required
status	str | None	New status (optional)	None
assignee_id	int | None	New assignee ID (optional)	None
team_id	int | None	New team ID (optional)	None
**kwargs	Any	Additional conversation attributes to update	{}

Returns:

Type	Description
Conversation	Updated Conversation object

Examples:

>>> conversation = client.conversations.update(
... account_id=1,
... conversation_id=42,
... status="resolved",
... assignee_id=10
... )

assign

assign(
    account_id: int, conversation_id: int, assignee_id: int
) -> Conversation

Assign conversation to an agent.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
conversation_id	int	The conversation ID	required
assignee_id	int	Agent ID to assign to	required

Returns:

Type	Description
Conversation	Updated Conversation object

Examples:

>>> conversation = client.conversations.assign(
... account_id=1,
... conversation_id=42,
... assignee_id=10
... )

toggle_status

toggle_status(
    account_id: int, conversation_id: int, status: str
) -> ConversationToggleStatusResponse

Toggle conversation status.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
conversation_id	int	The conversation ID	required
status	str	New status ('open', 'resolved', 'pending', 'snoozed')	required

Returns:

Type	Description
ConversationToggleStatusResponse	ConversationToggleStatusResponse

Examples:

>>> result = client.conversations.toggle_status(
... account_id=1,
... conversation_id=42,
... status="resolved"
... )
... print(result.current_status)

get_counts

get_counts(
    account_id: int, status: str = "open", **filters: Any
) -> dict

Get conversation counts.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
status	str	Status to count ('open', 'resolved', etc.)	'open'
**filters	Any	Additional filters (inbox_id, team_id, labels, etc.)	{}

Returns:

Type	Description
dict	Dictionary with conversation counts

Examples:

>>> counts = client.conversations.get_counts(account_id=1, status="open")
... print(counts)

---

ConversationLabelsResource

ConversationLabelsResource(http: HTTPClient)

Bases: BaseResource

Nested resource for managing conversation labels.

list

list(account_id: int, conversation_id: int) -> list[str]

List conversation labels.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
conversation_id	int	The conversation ID	required

Returns:

Type	Description
list[str]	List of label strings

Examples:

>>> labels = client.conversations.labels.list(
... account_id=1,
... conversation_id=42
... )

add

add(
    account_id: int, conversation_id: int, labels: list[str]
) -> list[str]

Add/replace labels on conversation.

IMPORTANT: This overwrites existing labels, does not append.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
conversation_id	int	The conversation ID	required
labels	list[str]	List of label strings to set	required

Returns:

Type	Description
list[str]	Updated list of labels

Examples:

>>> labels = client.conversations.labels.add(
... account_id=1,
... conversation_id=42,
... labels=["urgent", "billing"]
... )

---

AsyncConversationsResource

AsyncConversationsResource(http)

Bases: AsyncBaseResource

Asynchronous conversations resource.

Initialize async conversations resource with nested labels resource.

list async

list(
    account_id: int,
    status: str = "open",
    assignee_type: str = "all",
    page: int = 1,
    inbox_id: int | None = None,
    team_id: int | None = None,
    labels: list[str] | None = None,
    q: str | None = None,
) -> list[Conversation]

List conversations with filters (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
status	str	Conversation status	'open'
assignee_type	str	Filter by assignee	'all'
page	int	Page number	1
inbox_id	int | None	Filter by inbox ID	None
team_id	int | None	Filter by team ID	None
labels	list[str] | None	Filter by labels	None
q	str | None	Search query	None

Returns:

Type	Description
list[Conversation]	List of Conversation objects

get async

get(account_id: int, conversation_id: int) -> Conversation

Get conversation details (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
conversation_id	int	The conversation ID	required

Returns:

Type	Description
Conversation	Conversation object

create async

create(
    account_id: int,
    source_id: str,
    inbox_id: int,
    contact_id: int | None = None,
    **kwargs: Any,
) -> Conversation

Create a new conversation (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
source_id	str	Unique identifier for the conversation source	required
inbox_id	int	The inbox ID	required
contact_id	int | None	The contact ID	None
**kwargs	Any	Additional conversation attributes	{}

Returns:

Type	Description
Conversation	Created Conversation object

update async

update(
    account_id: int,
    conversation_id: int,
    status: str | None = None,
    assignee_id: int | None = None,
    team_id: int | None = None,
    **kwargs: Any,
) -> Conversation

Update conversation (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
conversation_id	int	The conversation ID	required
status	str | None	New status	None
assignee_id	int | None	New assignee ID	None
team_id	int | None	New team ID	None
**kwargs	Any	Additional conversation attributes	{}

Returns:

Type	Description
Conversation	Updated Conversation object

assign async

assign(
    account_id: int, conversation_id: int, assignee_id: int
) -> Conversation

Assign conversation to an agent (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
conversation_id	int	The conversation ID	required
assignee_id	int	Agent ID to assign to	required

Returns:

Type	Description
Conversation	Updated Conversation object

toggle_status async

toggle_status(
    account_id: int, conversation_id: int, status: str
) -> ConversationToggleStatusResponse

Toggle conversation status (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
conversation_id	int	The conversation ID	required
status	str	New status	required

Returns:

Type	Description
ConversationToggleStatusResponse	ConversationToggleStatusResponse

get_counts async

get_counts(
    account_id: int, status: str = "open", **filters: Any
) -> dict

Get conversation counts (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
status	str	Status to count	'open'
**filters	Any	Additional filters	{}

Returns:

Type	Description
dict	Dictionary with conversation counts

---

AsyncConversationLabelsResource

AsyncConversationLabelsResource(http: AsyncHTTPClient)

Bases: AsyncBaseResource

Async nested resource for managing conversation labels.

list async

list(account_id: int, conversation_id: int) -> list[str]

List conversation labels (async).

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
conversation_id	int	The conversation ID	required

Returns:

Type	Description
list[str]	List of label strings

add async

add(
    account_id: int, conversation_id: int, labels: list[str]
) -> list[str]

Add/replace labels on conversation (async).

IMPORTANT: This overwrites existing labels, does not append.

Parameters:

Name	Type	Description	Default
account_id	int	The account ID	required
conversation_id	int	The conversation ID	required
labels	list[str]	List of label strings to set	required

Returns:

Type	Description
list[str]	Updated list of labels