# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://jumpathy.gitbook.io/betterchat-v3/server/speaker.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.