How to query contacts, tickets, and messages in real time via API

When to use

• You want to read current data from Cloud Chat without changing anything (look up a contact, view a customer's tickets, read the messages of a conversation)

• You are integrating Cloud Chat with another system (CRM, internal portal) that needs to display live data

• You want to avoid duplicate contacts before creating a ticket

Prerequisites

• Administrator API Key — see How to find your API Key in Cloud Chat

• CLOUDCHAT_DOMAIN and ACCOUNT_ID

About this article

The Real-Time Query APIs let you read current data from Cloud Chat, straight from the production database, without changing anything. They are ideal for integrations, automations, and internal screens that need to answer questions like:

• "Does this contact already exist?"

• "Which tickets does this customer have?"

• "What is the current status of this ticket?"

• "Which messages were exchanged in this conversation?"

About the /api/client/ namespace

What these APIs are for

Use them when you need to:

• Read data right now

• Integrate Cloud Chat data with another system

• Display information in an application

• Make decisions based on the current state of the service

What they are not for

Authentication

All endpoints require:

• {CLOUDCHAT_DOMAIN} — your account's domain (e.g. cloudchat.cloudhumans.com)

• {ACCOUNT_ID} — account ID

• api_access_token — for the /api/client/ endpoints (sections 1, 2, and 3), the token must belong to an administrator — supervisor or agent tokens receive 403 Forbidden. The free-text search (section 1b, /api/v1/ namespace) accepts a token from any agent profile

1. Find a contact by email or phone

When to use

• Before creating a ticket (to find out whether the contact already exists)

• To associate external data with a contact

• To avoid duplication

Endpoint

GET https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/contacts?email=EMAIL&phone_number=PHONE

Rules

• At least one of the parameters (email or phone_number) is required

• If both are sent, the API attempts the most precise match possible

What it returns

• Contact ID, name, email, phone

• Custom fields

• Creation and last activity dates

1b. Search contacts by free text (Search)

When to use

To find a contact by any text field (name, email, phone, identifier, company) without knowing exactly which one holds the information.

Unlike the previous endpoint, this one performs an ILIKE search (case-insensitive, partial) across multiple fields simultaneously.

Endpoint

GET /api/v1/accounts/{account_id}/contacts/search?q={termo}

Parameters

Searched fields

• name — contact name (always searched)

• email — email (from 3 characters with a digit)

• identifier — external identifier (from 3 characters with a digit)

• phone_number — phone, with and without the + prefix (from 3 characters with a digit)

• company_name — company name (from 3 characters with a digit)

Response

• payload[] — array of matching contacts

• meta — contains only the current page

Example

GET /api/v1/accounts/1/contacts/search?q=maria&page=1

Returns every contact whose name, email, phone, identifier, or company contains maria.

Usage limit (rate limit)

Difference between the two search endpoints

2. List a contact's tickets

When to use

You already have the CONTACT_ID and want to list that customer's tickets:

• Show the service history

• View open or resolved tickets

• Integrate with a CRM or internal portal

Endpoint

GET https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}/conversations?page=1&limit=10

Parameters

• page — required

• limit — optional (default: 10)

What it returns

• Ticket IDs

• Status (open, resolved, etc.)

• Priority

• Inbox

• Creation dates

• Whether it was started by a campaign

3. List a ticket's messages

When to use

To retrieve the message history of a ticket:

• Real-time auditing

• Display the conversation in another interface

• Debug integrations

Endpoint

GET https://{CLOUDCHAT_DOMAIN}/api/client/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID}/messages?page=1&limit=10

What it returns

• Message content

• Type (incoming / outgoing)

• Public or private

• Creation date

• Message status

• Attachment links (if any)

How these APIs connect (typical flow)

1. Find the contact by email or phone

2. Get the CONTACT_ID

3. List that contact's tickets

4. Pick a ticket

5. List the ticket's messages

Risk level

Medium risk — they do not change data, but they query the production database in real time.

Common mistakes

Conversation tags (labels) and how to find the contact_id

Tags applied to a conversation have their own endpoint (in Chatwoot, the base of Cloud Chat, they are called labels):

GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID}/labels

To find the contact_id from the CONVERSATION_ID you don't need a separate endpoint — the conversation details already return it:

GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/conversations/{CONVERSATION_ID}

In the response, meta.sender.id is the contact_id of the contact who owns the conversation. The same meta.sender object includes the name, email, phone, and other identifiers.

Both endpoints require an api_access_token from a user with the appropriate permission.

Notes

• To change status, priority, or team: How to update and act on tickets via API

• For reports and BI (historical extraction): How to extract data in bulk via API

• Overview of the available APIs: Master Guide — How to access and operate Cloud Chat data via API