Chatwoot

Let hires read and answer your customers' conversations in Chatwoot, leave private notes, assign, label and resolve them, and be woken when a customer writes.

Explore 9 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With Chatwoot (open source) connected, a hire can:

list conversations in your inboxes: open, pending, resolved or snoozed, by inbox, by who they're assigned to, by label, or by words in the messages,
read a conversation, with private notes marked,
reply to the customer, or leave a private note only your team sees,
assign a conversation to a teammate or a team, add or remove labels, and open, resolve or snooze it.

It works with Chatwoot Cloud and with a Chatwoot you run yourself.

1. Make a Chatwoot user for Roster

Replies show in Chatwoot, and to your customers, under the name of the user whose access token Roster has. So add a user named after your team or business, like Bayt Studio Support, never a made-up person's name:

In Chatwoot, open Settings → Agents → Add agent, name it after your team and add it to the inboxes hires should work in.
Sign in as that user, open Profile settings and copy the Access token. Once you've typed the address and account ID in Roster, the form links straight to that page.

2. Connect it in Roster

Open Integrations → Tools → Add a tool, search for Chatwoot and choose it.
Fill in:
- Access token: the token you copied.
- Chatwoot address: leave https://app.chatwoot.com for Chatwoot Cloud, or put your own server's address.
- Account ID: the number after /app/accounts/ in Chatwoot's address bar.
- Business name: your business's name, like Bayt Studio.
Click Connect. Roster checks the token, and the connection shows Connected as your Chatwoot account and the user hires reply as. If Chatwoot refuses the token, Roster says so and saves nothing.

3. Let customers' messages reach Roster

When you connect, Roster adds its own webhook in Chatwoot (for Message created) and keeps the secret Chatwoot signs deliveries with, so a customer's message wakes the hire at once. There's nothing to paste, and removing the connection removes the webhook. It needs Chatwoot 4.12 or later, and a token whose user may manage the account's webhooks; otherwise a watching hire checks Chatwoot for new messages every so often instead.

To add the webhook by hand:

After connecting, copy the address the connection shows for Chatwoot to send to.
In Chatwoot, open Settings → Integrations → Webhooks → Add new webhook, paste the address and tick Message created.
Copy the webhook's secret and paste it as Webhook secret on the connection in Roster.

Roster checks every delivery really comes from your Chatwoot, using the secret, and ignores anything else.

4. Give hires access

On the hire's Tools tab, click Give access on Chatwoot:

Read only: it can list and read conversations, inboxes and teammates, and nothing else.
Read and write: it can also reply, leave notes, assign, label and change status.
Inboxes: inbox names or IDs it may use. Leave it empty for every inbox. A conversation in any other inbox is refused, even if the hire knows its number.

First replies wait for approval

The first public reply a hire writes to a customer it has never written to waits for a person's approval, even when the customer wrote in first. If someone on your team already replied publicly in the conversation, it doesn't ask. The hire asks in the thread with the conversation and the reply, and when the approver says yes, Roster posts exactly that reply, once. After that, replies to that customer go out without asking. Private notes never ask, and neither do replies to people at your team's own domains.

Customers your team already talks to can be added under Settings → Workspace → People you're already in touch with (more), by email address, domain or phone number. Approving a first reply adds the customer's address and number there too.

Waking a hire when a customer writes

A hire's responsibility can watch Chatwoot: when a customer writes in one of its inboxes, the hire is woken with the message, so it can answer.

Saying it's an AI assistant

A hire never pretends to be a person, and always says it's AI when asked. If you also want it to say so up front, turn on Say it's an AI assistant in first messages to outsiders under Settings → Workspace (more). Then the first reply a hire writes in a conversation starts with "This is the AI assistant for" and your business name. Private notes are never changed.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Chatwoot and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

In Chatwoot: Profile settings → Access token, for a user named after your team (replies show under its name).

No fixed permission list is declared for this connection. Review the sign-in consent screen, the account's roles, and the service's own documentation before connecting.

Connection fields

Chatwoot connection fields
Field	What to provide
Access token `token` Required · sealed secret	In Chatwoot: Profile settings → Access token, for a user named after your team (replies show under its name).
Chatwoot address `url` Optional	https://app.chatwoot.com for Chatwoot Cloud, or your own server's address. Starts with: `https://app.chatwoot.com`.
Account ID `accountId` Required	The number after /app/accounts/ in Chatwoot's address bar.
Business name `businessName` Required	Used when hires say they're your business's AI assistant. Never a made-up person's name.
Webhook secret `webhookSecret` Optional · sealed secret	Optional: from the webhook you add in Chatwoot (Settings → Integrations → Webhooks). With it, customers' messages wake hires at once.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

Chatwoot per-hire limits
Field	What to provide
Inboxes `inboxes` Optional	Inbox names or IDs it may use. Leave empty for every inbox.

Actions

9 actions: 4 only read and 5 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

Find an actionAccess

9 of 9 actions. Open an action for its arguments and full input schema.

list_inboxesRead only

The Chatwoot inboxes this hire may use, with their channel (website chat, email, WhatsApp…).

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}

list_conversationsRead only

Conversations in the inboxes this hire may use, most recent activity first: open ones by default, optionally by inbox, who they're assigned to, label, or words in their messages.

Approval: Uses your workspace and hire approval settings.

Arguments for list_conversations
Argument	Type	Details
`status`Optional	"open" \| "pending" \| "resolved" \| "snoozed" \| "all"	See input schema below.Default: `"open"`
`assigned`Optional	"all" \| "unassigned" \| "assigned" \| "me"	See input schema below.Default: `"all"`
`inbox`Optional	string	an inbox's name or ID
`label`Optional	string	See input schema below.
`search`Optional	string	words in the messages
`page`Optional	integer	See input schema below.Default: `1`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": {
      "default": "open",
      "type": "string",
      "enum": [
        "open",
        "pending",
        "resolved",
        "snoozed",
        "all"
      ]
    },
    "assigned": {
      "default": "all",
      "type": "string",
      "enum": [
        "all",
        "unassigned",
        "assigned",
        "me"
      ]
    },
    "inbox": {
      "description": "an inbox's name or ID",
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "search": {
      "description": "words in the messages",
      "type": "string",
      "maxLength": 200
    },
    "page": {
      "default": 1,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  }
}

read_conversationRead only

Read a conversation: who it's with, its status, and its latest messages oldest first, with private notes marked.

Approval: Uses your workspace and hire approval settings.

Arguments for read_conversation
Argument	Type	Details
`id`Required	integer	the conversation's number, like 123

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the conversation's number, like 123"
    }
  },
  "required": [
    "id"
  ]
}

replyRead and write

Reply to the customer in a conversation: they'll see it in their chat, email or messaging app. It goes out in the business's name: write as the business, never sign with a person's name or say you're one.

Approval: when it writes to someone outside your team for the first time.

Arguments for reply
Argument	Type	Details
`id`Required	integer	the conversation's number, like 123
`text`Required	string	See input schema below.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the conversation's number, like 123"
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10000
    }
  },
  "required": [
    "id",
    "text"
  ]
}

add_noteRead and write

Leave a private note in a conversation, for the team only; the customer never sees it.

Approval: Uses your workspace and hire approval settings.

Arguments for add_note
Argument	Type	Details
`id`Required	integer	the conversation's number, like 123
`text`Required	string	See input schema below.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the conversation's number, like 123"
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10000
    }
  },
  "required": [
    "id",
    "text"
  ]
}

assignRead and write

Assign a conversation to a teammate (by name or email) or to a team.

Approval: Uses your workspace and hire approval settings.

Arguments for assign
Argument	Type	Details
`id`Required	integer	the conversation's number, like 123
`agent`Optional	string	the teammate's name or email
`team`Optional	string	a team's name

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the conversation's number, like 123"
    },
    "agent": {
      "description": "the teammate's name or email",
      "type": "string"
    },
    "team": {
      "description": "a team's name",
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}

labelRead and write

Add labels to a conversation, or take labels off. Other labels stay.

Approval: Uses your workspace and hire approval settings.

Arguments for label
Argument	Type	Details
`id`Required	integer	the conversation's number, like 123
`add`Optional	string[]	See input schema below.Default: `[]`
`remove`Optional	string[]	See input schema below.Default: `[]`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the conversation's number, like 123"
    },
    "add": {
      "default": [],
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 100
      }
    },
    "remove": {
      "default": [],
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    }
  },
  "required": [
    "id"
  ]
}

set_statusRead and write

Open, mark pending, resolve or snooze a conversation (snoozed ones reopen when the customer writes).

Approval: Uses your workspace and hire approval settings.

Arguments for set_status
Argument	Type	Details
`id`Required	integer	the conversation's number, like 123
`status`Required	"open" \| "pending" \| "resolved" \| "snoozed"	See input schema below.
`until`Optional	string	snoozed: when to reopen it

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the conversation's number, like 123"
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "pending",
        "resolved",
        "snoozed"
      ]
    },
    "until": {
      "description": "snoozed: when to reopen it",
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    }
  },
  "required": [
    "id",
    "status"
  ]
}

list_agentsRead only

The teammates conversations can be assigned to, with whether they're online.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}

Watches and incoming events

This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
Incoming webhooks are supported. Roster can register the connection's callback with the service.

Limits and troubleshooting

Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
Expired or revoked access: reconnect or replace the key on the connection.
Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

1. Make a Chatwoot user for RosterCopy Anchor Link

2. Connect it in RosterCopy Anchor Link

3. Let customers' messages reach RosterCopy Anchor Link

4. Give hires accessCopy Anchor Link

First replies wait for approvalCopy Anchor Link

Saying it's an AI assistantCopy Anchor Link

Tools and permissions reference

Authentication and requested permissions

API key or access token

Connection fields

Per-hire limits

Actions

Watches and incoming events

Limits and troubleshooting

On this page

1. Make a Chatwoot user for Roster

2. Connect it in Roster

3. Let customers' messages reach Roster

4. Give hires access

First replies wait for approval

Saying it's an AI assistant