Inboxes - Chatwoot

Overview

Inboxes represent communication channels through which conversations occur. Each inbox can be a website widget, email, SMS, social media channel, or API.

List All Inboxes

Retrieve all inboxes in your account.

GET /api/v1/accounts/{account_id}/inboxes

Path Parameters

account_id

integer

required

The ID of the account

Response

integer

Inbox ID

name

string

Inbox name

channel_id

integer

Associated channel ID

channel_type

string

Channel type: Channel::WebWidget, Channel::Email, Channel::Api, etc.

greeting_enabled

boolean

Whether greeting message is enabled

greeting_message

string

Greeting message content

enable_auto_assignment

boolean

Whether auto-assignment is enabled

working_hours_enabled

boolean

Whether working hours are configured

timezone

string

Inbox timezone

Example Request

curl -X GET https://app.chatwoot.com/api/v1/accounts/1/inboxes \
  -H "api_access_token: YOUR_ACCESS_TOKEN"

Example Response

{
  "payload": [
    {
      "id": 1,
      "name": "Website Widget",
      "channel_id": 1,
      "channel_type": "Channel::WebWidget",
      "greeting_enabled": true,
      "greeting_message": "Hello! How can we help you?",
      "enable_auto_assignment": true,
      "working_hours_enabled": true,
      "timezone": "America/New_York",
      "avatar_url": "https://example.com/inbox-avatar.png"
    },
    {
      "id": 2,
      "name": "Support Email",
      "channel_id": 2,
      "channel_type": "Channel::Email",
      "greeting_enabled": false,
      "enable_auto_assignment": true,
      "working_hours_enabled": false
    }
  ]
}

Get Inbox

Retrieve details of a specific inbox.

GET /api/v1/accounts/{account_id}/inboxes/{id}

Path Parameters

account_id

integer

required

The ID of the account

integer

required

The ID of the inbox

Example Request

curl -X GET https://app.chatwoot.com/api/v1/accounts/1/inboxes/1 \
  -H "api_access_token: YOUR_ACCESS_TOKEN"

Create Inbox

Create a new inbox with a communication channel.

POST /api/v1/accounts/{account_id}/inboxes

Path Parameters

account_id

integer

required

The ID of the account

Request Body

name

string

required

Inbox name

channel[type]

string

required

Channel type: web_widget, api, email, line, telegram, whatsapp, sms

greeting_enabled

boolean

default:"false"

Enable greeting message

greeting_message

string

Greeting message text

enable_auto_assignment

boolean

default:"true"

Enable automatic conversation assignment

enable_email_collect

boolean

default:"true"

Enable email collection (web widget only)

csat_survey_enabled

boolean

default:"false"

Enable CSAT survey

timezone

string

Inbox timezone (e.g., “America/New_York”)

curl -X POST https://app.chatwoot.com/api/v1/accounts/1/inboxes \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website Support",
    "channel": {
      "type": "web_widget",
      "website_url": "https://example.com",
      "welcome_title": "Welcome!",
      "welcome_tagline": "How can we help?",
      "widget_color": "#1f93ff"
    },
    "greeting_enabled": true,
    "greeting_message": "Hi there! How can I help you today?",
    "enable_auto_assignment": true
  }'

Example Request (API Channel)

curl -X POST https://app.chatwoot.com/api/v1/accounts/1/inboxes \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App",
    "channel": {
      "type": "api",
      "webhook_url": "https://example.com/webhooks/chatwoot"
    },
    "enable_auto_assignment": true
  }'

Example Request (Email Channel)

curl -X POST https://app.chatwoot.com/api/v1/accounts/1/inboxes \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Email",
    "channel": {
      "type": "email",
      "email": "[email protected]",
      "imap_enabled": true,
      "imap_address": "imap.gmail.com",
      "imap_port": 993,
      "imap_email": "[email protected]",
      "imap_password": "app_password",
      "smtp_enabled": true,
      "smtp_address": "smtp.gmail.com",
      "smtp_port": 587,
      "smtp_email": "[email protected]",
      "smtp_password": "app_password"
    }
  }'

Example Response

{
  "id": 3,
  "name": "Website Support",
  "channel_id": 3,
  "channel_type": "Channel::WebWidget",
  "greeting_enabled": true,
  "greeting_message": "Hi there! How can I help you today?",
  "enable_auto_assignment": true,
  "webhook_url": "https://app.chatwoot.com/api/v1/webhooks/..."
}

Update Inbox

Update inbox settings and configuration.

PATCH /api/v1/accounts/{account_id}/inboxes/{id}

Path Parameters

account_id

integer

required

The ID of the account

integer

required

The ID of the inbox to update

Request Body

Accepts the same parameters as Create Inbox.

Example Request

curl -X PATCH https://app.chatwoot.com/api/v1/accounts/1/inboxes/1 \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Inbox Name",
    "greeting_message": "Welcome! We are here to help.",
    "enable_auto_assignment": false
  }'

Delete Inbox

Delete an inbox and its associated channel.

DELETE /api/v1/accounts/{account_id}/inboxes/{id}

Path Parameters

account_id

integer

required

The ID of the account

integer

required

The ID of the inbox to delete

Example Request

curl -X DELETE https://app.chatwoot.com/api/v1/accounts/1/inboxes/3 \
  -H "api_access_token: YOUR_ACCESS_TOKEN"

Deleting an inbox will remove all associated conversations and messages. This action cannot be undone.

Get Agent Bot

Retrieve the agent bot assigned to an inbox.

GET /api/v1/accounts/{account_id}/inboxes/{id}/agent_bot

Example Request

curl -X GET https://app.chatwoot.com/api/v1/accounts/1/inboxes/1/agent_bot \
  -H "api_access_token: YOUR_ACCESS_TOKEN"

Set Agent Bot

Assign an agent bot to an inbox.

POST /api/v1/accounts/{account_id}/inboxes/{id}/set_agent_bot

Request Body

agent_bot

integer

Agent bot ID (set to null to remove bot)

Example Request

curl -X POST https://app.chatwoot.com/api/v1/accounts/1/inboxes/1/set_agent_bot \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_bot": 1
  }'

Delete Avatar

Remove the inbox avatar image.

DELETE /api/v1/accounts/{account_id}/inboxes/{id}/avatar

Example Request

curl -X DELETE https://app.chatwoot.com/api/v1/accounts/1/inboxes/1/avatar \
  -H "api_access_token: YOUR_ACCESS_TOKEN"

Get Campaigns

Retrieve campaigns associated with an inbox.

GET /api/v1/accounts/{account_id}/inboxes/{id}/campaigns

Example Request

curl -X GET https://app.chatwoot.com/api/v1/accounts/1/inboxes/1/campaigns \
  -H "api_access_token: YOUR_ACCESS_TOKEN"

Sync Templates

Sync message templates for WhatsApp inboxes.

POST /api/v1/accounts/{account_id}/inboxes/{id}/sync_templates

Example Request

curl -X POST https://app.chatwoot.com/api/v1/accounts/1/inboxes/1/sync_templates \
  -H "api_access_token: YOUR_ACCESS_TOKEN"

Template sync is only available for WhatsApp channels (Cloud API and Twilio).

Get Health Status

Check the health status of a WhatsApp Cloud API inbox.

GET /api/v1/accounts/{account_id}/inboxes/{id}/health

Example Request

curl -X GET https://app.chatwoot.com/api/v1/accounts/1/inboxes/1/health \
  -H "api_access_token: YOUR_ACCESS_TOKEN"

Example Response

{
  "status": "healthy",
  "quality_rating": "green",
  "messaging_limit": "tier_1k"
}

Channel Types

Embeddable chat widget for websites. Required channel parameters:

website_url - Website URL
welcome_title - Welcome message title
welcome_tagline - Welcome message tagline
widget_color - Widget theme color

API

Programmatic messaging channel. Required channel parameters:

webhook_url - Webhook URL for callbacks (optional)

Email

Email-based inbox with IMAP/SMTP. Required channel parameters:

email - Email address
imap_enabled - Enable IMAP
imap_address - IMAP server address
imap_port - IMAP port
imap_email - IMAP login email
imap_password - IMAP password
smtp_enabled - Enable SMTP
smtp_address - SMTP server address
smtp_port - SMTP port
smtp_email - SMTP login email
smtp_password - SMTP password

Line

LINE messaging integration. Required channel parameters:

line_channel_id - LINE channel ID
line_channel_secret - LINE channel secret
line_channel_token - LINE channel access token

Telegram bot integration. Required channel parameters:

bot_token - Telegram bot token

WhatsApp Business API integration. Required channel parameters:

phone_number - WhatsApp phone number
provider - Provider: whatsapp_cloud or default
api_key - API key (provider-specific)

SMS

SMS messaging via Twilio. Required channel parameters:

phone_number - SMS phone number
account_sid - Twilio account SID
auth_token - Twilio auth token

Working Hours

Configure working hours for an inbox:

{
  "working_hours_enabled": true,
  "timezone": "America/New_York",
  "working_hours": [
    {
      "day_of_week": 1,
      "open_hour": 9,
      "open_minutes": 0,
      "close_hour": 17,
      "close_minutes": 0,
      "closed_all_day": false
    }
  ]
}

CSAT Survey

Configure CSAT (Customer Satisfaction) surveys:

{
  "csat_survey_enabled": true,
  "csat_config": {
    "display_type": "emoji",
    "message": "How would you rate your experience?",
    "button_text": "Rate us",
    "language": "en",
    "survey_rules": {
      "operator": "contains",
      "values": ["resolved"]
    }
  }
}

Error Responses

Inbox Not Found

{
  "error": "Inbox not found"
}

Invalid Channel Type

{
  "error": "Invalid channel type"
}

Account Limit Exceeded

{
  "error": "Account limit exceeded. Please upgrade your plan"
}

API Reference

Integrations

Advanced

​Overview

​List All Inboxes

​Path Parameters

​Response

​Example Request

​Example Response

​Get Inbox

​Path Parameters

​Example Request

​Create Inbox

​Path Parameters

​Request Body

​Example Request (Web Widget)

​Example Request (API Channel)

​Example Request (Email Channel)

​Example Response

​Update Inbox

​Path Parameters

​Request Body

​Example Request

​Delete Inbox

​Path Parameters

​Example Request

​Get Agent Bot

​Example Request

​Set Agent Bot

​Request Body

​Example Request

​Delete Avatar

​Example Request

​Get Campaigns

​Example Request

​Sync Templates

​Example Request

​Get Health Status

​Example Request

​Example Response

​Channel Types

​Web Widget

​API

​Email

​Line

​Telegram

​WhatsApp

​SMS

​Working Hours

​CSAT Survey

​Error Responses

​Inbox Not Found

​Invalid Channel Type

​Account Limit Exceeded

Build docs developers (and LLMs) love

Overview

List All Inboxes

Path Parameters

Response

Example Request

Example Response

Get Inbox

Path Parameters

Example Request

Create Inbox

Path Parameters

Request Body

Example Request (Web Widget)

Example Request (API Channel)

Example Request (Email Channel)

Example Response

Update Inbox

Path Parameters

Request Body

Example Request

Delete Inbox

Path Parameters

Example Request

Get Agent Bot

Example Request

Set Agent Bot

Request Body

Example Request

Delete Avatar

Example Request

Get Campaigns

Example Request

Sync Templates

Example Request

Get Health Status

Example Request

Example Response

Channel Types

Web Widget

API

Email

Line

Telegram

WhatsApp

SMS

Working Hours

CSAT Survey

Error Responses

Inbox Not Found

Invalid Channel Type

Account Limit Exceeded