Chatwoot

App · 14 actions

Run customer support in Chatwoot: reply to and resolve conversations, assign and label them, and manage contacts. Start a workflow when a conversation starts.

Actions

ActionWhat it does
Assign conversationAssign a conversation to an agent, or to a team.
Change contactChange a contact's name, email, phone number, your ID for them or custom attributes.
Create contactAdd a contact, with an email, phone number or your own ID for them.
Delete contactDelete a contact and their conversations.
Find contactsFind contacts by name, email, phone number or your ID for them, most recently active first.
Get conversationGet one conversation: who it's with, its status, labels, assignee and latest message.
List conversationsList conversations, most recently active first, by status, assignee, inbox, label or words.
List inboxesList the account's inboxes, or only those of one kind, such as API or email.
List messagesList a conversation's recent messages and notes, oldest first.
Send messageReply in a conversation, or add a private note only agents see.
Set conversation labelsSet a conversation's labels, replacing the ones it has.
Set conversation prioritySet how urgent a conversation is.
Set conversation statusOpen, resolve, mark pending or snooze a conversation.
Start conversationStart a conversation with a contact in an inbox, with a first message.

Assign conversation

Assign a conversation to an agent, or to a team.

Inputs

ConversationconversationtextRequired
The conversation's number, as shown in Chatwoot (#123), or its link.
Agentagenttext
The agent to assign it to, or me for the connected agent.
Or teamteamtext
Instead of an agent, the team to assign it to.

Outputs

assigned_idnumber
The agent's or team's number
assigned_totext
The agent's or team's name
conversation_idnumber
The conversation
Example output
{
  "assigned_id": 5,
  "assigned_to": "Alex",
  "conversation_id": 1042
}

Change contact

Change a contact's name, email, phone number, your ID for them or custom attributes.

Inputs

ContactcontacttextRequired
The contact's number, from 'Find contacts' or 'Create contact'.
Namenametext
A new name. Leave empty to keep it.
Emailemailtext
Their email address. Leave empty to keep it.
Phonephone_numbertext
Their phone number in international form, such as +14155550100. Leave empty to keep it.
Your ID for themidentifiertext
Their ID in your own system, such as a customer number. Leave empty to keep it.
Custom attributescustom_attributesobject
Extra details as fields and values, such as plan: Pro. Leave empty to keep it.

Outputs

created_attext
When they were added (ISO 8601)
custom_attributesobject
Their custom attributes
emailtext
Their email address
idnumber
The contact's number
identifiertext
Your ID for them
last_activity_attext
When they were last active (ISO 8601)
nametext
Their name
phone_numbertext
Their phone number
Example output
{
  "created_at": "2026-10-01T09:00:00Z",
  "custom_attributes": {
    "plan": "Pro"
  },
  "email": "sam@example.com",
  "id": 87,
  "identifier": "cus_123",
  "last_activity_at": "2026-10-28T09:05:00Z",
  "name": "Sam Lee",
  "phone_number": "+14155550100"
}

Create contact

Add a contact, with an email, phone number or your own ID for them.

Inputs

NamenametextRequired
Their name.
Emailemailtext
Their email address.
Phonephone_numbertext
Their phone number in international form, such as +14155550100.
Your ID for themidentifiertext
Their ID in your own system, such as a customer number.
Custom attributescustom_attributesobject
Extra details as fields and values, such as plan: Pro.
Inboxinboxtext
Also add them to this inbox, ready to start a conversation.

Outputs

created_attext
When they were added (ISO 8601)
custom_attributesobject
Their custom attributes
emailtext
Their email address
idnumber
The contact's number
identifiertext
Your ID for them
last_activity_attext
When they were last active (ISO 8601)
nametext
Their name
phone_numbertext
Their phone number
Example output
{
  "created_at": "2026-10-01T09:00:00Z",
  "custom_attributes": {
    "plan": "Pro"
  },
  "email": "sam@example.com",
  "id": 87,
  "identifier": "cus_123",
  "last_activity_at": "2026-10-28T09:05:00Z",
  "name": "Sam Lee",
  "phone_number": "+14155550100"
}

Delete contact

Delete a contact and their conversations. It cannot be undone.

Inputs

ContactcontacttextRequired
The contact's number, from 'Find contacts' or 'Create contact'.

Outputs

deletedtrue/false
True once deleted
idnumber
The contact's number
Example output
{
  "deleted": true,
  "id": 87
}

Find contacts

Find contacts by name, email, phone number or your ID for them, most recently active first.

Inputs

Searchsearchtext
A name, email, phone number or your ID. Leave empty for everyone.
How manylimitnumber
How many contacts. Defaults to 25.From 1 to 500.

Outputs

contactslist
The contacts
countnumber
How many contacts
Example output
{
  "contacts": [
    {
      "created_at": "2026-10-01T09:00:00Z",
      "custom_attributes": {
        "plan": "Pro"
      },
      "email": "sam@example.com",
      "id": 87,
      "identifier": "cus_123",
      "last_activity_at": "2026-10-28T09:05:00Z",
      "name": "Sam Lee",
      "phone_number": "+14155550100"
    }
  ],
  "count": 1
}

Get conversation

Get one conversation: who it's with, its status, labels, assignee and latest message.

Inputs

ConversationconversationtextRequired
The conversation's number, as shown in Chatwoot (#123), or its link.

Outputs

assignee_idnumber
The assigned agent's number; 0 if unassigned
assignee_nametext
The assigned agent's name
contact_emailtext
The contact's email address
contact_idnumber
The contact's number
contact_nametext
The contact's name
created_attext
When it started (ISO 8601)
idnumber
The conversation's number
inbox_idnumber
The inbox it came in through
labelslist
Its labels
last_activity_attext
When it was last active (ISO 8601)
last_messagetext
The latest message
prioritytext
urgent, high, medium or low; empty if none
statustext
open, pending, snoozed or resolved
team_nametext
The assigned team's name
unread_countnumber
How many messages the agents haven't read
Example output
{
  "assignee_id": 5,
  "assignee_name": "Alex",
  "contact_email": "sam@example.com",
  "contact_id": 87,
  "contact_name": "Sam Lee",
  "created_at": "2026-10-28T09:00:00Z",
  "id": 1042,
  "inbox_id": 3,
  "labels": [
    "billing"
  ],
  "last_activity_at": "2026-10-28T09:05:00Z",
  "last_message": "My invoice shows the wrong amount.",
  "priority": "high",
  "status": "open",
  "team_name": "Support",
  "unread_count": 1
}

List conversations

List conversations, most recently active first, by status, assignee, inbox, label or words.

Inputs

Statusstatustext
Only conversations with this status. Defaults to open.One of: all (Any status), open, pending, snoozed, resolved. Default: open.
Assignedassignedtext
Only those assigned to you, to no one, or to someone. Defaults to all.One of: all (Anyone or no one), me (Assigned to me), unassigned, assigned (Assigned to someone). Default: all.
Inboxinboxtext
Only this inbox's conversations.
Labellabeltext
Only conversations with this label.
Messages containsearchtext
Only conversations with a message containing these words.
How manylimitnumber
How many conversations. Defaults to 25.From 1 to 500.

Outputs

conversationslist
The conversations, most recently active first
countnumber
How many conversations
Example output
{
  "conversations": [
    {
      "assignee_id": 5,
      "assignee_name": "Alex",
      "contact_email": "sam@example.com",
      "contact_id": 87,
      "contact_name": "Sam Lee",
      "created_at": "2026-10-28T09:00:00Z",
      "id": 1042,
      "inbox_id": 3,
      "labels": [
        "billing"
      ],
      "last_activity_at": "2026-10-28T09:05:00Z",
      "last_message": "My invoice shows the wrong amount.",
      "priority": "high",
      "status": "open",
      "team_name": "Support",
      "unread_count": 1
    }
  ],
  "count": 1
}

List inboxes

List the account's inboxes, or only those of one kind, such as API or email.

Inputs

Kindchanneltext
Only inboxes of this kind. Leave empty for all.One of: api, website (Website chat), email, whatsapp, sms, facebook, instagram, telegram, line.

Outputs

countnumber
How many inboxes
inboxeslist
The inboxes
Example output
{
  "count": 1,
  "inboxes": [
    {
      "channel": "website",
      "id": 3,
      "name": "Website"
    }
  ]
}

List messages

List a conversation's recent messages and notes, oldest first.

Inputs

ConversationconversationtextRequired
The conversation's number, as shown in Chatwoot (#123), or its link.

Outputs

conversation_idnumber
The conversation
countnumber
How many messages
messageslist
The messages, oldest first
Example output
{
  "conversation_id": 1042,
  "count": 1,
  "messages": [
    {
      "content": "Thanks, we're looking into it.",
      "created_at": "2026-10-28T09:06:00Z",
      "id": 9001,
      "kind": "outgoing",
      "private": false,
      "sender_name": "Alex",
      "sender_type": "user"
    }
  ]
}

Send message

Reply in a conversation, or add a private note only agents see.

Inputs

ConversationconversationtextRequired
The conversation's number, as shown in Chatwoot (#123), or its link.
MessagecontenttextRequired
What to say.
Private noteprivate_notetrue/false
Add it as a note only agents see, rather than sending it to the contact. Off by default.Default: false.

Outputs

contenttext
What it says
conversation_idnumber
The conversation
created_attext
When it was sent (ISO 8601)
idnumber
The message's number
kindtext
incoming, outgoing, activity or template
privatetrue/false
True for a private note only agents see
sender_nametext
Who sent it
sender_typetext
contact, user (an agent) or agent_bot
Example output
{
  "content": "Thanks, we're looking into it.",
  "conversation_id": 1042,
  "created_at": "2026-10-28T09:06:00Z",
  "id": 9001,
  "kind": "outgoing",
  "private": false,
  "sender_name": "Alex",
  "sender_type": "user"
}

Set conversation labels

Set a conversation's labels, replacing the ones it has.

Inputs

ConversationconversationtextRequired
The conversation's number, as shown in Chatwoot (#123), or its link.
Labelslabelslist
Its labels. Leave empty to take them all off.

Outputs

conversation_idnumber
The conversation
labelslist
Its labels now
Example output
{
  "conversation_id": 1042,
  "labels": [
    "billing",
    "vip"
  ]
}

Set conversation priority

Set how urgent a conversation is.

Inputs

ConversationconversationtextRequired
The conversation's number, as shown in Chatwoot (#123), or its link.
PriorityprioritytextRequired
How urgent it is.One of: urgent, high, medium, low, none (No priority).

Outputs

conversation_idnumber
The conversation
prioritytext
Its priority; empty for none
Example output
{
  "conversation_id": 1042,
  "priority": "urgent"
}

Set conversation status

Open, resolve, mark pending or snooze a conversation.

Inputs

ConversationconversationtextRequired
The conversation's number, as shown in Chatwoot (#123), or its link.
StatusstatustextRequired
The conversation's new status.One of: open, pending, snoozed, resolved.
Snooze untilsnooze_untildate and time
When snoozing, when to reopen it. Leave empty to reopen at the contact's next reply.

Outputs

conversation_idnumber
The conversation
statustext
Its new status
Example output
{
  "conversation_id": 1042,
  "status": "resolved"
}

Start conversation

Start a conversation with a contact in an inbox, with a first message.

Inputs

InboxinboxtextRequired
The inbox to start it in: an API, website, email or SMS inbox.
ContactcontacttextRequired
The contact's number, from 'Find contacts' or 'Create contact'.
First messagemessagetextRequired
What to say first.
Statusstatustext
Open, pending or resolved. Defaults to open.One of: open, pending, resolved.

Outputs

assignee_idnumber
The assigned agent's number; 0 if unassigned
assignee_nametext
The assigned agent's name
contact_emailtext
The contact's email address
contact_idnumber
The contact's number
contact_nametext
The contact's name
created_attext
When it started (ISO 8601)
idnumber
The conversation's number
inbox_idnumber
The inbox it came in through
labelslist
Its labels
last_activity_attext
When it was last active (ISO 8601)
last_messagetext
The latest message
prioritytext
urgent, high, medium or low; empty if none
statustext
open, pending, snoozed or resolved
team_nametext
The assigned team's name
unread_countnumber
How many messages the agents haven't read
Example output
{
  "assignee_id": 0,
  "assignee_name": "",
  "contact_email": "sam@example.com",
  "contact_id": 87,
  "contact_name": "Sam Lee",
  "created_at": "2026-10-28T09:00:00Z",
  "id": 1042,
  "inbox_id": 3,
  "labels": [],
  "last_activity_at": "2026-10-28T09:05:00Z",
  "last_message": "My invoice shows the wrong amount.",
  "priority": "",
  "status": "open",
  "team_name": "Support",
  "unread_count": 1
}

On this page