Conversation

Core model representing chat conversations in WireChat

The Conversation model represents a chat conversation between participants. It supports private (1-on-1), self, and group conversation types.

Namespace

Wirechat\Wirechat\Models\Conversation

Properties

id · int

Unique identifier for the conversation

type · ConversationType

Type of conversation: PRIVATE (1-on-1), SELF, or GROUP

disappearing_started_at · Carbon|null

Timestamp when disappearing messages were enabled

disappearing_duration · int|null

Duration in seconds before messages disappear

created_at · Carbon|null

Conversation creation timestamp

updated_at · Carbon|null

Last update timestamp

Relationships

participants()

Get all participants in the conversation.

public function participants(): HasMany

return · HasMany

Relationship to Participant models

Example:

$participants = $conversation->participants;
foreach ($participants as $participant) {
    echo $participant->participantable->name;
}

participant()

Get a specific participant by user model.

public function participant(Model|Authenticatable $user, bool $withoutGlobalScopes = false): ?Participant

user · Model|Authenticatable · required

The user model to find the participant for

withoutGlobalScopes · bool · default: "false"

Whether to ignore global scopes in the query

return · Participant|null

The participant instance or null if not found

messages()

Get all messages in the conversation.

public function messages(): HasMany

return · HasMany

Relationship to Message models

lastMessage()

Get the most recent message in the conversation.

public function lastMessage(): HasOne

return · HasOne

Relationship to the latest Message

group()

Get the group configuration for this conversation.

public function group(): HasOne

return · HasOne

Relationship to Group model (only for GROUP type conversations)

Participant Management

addParticipant()

Add a new participant to the conversation.

public function addParticipant(
    Model $user, 
    ParticipantRole $role = ParticipantRole::PARTICIPANT, 
    bool $undoAdminRemovalAction = false
): Participant

user · Model · required

The user model to add as a participant

role · ParticipantRole · default: "ParticipantRole::PARTICIPANT"

The role to assign: OWNER, ADMIN, or PARTICIPANT

undoAdminRemovalAction · bool · default: "false"

If true, allows re-adding a user who was removed by an admin

return · Participant

The created or existing Participant instance

Example:

$participant = $conversation->addParticipant(
    $user, 
    ParticipantRole::ADMIN
);

peerParticipant()

Get the other participant in a private or self conversation.

public function peerParticipant(Model|Authenticatable $reference): ?Participant

reference · Model|Authenticatable · required

The reference user to exclude

return · Participant|null

The peer participant, or the same user for self conversations, or null

peerParticipants()

Get all participants except the reference user.

public function peerParticipants(Model $reference): Collection

reference · Model · required

The user to exclude from the results

return · Collection<Participant>

Collection of peer participants

Message Status

markAsRead()

Mark the conversation as read for a user.

public function markAsRead(?Model $user = null): void

user · Model|null · default: "null"

The user marking as read. Defaults to authenticated user.

Example:

$conversation->markAsRead(auth()->user());

readBy()

Check if the conversation has been fully read by a user.

public function readBy(Model|Participant $user): bool

user · Model|Participant · required

The user or participant to check

return · bool

True if fully read, false otherwise

unreadMessages()

Get unread messages for a specific user.

public function unreadMessages(Model|Authenticatable $user): Collection

user · Model|Authenticatable · required

The user to get unread messages for

return · Collection<Message>

Collection of unread messages

getUnreadCountFor()

Get the count of unread messages for a user.

public function getUnreadCountFor(Model $model): int

model · Model · required

The user model

return · int

Number of unread messages

Disappearing Messages

hasDisappearingTurnedOn()

Check if disappearing messages are enabled.

public function hasDisappearingTurnedOn(): bool

return · bool

True if disappearing messages are enabled

turnOnDisappearing()

Enable disappearing messages.

public function turnOnDisappearing(int $durationInSeconds): void

durationInSeconds · int · required

Duration before messages disappear (minimum 3600 seconds / 1 hour)

Example:

// Enable disappearing messages for 24 hours
$conversation->turnOnDisappearing(86400);

turnOffDisappearing()

Disable disappearing messages.

public function turnOffDisappearing(): void

Conversation Management

deleteFor()

Delete the conversation for a specific user.

public function deleteFor(Model|Authenticatable $user): ?bool

user · Model|Authenticatable · required

The user deleting the conversation

return · bool|null

True if force deleted, null otherwise

hasBeenDeletedBy()

Check if a user has deleted the conversation.

public function hasBeenDeletedBy(Model|Authenticatable $user): bool

user · Model|Authenticatable · required

The user to check

return · bool

True if the user has deleted the conversation

clearFor()

Clear all messages in the conversation for a user.

public function clearFor(Model|Authenticatable $user): void

user · Model|Authenticatable · required

The user clearing the conversation

Type Checking

isPrivate()

Check if the conversation is a private (1-on-1) conversation.

public function isPrivate(): bool

return · bool

True if private conversation

isSelf()

Check if the conversation is a self conversation.

public function isSelf(): bool

return · bool

True if self conversation

isSelfConversation()

Alias for isSelf().

public function isSelfConversation(): bool

isGroup()

Check if the conversation is a group conversation.

public function isGroup(): bool

return · bool

True if group conversation

Role Checking

isOwner()

Check if a user is the owner of the conversation.

public function isOwner(Model|Authenticatable $model): bool

model · Model|Authenticatable · required

The user to check

return · bool

True if the user is the owner

isAdmin()

Check if a user is an admin of the conversation.

public function isAdmin(Model|Authenticatable $model): bool

model · Model|Authenticatable · required

The user to check

return · bool

True if the user is an admin or owner

Query Scopes

whereHasParticipant()

Scope to filter conversations by participant.

public function scopeWhereHasParticipant(Builder $query, $userId, $userType): void

withoutBlanks()

Exclude conversations with no messages.

public function scopeWithoutBlanks(Builder $builder): void

withoutCleared()

Exclude conversations the user has cleared.

public function scopeWithoutCleared(Builder $builder): void

withoutDeleted()

Exclude conversations the user has deleted.

public function scopeWithoutDeleted(Builder $builder): void

withDeleted()

Include conversations the user has deleted.

public function scopeWithDeleted(Builder $builder): void

Example Usage

use Wirechat\Wirechat\Models\Conversation;
use Wirechat\Wirechat\Enums\ParticipantRole;

// Get a conversation with unread count
$conversation = Conversation::find(1);
$unreadCount = $conversation->getUnreadCountFor(auth()->user());

// Add a participant
$conversation->addParticipant($newUser, ParticipantRole::PARTICIPANT);

// Mark as read
$conversation->markAsRead();

// Enable disappearing messages for 7 days
$conversation->turnOnDisappearing(604800);

// Get peer participant in private chat
$peer = $conversation->peerParticipant(auth()->user());
echo $peer->participantable->name;

// Check conversation type
if ($conversation->isGroup()) {
    $group = $conversation->group;
    echo $group->name;
}