> For the complete documentation index, see [llms.txt](https://jumpathy.gitbook.io/betterchat-v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://jumpathy.gitbook.io/betterchat-v3/server/speaker.md).

# Speaker

A speaker is a representation of an entity that can speak in a channel. Each player that joins will automatically be assigned a speaker object that manages their chat.

[The server API ](/betterchat-v3/server/getting-started.md)allows you to access speakers and manage them from there.

```lua
-- Let's start by getting the speaker module!

local speakerModule = api.speaker
print(speakerModule) --> {...} <speakerModule>
```

### Events

**--> .speakerAdded**

The 'speakerAdded' event will fire with a speaker object whenever a speaker is created, if you want to get all player objects through this method it's recommended that you connect to this as the first signal.

```lua
speakerModule.speakerAdded:Connect(function(speaker)
    print(speaker) --> {...} <speaker>
    print(speaker.name) --> <speaker's name>
end)
```

**--> .speakerRemoved**

The 'speakerRemoved' event will fire with the name of the speaker that's just been removed.

```lua
speakerModule.speakerRemoved:Connect(function(speakerName)
    print("rip",speakerName)
end)
```

### Methods

**--> :getSpeakers(\<void>)**

Returns: \<table:speakers>

This method will return an array containing all currently existing speaker objects.

```lua
for _,speaker in pairs(speakerModule:getSpeakers()) do
    print(speaker.name)
end
```

**--> :getById(\<integer/string:id>)**

Returns: \<nil> / \<table:speaker)

Speakers are assigned an identifier and you can get them by that if you don't have their name.

```lua
speakerModule:getById(1234) --> {...} <speaker>
```

**--> :getByName(\<string:name>)**

Returns: \<nil> / \<table:speaker>

Speakers can be also fetched by their assigned name if you don't have their ID.

```lua
speakerModule:getByName("Roblox") --> {...} <speaker>
```

**--> .new(\<string:name>)**

Returns: \<boolean:success>,\<table:speaker>

Creating a speaker is a pretty straightforward process, all you need to do is pass the speaker's name and it'll magically create a speaker for you!

```lua
local success,speaker = speakerModule.new("Roblox")
```

### Speakers

Now, onto the actual objects themselves! They're full of all sorts of functions, properties, and events!

#### Properties

**--> .name \<string>**

The name is, as it says the 'name' of the speaker object.

```lua
speaker.name --> <string>
```

**--> .isPlayer \<boolean>**

This property determines if the speaker is a player or not.

```lua
speaker.isPlayer --> <true/false>
```

**--> .muted \<boolean>**

This property tells you if the speaker is muted, you should use the :mute(),:unmute(), or :updateMuteStatus() methods to change this as they connect events to it to update the status afterwards.

```lua
speaker.muted --> <true/false>
```

**--> .id \<integer/string>**

This property determines what the speaker is identified by, similar to their name property.

```lua
speaker.id
```

**--> .events \<table:events>**

This table contains a few events for the speaker, and when the speaker is destroyed all connections are removed automatically.

> **events.chatted \<string:message,\<table:messageObject>>**
>
> This event is fired with an *unfiltered* string whenever the speaker says anything.
>
> ```lua
> speaker.events.chatted:Connect(function(message,messageObject)
>     print(message) --> <string>
>     print(messageObject.data) --> {...}
> end)
> ```

> **events.channelUpdated \<void>**
>
> This event is fired whenever the speaker's channels are updated.
>
> ```lua
> speaker.events.channelUpdated:Connect(function()
>     --> do your magic here~
> end)
> ```

> **events.muteUpdate \<boolean:isMuted>**
>
> This event is fired whenever the speaker's mute status is updated.
>
> ```lua
> speaker.events.muteUpdate:Connect(function(isMuted)
>     print(isMuted) --> (same as speaker.muted)
> end)
> ```

#### Methods

**--> :mute(\<void>)**

This method will mute the specified speaker, for players it'll disable their chatbar's function and set an attribute named 'Muted'.

![](/files/V3Dnq35OHBfxxmJ874md)

```lua
speaker:mute()
```

**--> :unmute(\<void>)**

This method will unmute the specified speaker, the inverse of the previous function.

```lua
speaker:unmute()
```

**--> :updateMuteStatus(\<boolean:isMuted>)**

Like the previous two methods, it mutes/unmutes the user but for this one you can just pass a boolean to mute/unmute.

```lua
speaker:updateMuteStatus(true) --> muted now >:)
speaker:updateMuteStatus(false) --> nvm
```

**--> :addToChannel(\<string:channelName>)**

Add a speaker to a specified channel with this method.

```lua
speaker:addToChannel("System")
```

**--> :removeFromChannel(\<string:channelName>)**

Remove a speaker from the specified channel with this method.

```lua
speaker:removeFromChannel("System")
```

**--> :setIcon(\<string:imageUrl>)**

{% hint style="warning" %}
This method currently only works on non-player speakers.
{% endhint %}

If your chat uses icons, initially custom speakers will not have an icon and you can set one using this method.

```lua
speaker:setIcon("rbxthumb://type=AvatarHeadShot&id=1&w=420&h=420") --> Set speaker to Roblox's user icon
```

**--> :say(\<string:channelName>,\<string:message>,\<table:replyTo(message/optional)>)**

This method is used to make a speaker send a message. It returns the full message object, if you pass this as an additional argument to this method it will reply to that message.

```lua
local original = speaker:say("Main","Hello world!")
speaker:say("Main","Replying to Hello World!",original)
```

![](/files/suofOohViWPJ8u3TqRbF)

**--> :Destroy(\<void>)**

This method destroys the speaker and disconnects everything.

### Full examples

```lua
return function(api)
    local _,roblox = api.speaker.new("Roblox")
    roblox:setIcon("rbxthumb://type=AvatarHeadShot&id=1&w=420&h=420")
		
    local message = roblox:say("Main","Hello world!")
    roblox:say("Main","Hello there..",message)
end
```

![](/files/su4m3oXjobVPTL1OkaLC)