Welcome to the official HueChat REST API. HueChat is a customer messaging and engagement platform that unifies WhatsApp, email, web chat, and AI-powered support into a single inbox. This API gives your applications full programmatic access to every public-facing resource in your account — conversations, contacts, messages, broadcasts, templates, webhooks, contact lists, tickets, and deals.
\nVersion 1 of the HueChat API is structured around REST, HTTP, and JSON. Endpoint URLs are organized around resources such as conversations or contacts. The API uses HTTP methods to indicate the action to take on a resource and HTTP status codes to express error states. All responses are returned as JSON.
Click the Run in Postman button at the top-right corner of this documentation to import the entire collection into your local Postman workspace. Once imported, fill in the api_token and account_id variables in the pre-configured environment, and every request in this collection will automatically authenticate against your HueChat account.
You can also download any request as a code snippet (cURL, Python, JavaScript, Go, PHP, Ruby) directly from Postman by clicking the Code button on the top-right of any request panel.
\nThe API is accessed using the following base URL:
\nhttps://app.huechat.ai
All v1 endpoint paths begin with /api/v1/accounts/{account_id}/. A smaller set of newer resources (Broadcasts, Templates, Contact Lists, Tickets, Deals, Outbound Webhooks, AI Agents) lives under /api/v2/accounts/{account_id}/.
All API requests must be made over HTTPS. Plain HTTP requests will be rejected with a 426 Upgrade Required response. Connections must support TLS 1.2 or higher.
All API requests and response bodies adhere to a common JSON format representing individual items, collections of items, links to related items, and additional meta data.
\nIndividual resources are returned as a JSON object representing the resource directly, for example:
\n{\n \"id\": 42,\n \"name\": \"Sarah Ahmed\",\n \"email\": \"sarah@example.com\",\n \"created_at\": 1712400000\n}\n\nCollections of resources are returned as an object with a data or payload array and a meta object describing pagination:
{\n \"data\": {\n \"meta\": {\n \"mine_count\": 12,\n \"unassigned_count\": 5,\n \"all_count\": 45\n },\n \"payload\": [\n { \"id\": 1, \"...\": \"...\" },\n { \"id\": 2, \"...\": \"...\" }\n ]\n }\n}\n\nAll timestamps are returned as Unix epoch seconds (integers) unless explicitly stated otherwise. Broadcast, template, and webhook resources use ISO 8601 date-time strings for historical reasons.
\nInteger IDs are used for conversations (display_id), contacts, messages, inboxes, agents, teams, and webhooks.
UUID strings are used for newer resources: broadcasts, templates, contact lists, tickets, deals, and outbound webhook subscriptions.
\nThis collection includes a pre-configured environment with the following variables. You must set api_token and account_id before making any requests.
Sign in to app.huechat.ai
\nOpen Settings → API Keys
\nClick Create API Key, give it a name and scope (e.g. conversations:write, messages:write)
Copy the hc_live_... token — this is the only time the full token will be shown
Paste it into the api_token environment variable in Postman
To ensure the best experience with the HueChat API, please observe the following guidelines:
\nUse version 1 (v1) or version 2 (v2) APIs — never call internal, unversioned, or /platform/ endpoints. Those are reserved for HueChat internal use and are not part of the public API contract.
Respect rate limits. Every endpoint has a documented rate limit (see the per-endpoint description). If you receive a 429 Too Many Requests response, pause or sleep execution for at least 1,000 milliseconds before retrying. We recommend implementing exponential backoff for production integrations.
Always handle 5xx errors gracefully. Treat 500, 502, 503, and 504 responses as transient and retry with backoff. Do not retry 4xx responses without first correcting the request.
Use idempotency keys for critical write operations when available (e.g. creating a conversation). This prevents duplicate records if a request times out and is retried.
\nKeep your API keys secret. Never commit tokens to source control, log them, or expose them in client-side code. Use scoped API keys with the minimum permissions required for your integration.
\nRotate keys periodically. If you suspect a key has been compromised, revoke it immediately from the dashboard and generate a new one.
\nWe are actively working on improving the platform, adding new features, and optimizing performance. Following these guidelines helps us provide a reliable, secure, and performant experience for all customers.
\nAll requests to the HueChat API are authenticated by providing your API key. The API key must be provided as an HTTP header named api_access_token.
api_access_token: hc_live_your_token_here\n\nThis collection's pre-request script automatically sets this header for every request, reading the value from the api_token environment variable. You do not need to add the header manually.
HueChat supports scoped API keys with granular permissions. When creating a key, you can restrict it to specific operations such as conversations:read, messages:write, contacts:delete, and more. A request made with a scoped key that lacks the required scope will receive a 403 Forbidden response with a descriptive error body.
API keys can optionally be restricted to a list of allowed client IP addresses or CIDR ranges. Requests from IPs outside the allowlist will be rejected with 401 Unauthorized, even if the key itself is valid.
API keys can be configured to expire at a specific timestamp. Expired keys return 401 Unauthorized and must be rotated before they stop working.
Remember: keep your API key secret. Treat it like a password.
\nEvery API endpoint enforces a rate limit expressed as requests per minute. The exact limit depends on the endpoint and is documented in each request's description.
\nEvery response includes rate limit headers so your client can track usage and back off gracefully:
\nWhen the limit is exceeded, the API returns 429 Too Many Requests. Scoped API keys can be created with custom rate limits (1 to 100,000 RPM) to match your integration's traffic profile.
HueChat uses conventional HTTP status codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate a problem with the request (missing parameter, failed validation, insufficient scope, etc.). Codes in the 5xx range indicate an error with HueChat's servers.
{\n \"error\": \"Descriptive error message for developers\",\n \"code\": \"invalid_parameter\",\n \"status\": 400\n}\n\nDashboard: app.huechat.ai
\nDeveloper portal: app.huechat.ai/developers
\nStatus page: status.huechat.ai
\nSupport email: support@huechat.ai
\nFound a bug or have a feature request? Reach out via the dashboard chat widget or email support and we'll get back to you within one business day.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"HueChat API","slug":"huechat-api"},{"content":"Installation","slug":"installation"},{"content":"Base URL","slug":"base-url"},{"content":"Schema","slug":"schema"},{"content":"Environment","slug":"environment"},{"content":"Guidance","slug":"guidance"},{"content":"Authentication","slug":"authentication"},{"content":"Rate Limits","slug":"rate-limits"},{"content":"Errors","slug":"errors"},{"content":"Support","slug":"support"}],"owner":"12967924","collectionId":"3c72728f-769f-430d-bd6f-3e3536a5e78d","publishedId":"2sBXqNkdjQ","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-05-08T16:20:21.000Z"},"item":[{"name":"Contacts","item":[{"name":"List contacts","id":"369902f7-6eb4-4c52-939c-0ec63c8df539","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"api_access_token"},{"key":"value","value":"{{apiKey}}"}]},"isInherited":false},"method":"GET","header":[{"key":"Accept","value":"application/json"}],"url":"{{base_url}}/api/v1/accounts/:account_id/contacts?page=Returns a paginated list of contacts for your account. Contacts are returned in the order specified by the sort parameter, with newest first by default.
Rate Limit: 240/min
\nScopes required: contacts:read
Returns an object with meta (pagination info) and payload (array of contact objects).
Each contact object includes:
\nid — integer contact IDname, email, phone_number, identifier — basic profile fieldsblocked — whether the contact has been blockedthumbnail — URL to the contact's profile picture (or empty string)availability_status — online, offline, or busyadditional_attributes — system-collected metadata (browser info, IP location, etc.)custom_attributes — your account's custom attribute values for this contactcontact_inboxes — array of inboxes this contact is associated withlast_activity_at — Unix timestamp of the contact's last activitycreated_at — Unix timestamp of when the contact was createdPage number
\n","type":"text/plain"},"key":"page","value":"Sort field (name, email, phone_number, last_activity_at, company, city, country, created_at). Prefix with - for desc.
\n","type":"text/plain"},"key":"sort","value":"Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Search contacts by name, email, phone number, or identifier. The query is matched against all four fields using case-insensitive partial matching.
\nRate Limit: 240/min
\nScopes required: contacts:read
Same shape as List contacts — meta + payload[]. Results are ordered by relevance (best match first).
name, email, phone_number, and identifier fields.+, spaces, dashes) before matching.Get contact by phone endpoint when available.(Required) Search query
\n","type":"text/plain"},"key":"q","value":"Page number
\n","type":"text/plain"},"key":"page","value":"Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Contacts represent the end users, customers, or leads that your team engages with through HueChat. Each contact has a canonical phone number, optional email and name, custom attributes, and a history of conversations across all your connected inboxes.
\nBase path: /api/v1/accounts/{account_id}/contacts
Common use cases:
\nSync contacts from your CRM or customer database into HueChat so every conversation is attributed to the right person.
\nSearch for an existing contact by name, email, or phone number before creating a new conversation.
\nEnrich a contact with custom attributes (plan tier, last purchase date, lifetime value, account manager, etc.) so agents see relevant context inline.
\nBlock or unblock contacts that violate your terms of service.
\nRequired scopes: contacts:read for read operations, contacts:write for create/update/block, contacts:delete for deletion.
Returns a paginated list of conversations, optionally filtered by status, inbox, and assignee type. This is the main endpoint for building custom inbox views.
\nRate Limit: 240/min
\nScopes required: conversations:read
Returns an object with data.meta (counts per filter) and data.payload (array of conversation objects). The meta object includes:
mine_count — conversations assigned to the authenticated userunassigned_count — conversations with no assigneeassigned_count — conversations with any assigneeall_count — total conversations matching the filterEach conversation object includes the full conversation state plus an embedded meta object with the contact (sender), assignee, team, and channel.
Filter by status
\n","type":"text/plain"},"key":"status","value":"snoozed"},{"description":{"content":"Filter by inbox ID
\n","type":"text/plain"},"key":"inbox_id","value":"Filter by assignee type
\n","type":"text/plain"},"key":"assignee_type","value":"all"},{"description":{"content":"Page number
\n","type":"text/plain"},"key":"page","value":"Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Creates a new conversation in your account. Use this endpoint when you want to start a conversation programmatically rather than waiting for a customer to message you.
\nRate Limit: 60/min
\nScopes required: conversations:write
Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Returns conversations matching complex filter conditions. Supports multiple conditions combined with AND/OR operators across any field, including custom attributes.
\nRate Limit: 120/min
\nScopes required: conversations:read
status, assignee_id, inbox_id, team_id, label, priority, browser_language, country_code, referer, created_at, last_activity_at, plus any custom attribute key.
{\n \"payload\": [\n {\n \"attribute_key\": \"status\",\n \"filter_operator\": \"equal_to\",\n \"values\": [\"open\"],\n \"query_operator\": \"AND\"\n },\n {\n \"attribute_key\": \"priority\",\n \"filter_operator\": \"equal_to\",\n \"values\": [\"urgent\", \"high\"],\n \"query_operator\": null\n }\n ],\n \"page\": 1\n}\nThe last condition's query_operator should be null. All other conditions chain via the query_operator they declare.
Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Returns aggregate counts of conversations grouped by status. Useful for building dashboards, status indicators, or unread badges.
\nRate Limit: 240/min
\nScopes required: conversations:read
{\n \"meta\": {\n \"mine_count\": 12,\n \"unassigned_count\": 5,\n \"assigned_count\": 40,\n \"all_count\": 45\n }\n}\nOptionally filter by inbox_id or team_id to get counts scoped to a specific channel or team.
Filter by status
\n","type":"text/plain"},"key":"status","value":"open"},{"description":{"content":"Filter by inbox ID
\n","type":"text/plain"},"key":"inbox_id","value":"Filter by team ID
\n","type":"text/plain"},"key":"team_id","value":"Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Full-text search across conversation messages and contact details. Returns conversations where the query matches message content, contact name, contact email, or contact phone number.
\nRate Limit: 120/min
\nScopes required: conversations:read
Results are ordered by relevance.
\n","urlObject":{"path":["api","v1","accounts",":account_id","conversations","search"],"host":["{{base_url}}"],"query":[{"description":{"content":"(Required) Search query
\n","type":"text/plain"},"key":"q","value":"Page number
\n","type":"text/plain"},"key":"page","value":"Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Permanently deletes a conversation and all its messages, attachments, and metadata. This action cannot be undone.
\nRate Limit: 30/min
\nScopes required: conversations:delete
Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Conversation display ID (integer)
\n","type":"text/plain"},"type":"any","value":"Returns the full conversation object including metadata, labels, custom attributes, assignment info, and the most recent non-activity message.
\nRate Limit: 480/min
\nScopes required: conversations:read
Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Conversation display ID (integer)
\n","type":"text/plain"},"type":"any","value":"Updates conversation fields. Currently the only updatable field via this endpoint is priority. Use the dedicated endpoints below for status changes, assignments, labels, etc.
Rate Limit: 120/min
\nScopes required: conversations:write
{\n \"priority\": \"high\"\n}\nPriority values: low, medium, high, urgent, or null to remove the priority.
Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Conversation display ID (integer)
\n","type":"text/plain"},"type":"any","value":"Assigns the conversation to an agent and/or a team. Pass null for assignee_id or team_id to unassign.
Rate Limit: 120/min
\nScopes required: conversations:write
{\n \"assignee_id\": 5,\n \"team_id\": 2\n}\nBoth fields are optional but at least one must be provided.
\nReturns the new assignee object (or team object), or null if the conversation was unassigned.
Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Conversation display ID (integer)
\n","type":"text/plain"},"type":"any","value":"Returns all file attachments shared in a conversation, paginated. Each attachment includes the file URL, type, size, and the message ID it belongs to.
\nRate Limit: 120/min
\nScopes required: conversations:read
Page number
\n","type":"text/plain"},"key":"page","value":"Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Conversation display ID (integer)
\n","type":"text/plain"},"type":"any","value":"Sets or updates custom key-value attributes on a conversation. Custom attributes are freeform JSON — store any metadata your integration needs.
\nRate Limit: 120/min
\nScopes required: conversations:write
custom_attributes object is merged into the existing attributes (existing keys are preserved unless overwritten).null.Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Conversation display ID (integer)
\n","type":"text/plain"},"type":"any","value":"Returns the list of labels currently applied to a conversation.
\nRate Limit: 240/min
\nScopes required: conversations:read
Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Conversation display ID (integer)
\n","type":"text/plain"},"type":"any","value":"Replaces the conversation's labels with the provided list. To add a label, pass the existing labels plus the new one. To remove a label, omit it from the list. To clear all labels, pass an empty array.
\nRate Limit: 120/min
\nScopes required: conversations:write
{\n \"labels\": [\"support\", \"billing\", \"vip\"]\n}\nYour HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Conversation display ID (integer)
\n","type":"text/plain"},"type":"any","value":"Mutes notifications for this conversation. Muted conversations won't trigger browser, push, or email notifications for the agent who muted them.
\nRate Limit: 120/min
\nScopes required: conversations:write
Request body: None required.
\n","urlObject":{"path":["api","v1","accounts",":account_id","conversations",":conversation_id","mute"],"host":["{{base_url}}"],"query":[],"variable":[{"description":{"content":"Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Conversation display ID (integer)
\n","type":"text/plain"},"type":"any","value":"Returns the list of agents currently participating in (watching) this conversation. Participants receive in-app notifications for new messages even if they're not the assigned agent.
\nRate Limit: 240/min
\nScopes required: conversations:read
Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Conversation display ID (integer)
\n","type":"text/plain"},"type":"any","value":"Replaces the list of participants with the provided user IDs. Use this to add or remove agents who should receive notifications about a conversation.
\nRate Limit: 120/min
\nScopes required: conversations:write
{\n \"user_ids\": [5, 8, 12]\n}\nYour HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Conversation display ID (integer)
\n","type":"text/plain"},"type":"any","value":"Sets or changes the priority level of a conversation. Equivalent to using the Update a conversation endpoint with just the priority field, but returns a different response shape.
\nRate Limit: 120/min
\nScopes required: conversations:write
Priority values: low, medium, high, urgent
Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Conversation display ID (integer)
\n","type":"text/plain"},"type":"any","value":"Changes the conversation status. When setting to snoozed, you must also include snoozed_until with an ISO 8601 datetime.
Rate Limit: 120/min
\nScopes required: conversations:write
{\n \"status\": \"resolved\"\n}\nOr for snoozing:
\n{\n \"status\": \"snoozed\",\n \"snoozed_until\": \"2026-04-08T09:00:00Z\"\n}\nStatus values: open, resolved, pending, snoozed
This endpoint triggers the conversation.status_changed webhook event, which fires every time the status changes (including reopening a resolved conversation).
Your HueChat account ID (integer)
\n","type":"text/plain"},"type":"any","value":"Conversation display ID (integer)
\n","type":"text/plain"},"type":"any","value":"