Conversations List

GET

api

accounts

{account_id}

conversations

Conversations List

curl --request GET \
  --url https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations \
  --header 'api_access_token: <api-key>'

{
  "data": {
    "meta": {
      "mine_count": 123,
      "unassigned_count": 123,
      "assigned_count": 123,
      "all_count": 123
    },
    "payload": [
      {
        "id": 123,
        "messages": [
          {
            "id": 123,
            "content": "<string>",
            "account_id": 123,
            "inbox_id": 123,
            "conversation_id": 123,
            "message_type": 0,
            "created_at": 123,
            "updated_at": 123,
            "private": true,
            "status": "sent",
            "source_id": "<string>",
            "content_type": "text",
            "content_attributes": {},
            "sender_type": "contact",
            "sender_id": 123,
            "external_source_ids": {},
            "additional_attributes": {},
            "processed_message_content": "<string>",
            "sentiment": {},
            "conversation": {},
            "attachment": {},
            "sender": {}
          }
        ],
        "account_id": 123,
        "uuid": "<string>",
        "additional_attributes": {},
        "agent_last_seen_at": 123,
        "assignee_last_seen_at": 123,
        "can_reply": true,
        "contact_last_seen_at": 123,
        "custom_attributes": {},
        "inbox_id": 123,
        "labels": [
          "<string>"
        ],
        "muted": true,
        "snoozed_until": 123,
        "status": "open",
        "created_at": 123,
        "updated_at": 123,
        "timestamp": "<string>",
        "first_reply_created_at": 123,
        "unread_count": 123,
        "last_non_activity_message": {
          "id": 123,
          "content": "<string>",
          "account_id": 123,
          "inbox_id": 123,
          "conversation_id": 123,
          "message_type": 0,
          "created_at": 123,
          "updated_at": 123,
          "private": true,
          "status": "sent",
          "source_id": "<string>",
          "content_type": "text",
          "content_attributes": {},
          "sender_type": "contact",
          "sender_id": 123,
          "external_source_ids": {},
          "additional_attributes": {},
          "processed_message_content": "<string>",
          "sentiment": {},
          "conversation": {},
          "attachment": {},
          "sender": {}
        },
        "last_activity_at": 123,
        "priority": "<string>",
        "waiting_since": 123,
        "sla_policy_id": 123,
        "applied_sla": {},
        "sla_events": [
          {}
        ],
        "meta": {
          "sender": {
            "additional_attributes": {},
            "availability_status": "<string>",
            "email": "<string>",
            "id": 123,
            "name": "<string>",
            "phone_number": "<string>",
            "blocked": true,
            "identifier": "<string>",
            "thumbnail": "<string>",
            "custom_attributes": {},
            "last_activity_at": 123,
            "created_at": 123
          },
          "channel": "<string>",
          "assignee": {
            "id": 123,
            "access_token": "<string>",
            "account_id": 123,
            "available_name": "<string>",
            "avatar_url": "<string>",
            "confirmed": true,
            "display_name": "<string>",
            "message_signature": "<string>",
            "email": "<string>",
            "hmac_identifier": "<string>",
            "inviter_id": 123,
            "name": "<string>",
            "provider": "<string>",
            "pubsub_token": "<string>",
            "role": "agent",
            "ui_settings": {},
            "uid": "<string>",
            "type": "<string>",
            "custom_attributes": {},
            "accounts": [
              {
                "id": 123,
                "name": "<string>",
                "status": "<string>",
                "active_at": "2023-11-07T05:31:56Z",
                "role": "administrator",
                "permissions": [
                  "<string>"
                ],
                "availability": "<string>",
                "availability_status": "<string>",
                "auto_offline": true,
                "custom_role_id": 123,
                "custom_role": {}
              }
            ]
          },
          "hmac_verified": true
        }
      }
    ]
  }
}

Authorizations

api_access_token

string

header

required

This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user.

Path Parameters

account_id

integer

required

The numeric ID of the account

Query Parameters

assignee_type

enum<string>

default:all

Filter conversations by assignee type.

Available options:

me,

unassigned,

all,

assigned

status

enum<string>

default:open

Filter by conversation status.

Available options:

all,

open,

resolved,

pending,

snoozed

string

Filters conversations with messages containing the search term

inbox_id

integer

team_id

integer

labels

string[]

page

integer

default:1

paginate through conversations

Response

Success

data

object

Show child attributes

data.meta

object

Show child attributes

data.meta.mine_count

number

data.meta.unassigned_count

number

data.meta.assigned_count

number

data.meta.all_count

number

data.payload

object[]

array of conversations

Show child attributes

data.payload.id

number

ID of the conversation

data.payload.messages

object[]

Show child attributes

data.payload.messages.id

number

The ID of the message

data.payload.messages.content

string

The text content of the message

data.payload.messages.account_id

number

The ID of the account

data.payload.messages.inbox_id

number

The ID of the inbox

data.payload.messages.conversation_id

number

The ID of the conversation

data.payload.messages.message_type

enum<integer>

The type of the message

Available options:

0,

1,

2

data.payload.messages.created_at

integer

The time at which message was created

data.payload.messages.updated_at

integer

The time at which message was updated

data.payload.messages.private

boolean

The flags which shows whether the message is private or not

data.payload.messages.status

enum<string>

The status of the message

Available options:

sent,

delivered,

read,

failed

data.payload.messages.source_id

string

The source ID of the message

data.payload.messages.content_type

enum<string>

The type of the template message

Available options:

text,

input_select,

cards,

form

data.payload.messages.content_attributes

object

The content attributes for each content_type

data.payload.messages.sender_type

enum<string>

The type of the sender

Available options:

contact,

agent,

agent_bot

data.payload.messages.sender_id

number

The ID of the sender

data.payload.messages.external_source_ids

object

The external source IDs of the message

data.payload.messages.additional_attributes

object

The additional attributes of the message

data.payload.messages.processed_message_content

string

The processed message content

data.payload.messages.sentiment

object

The sentiment of the message

data.payload.messages.conversation

object

The conversation object

data.payload.messages.attachment

object

The file object attached to the image

data.payload.messages.sender

object

User/Agent/AgentBot object

data.payload.account_id

number

Account Id

data.payload.uuid

string

UUID of the conversation

data.payload.additional_attributes

object

The object containing additional attributes related to the conversation

data.payload.agent_last_seen_at

number

The last activity at of the agent

data.payload.assignee_last_seen_at

number

The last activity at of the assignee

data.payload.can_reply

boolean

Whether the conversation can be replied to

data.payload.contact_last_seen_at

number

The last activity at of the contact

data.payload.custom_attributes

object

The object to save custom attributes for conversation, accepts custom attributes key and value

data.payload.inbox_id

number

ID of the inbox

data.payload.labels

string[]

The labels of the conversation

data.payload.muted

boolean

Whether the conversation is muted

data.payload.snoozed_until

number

The time at which the conversation will be unmuted

data.payload.status

enum<string>

The status of the conversation

Available options:

open,

resolved,

pending

data.payload.created_at

number

The time at which conversation was created

data.payload.updated_at

number

The time at which conversation was updated

data.payload.timestamp

string

The time at which conversation was created

data.payload.first_reply_created_at

number

The time at which the first reply was created

data.payload.unread_count

number

The number of unread messages

data.payload.last_non_activity_message

object

Show child attributes

data.payload.last_non_activity_message.id

number

The ID of the message

data.payload.last_non_activity_message.content

string

The text content of the message

data.payload.last_non_activity_message.account_id

number

The ID of the account

data.payload.last_non_activity_message.inbox_id

number

The ID of the inbox

data.payload.last_non_activity_message.conversation_id

number

The ID of the conversation

data.payload.last_non_activity_message.message_type

enum<integer>

The type of the message

Available options:

0,

1,

2

data.payload.last_non_activity_message.created_at

integer

The time at which message was created

data.payload.last_non_activity_message.updated_at

integer

The time at which message was updated

data.payload.last_non_activity_message.private

boolean

The flags which shows whether the message is private or not

data.payload.last_non_activity_message.status

enum<string>

The status of the message

Available options:

sent,

delivered,

read,

failed

data.payload.last_non_activity_message.source_id

string

The source ID of the message

data.payload.last_non_activity_message.content_type

enum<string>

The type of the template message

Available options:

text,

input_select,

cards,

form

data.payload.last_non_activity_message.content_attributes

object

The content attributes for each content_type

data.payload.last_non_activity_message.sender_type

enum<string>

The type of the sender

Available options:

contact,

agent,

agent_bot

data.payload.last_non_activity_message.sender_id

number

The ID of the sender

data.payload.last_non_activity_message.external_source_ids

object

The external source IDs of the message

data.payload.last_non_activity_message.additional_attributes

object

The additional attributes of the message

data.payload.last_non_activity_message.processed_message_content

string

The processed message content

data.payload.last_non_activity_message.sentiment

object

The sentiment of the message

data.payload.last_non_activity_message.conversation

object

The conversation object

data.payload.last_non_activity_message.attachment

object

The file object attached to the image

data.payload.last_non_activity_message.sender

object

User/Agent/AgentBot object

data.payload.last_activity_at

number

The last activity at of the conversation

data.payload.priority

string

The priority of the conversation

data.payload.waiting_since

number

The time at which the conversation was waiting

data.payload.sla_policy_id

number

The ID of the SLA policy

data.payload.applied_sla

object

The applied SLA

data.payload.sla_events

object[]

data.payload.meta

object

Show child attributes

data.payload.meta.sender

object

Show child attributes

data.payload.meta.sender.additional_attributes

object

The additional attributes of the sender

data.payload.meta.sender.availability_status

string

The availability status of the sender

data.payload.meta.sender.email

string

The email of the sender

data.payload.meta.sender.id

number

ID fo the sender

data.payload.meta.sender.name

string

The name of the sender

data.payload.meta.sender.phone_number

string

The phone number of the sender

data.payload.meta.sender.blocked

boolean

Whether the sender is blocked

data.payload.meta.sender.identifier

string

The identifier of the sender

data.payload.meta.sender.thumbnail

string

Avatar URL of the contact

data.payload.meta.sender.custom_attributes

object

The custom attributes of the sender

data.payload.meta.sender.last_activity_at

number

The last activity at of the sender

data.payload.meta.sender.created_at

number

The created at of the sender

data.payload.meta.channel

string

Channel Type

data.payload.meta.assignee

object

Show child attributes

data.payload.meta.assignee.id

number

data.payload.meta.assignee.access_token

string

data.payload.meta.assignee.account_id

number

data.payload.meta.assignee.available_name

string

data.payload.meta.assignee.avatar_url

string

data.payload.meta.assignee.confirmed

boolean

data.payload.meta.assignee.display_name

string | null

data.payload.meta.assignee.message_signature

string | null

data.payload.meta.assignee.email

string

data.payload.meta.assignee.hmac_identifier

string

data.payload.meta.assignee.inviter_id

number

data.payload.meta.assignee.name

string

data.payload.meta.assignee.provider

string

data.payload.meta.assignee.pubsub_token

string

data.payload.meta.assignee.role

enum<string>

Available options:

agent,

administrator

data.payload.meta.assignee.ui_settings

object

data.payload.meta.assignee.uid

string

data.payload.meta.assignee.type

string | null

data.payload.meta.assignee.custom_attributes

object

Available for users who are created through platform APIs and has custom attributes associated.

data.payload.meta.assignee.accounts

object[]

Show child attributes

data.payload.meta.assignee.accounts.id

number

data.payload.meta.assignee.accounts.name

string

data.payload.meta.assignee.accounts.status

string

data.payload.meta.assignee.accounts.active_at

string<date-time>

data.payload.meta.assignee.accounts.role

enum<string>

Available options:

administrator,

agent

data.payload.meta.assignee.accounts.permissions

string[]

data.payload.meta.assignee.accounts.availability

string

data.payload.meta.assignee.accounts.availability_status

string

data.payload.meta.assignee.accounts.auto_offline

boolean

data.payload.meta.assignee.accounts.custom_role_id

number | null

data.payload.meta.assignee.accounts.custom_role

object

data.payload.meta.hmac_verified

boolean

Whether the hmac is verified

Create New ConversationCreating a conversation in chatwoot requires a source id. Learn more about source_id: https://www.chatwoot.com/hc/user-guide/articles/1677839703-how-to-create-an-api-channel-inbox#send-messages-to-the-api-channel

⌘I

Conversations List

curl --request GET \
  --url https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations \
  --header 'api_access_token: <api-key>'

{
  "data": {
    "meta": {
      "mine_count": 123,
      "unassigned_count": 123,
      "assigned_count": 123,
      "all_count": 123
    },
    "payload": [
      {
        "id": 123,
        "messages": [
          {
            "id": 123,
            "content": "<string>",
            "account_id": 123,
            "inbox_id": 123,
            "conversation_id": 123,
            "message_type": 0,
            "created_at": 123,
            "updated_at": 123,
            "private": true,
            "status": "sent",
            "source_id": "<string>",
            "content_type": "text",
            "content_attributes": {},
            "sender_type": "contact",
            "sender_id": 123,
            "external_source_ids": {},
            "additional_attributes": {},
            "processed_message_content": "<string>",
            "sentiment": {},
            "conversation": {},
            "attachment": {},
            "sender": {}
          }
        ],
        "account_id": 123,
        "uuid": "<string>",
        "additional_attributes": {},
        "agent_last_seen_at": 123,
        "assignee_last_seen_at": 123,
        "can_reply": true,
        "contact_last_seen_at": 123,
        "custom_attributes": {},
        "inbox_id": 123,
        "labels": [
          "<string>"
        ],
        "muted": true,
        "snoozed_until": 123,
        "status": "open",
        "created_at": 123,
        "updated_at": 123,
        "timestamp": "<string>",
        "first_reply_created_at": 123,
        "unread_count": 123,
        "last_non_activity_message": {
          "id": 123,
          "content": "<string>",
          "account_id": 123,
          "inbox_id": 123,
          "conversation_id": 123,
          "message_type": 0,
          "created_at": 123,
          "updated_at": 123,
          "private": true,
          "status": "sent",
          "source_id": "<string>",
          "content_type": "text",
          "content_attributes": {},
          "sender_type": "contact",
          "sender_id": 123,
          "external_source_ids": {},
          "additional_attributes": {},
          "processed_message_content": "<string>",
          "sentiment": {},
          "conversation": {},
          "attachment": {},
          "sender": {}
        },
        "last_activity_at": 123,
        "priority": "<string>",
        "waiting_since": 123,
        "sla_policy_id": 123,
        "applied_sla": {},
        "sla_events": [
          {}
        ],
        "meta": {
          "sender": {
            "additional_attributes": {},
            "availability_status": "<string>",
            "email": "<string>",
            "id": 123,
            "name": "<string>",
            "phone_number": "<string>",
            "blocked": true,
            "identifier": "<string>",
            "thumbnail": "<string>",
            "custom_attributes": {},
            "last_activity_at": 123,
            "created_at": 123
          },
          "channel": "<string>",
          "assignee": {
            "id": 123,
            "access_token": "<string>",
            "account_id": 123,
            "available_name": "<string>",
            "avatar_url": "<string>",
            "confirmed": true,
            "display_name": "<string>",
            "message_signature": "<string>",
            "email": "<string>",
            "hmac_identifier": "<string>",
            "inviter_id": 123,
            "name": "<string>",
            "provider": "<string>",
            "pubsub_token": "<string>",
            "role": "agent",
            "ui_settings": {},
            "uid": "<string>",
            "type": "<string>",
            "custom_attributes": {},
            "accounts": [
              {
                "id": 123,
                "name": "<string>",
                "status": "<string>",
                "active_at": "2023-11-07T05:31:56Z",
                "role": "administrator",
                "permissions": [
                  "<string>"
                ],
                "availability": "<string>",
                "availability_status": "<string>",
                "auto_offline": true,
                "custom_role_id": 123,
                "custom_role": {}
              }
            ]
          },
          "hmac_verified": true
        }
      }
    ]
  }
}

Getting Started

Application APIs

Platform APIs

Client APIs

Other APIs

Authorizations

Path Parameters

Query Parameters

Response