{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"3c72728f-769f-430d-bd6f-3e3536a5e78d","name":"HueChat API","description":"# HueChat API\n\nWelcome 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.\n\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.\n\n---\n\n# Installation\n\nClick 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.\n\nYou 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.\n\n---\n\n# Base URL\n\nThe API is accessed using the following base URL:\n\n**`https://app.huechat.ai`**\n\nAll 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}/`.\n\nAll 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.\n\n---\n\n# Schema\n\nAll 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.\n\n### Single Resources\n\nIndividual resources are returned as a JSON object representing the resource directly, for example:\n\n``` json\n{\n  \"id\": 42,\n  \"name\": \"Sarah Ahmed\",\n  \"email\": \"sarah@example.com\",\n  \"created_at\": 1712400000\n}\n\n ```\n\n### Collections\n\nCollections of resources are returned as an object with a `data` or `payload` array and a `meta` object describing pagination:\n\n``` json\n{\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\n ```\n\n### Timestamps\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.\n\n### Identifiers\n\n- **Integer IDs** are used for conversations (`display_id`), contacts, messages, inboxes, agents, teams, and webhooks.\n    \n- **UUID strings** are used for newer resources: broadcasts, templates, contact lists, tickets, deals, and outbound webhook subscriptions.\n    \n\n---\n\n# Environment\n\nThis collection includes a pre-configured environment with the following variables. You must set `api_token` and `account_id` before making any requests.\n\n| Name | Description |\n| --- | --- |\n| `base_url` | The API base URL. Defaults to `https://app.huechat.ai` — do not change unless instructed. |\n| `api_token` | Your HueChat API key. Found under **Settings → API Keys** in the dashboard. |\n| `account_id` | The numeric ID of your HueChat account. Shown in the dashboard URL. |\n\n### Getting your API Token\n\n1. Sign in to [app.huechat.ai](https://app.huechat.ai)\n    \n2. Open **Settings → API Keys**\n    \n3. Click **Create API Key**, give it a name and scope (e.g. `conversations:write`, `messages:write`)\n    \n4. Copy the `hc_live_...` token — this is the only time the full token will be shown\n    \n5. Paste it into the `api_token` environment variable in Postman\n    \n\n---\n\n# Guidance\n\nTo ensure the best experience with the HueChat API, please observe the following guidelines:\n\n- **Use 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.\n    \n- **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.\n    \n- **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.\n    \n- **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.\n    \n- **Keep 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.\n    \n- **Rotate keys periodically.** If you suspect a key has been compromised, revoke it immediately from the dashboard and generate a new one.\n    \n\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.\n\n---\n\n# Authentication\n\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`.\n\n```\napi_access_token: hc_live_your_token_here\n\n ```\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.\n\n### Scoped API Keys\n\nHueChat 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.\n\n### IP Allowlisting\n\nAPI 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.\n\n### Key Expiration\n\nAPI keys can be configured to expire at a specific timestamp. Expired keys return `401 Unauthorized` and must be rotated before they stop working.\n\n**Remember: keep your API key secret. Treat it like a password.**\n\n---\n\n# Rate Limits\n\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.\n\nEvery response includes rate limit headers so your client can track usage and back off gracefully:\n\n| Header | Description |\n| --- | --- |\n| `X-RateLimit-Limit` | Maximum number of requests allowed in the current 60-second window |\n| `X-RateLimit-Remaining` | Number of requests remaining in the current window |\n| `X-RateLimit-Reset` | Unix timestamp when the current rate-limit window resets |\n\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.\n\n---\n\n# Errors\n\nHueChat 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\n### Common error response body\n\n``` json\n{\n  \"error\": \"Descriptive error message for developers\",\n  \"code\": \"invalid_parameter\",\n  \"status\": 400\n}\n\n ```\n\n### Standard status codes\n\n| Status | Meaning |\n| --- | --- |\n| `200` | OK — the request succeeded |\n| `201` | Created — a new resource was created |\n| `204` | No Content — the request succeeded and there's nothing to return |\n| `400` | Bad Request — the request body or query parameters are malformed |\n| `401` | Unauthorized — the API key is missing, invalid, expired, or blocked by IP allowlist |\n| `403` | Forbidden — the API key is valid but lacks the required scope for this endpoint |\n| `404` | Not Found — the requested resource does not exist or you don't have access to it |\n| `409` | Conflict — the request conflicts with the current state (e.g. sending an already-sent broadcast) |\n| `422` | Unprocessable Entity — validation failed (e.g. invalid email format) |\n| `429` | Too Many Requests — rate limit exceeded, retry after `X-RateLimit-Reset` |\n| `500` | Internal Server Error — something went wrong on our side, please retry |\n| `502` | Bad Gateway — an upstream service (e.g. WhatsApp) is unreachable |\n| `503` | Service Unavailable — the service is temporarily overloaded or down for maintenance |\n\n---\n\n# Support\n\n- **Dashboard**: [app.huechat.ai](https://app.huechat.ai)\n    \n- **Developer portal**: [app.huechat.ai/developers](https://app.huechat.ai/developers)\n    \n- **Status page**: [status.huechat.ai](https://status.huechat.ai)\n    \n- **Support email**: [support@huechat.ai](https://mailto:support@huechat.ai)\n    \n\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.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":true,"owner":"12967924","team":14818946,"collectionId":"3c72728f-769f-430d-bd6f-3e3536a5e78d","publishedId":"2sBXqNkdjQ","public":true,"publicUrl":"https://developers.huechat.ai","privateUrl":"https://go.postman.co/documentation/12967924-3c72728f-769f-430d-bd6f-3e3536a5e78d","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/d282ed75-1e63-46b7-a831-2d9ffd1ba0de/bG9nb19kYXJrLnBuZw==","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":"https://content.pstmn.io/e63ae364-32ef-4940-b228-15e3a60174a6/bG9nby5wbmc=","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2026-05-08T16:20:21.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/e63ae364-32ef-4940-b228-15e3a60174a6/bG9nby5wbmc=","logoDark":"https://content.pstmn.io/d282ed75-1e63-46b7-a831-2d9ffd1ba0de/bG9nb19kYXJrLnBuZw=="}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/f63623f367ce793ec3ac6b1f9b1668fc0598b92f0e82d2b3ea5f0c4401629dd9","favicon":"https://huechat.ai/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://developers.huechat.ai/view/metadata/2sBXqNkdjQ"}