Master Guide — How to Access and Operate CloudChat Data via API

This guide exists to answer a single question:

👉 “Which CloudChat API should I use for what I want to do?”

Before copying any endpoint or writing code, read this page. It prevents confusion, incorrect API usage, and unintended impacts in production.

🧠 Overview: there are 3 types of APIs in CloudChat

CloudChat APIs are not all the same.
They are divided into three categories, each with a clear purpose.

📦 Data Extraction APIs

Used for historical analysis and reports.

• Batch export (batch)

• Typical use: BI, auditing, dashboards

• Do not modify data

• Ideal for scheduled jobs

🔍 Real-Time Query APIs

Used to read current data from the system.

• Search contacts

• List tickets

• Read messages

• Do not modify data

• Used in real-time integrations and automations

✏️ Update and Action APIs

⚠️ These APIs modify real data in production.

• Resolve tickets

• Change status, priority, or team

• Create messages in tickets

• Can impact operations, SLA, and metrics

• Some routes are experimental or require an active flag

📦 When to use Data Extraction APIs

Use extraction APIs when you want to:

• Create reports

• Feed BI tools

• Conduct audits

• Analyze large periods of time

• Export many tickets at once

These APIs:

• Work in batches

• Have interval limits per request

• Should not be used for real-time application logic

👉 Specific documentation:
📦 Data Extraction API (Data Extract API)

🔍 When to use Real-Time Query APIs

Use query APIs when you need to answer questions now, such as:

• “Does this contact already exist?”

• “What tickets does this customer have?”

• “What is the current status of this ticket?”

• “What messages have been exchanged in this conversation?”

These APIs:

• Are read-only (GET)

• Operate directly on the production database

• Do not replace the extraction API

👉 Specific documentation:
🔍 Real-Time Query APIs (Contacts, Tickets, and Messages)

✏️ When to use Update and Action APIs

⚠️ Attention: these APIs modify real data in CloudChat.

Use action APIs when you want to:

• Resolve a ticket via integration

• Update priority or responsible team

• Automatically create messages

• Synchronize actions from another system with CloudChat

These APIs:

• Execute actions in production

• Can affect operation and metrics

• Should be used carefully and validated

👉 Specific documentation:
✏️ Update and Action APIs in Tickets

🧩 Practical rule for choosing the right API

Always ask:

• Do I want to analyze historical data?
  → Use Data Extraction API

• Do I just want to read current data?
  → Use Real-Time Query APIs

• Do I want to change something in the system?
  → Use Update and Action APIs

If still unsure, do not proceed. Using the wrong API can cause unexpected side effects.

🚦 Levels of caution (important)

• Data extraction → low risk

• Real-time query → medium risk

• Update / action → high risk

The closer you get to write actions, the more attention and testing are necessary.

❌ Common mistakes this guide helps to avoid

• Using extraction API for something that requires real-time

• Using write API thinking it is just a query

• Mixing application logic with data export

• Changing tickets without understanding operational impact

📌 Next steps

Now choose the right documentation for your case:

• 📦 Data Extraction API (Data Extract API)

• 🔍 Real-Time Query APIs (Contacts, Tickets, and Messages)

• ✏️ Update and Action APIs in Tickets

This guide should always be read before the above technical FAQs.