A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Freshchat API is how an app or AI agent works with a Freshchat account: reading a conversation, sending a message to a customer, creating or updating a user, or pulling agents and groups. Access is granted through an API token generated in the admin settings, and that token carries the full account-level access of the admin who created it rather than per-method permissions. A state change like a new message or a conversation being assigned emits a signed event that Freshchat can deliver to a registered endpoint.
How an app or AI agent connects to Freshchat determines what it can reach. There is a route for making calls, governed by an API token generated in the admin settings, and a route for receiving events, where Freshchat posts a signed payload to a registered endpoint.
The REST API takes JSON request bodies, returns JSON, and pages through lists with page and items_per_page query parameters, under the v2 path at https://
Freshchat POSTs a JSON payload to an HTTPS endpoint registered in the admin settings when a message is created or a conversation is assigned, resolved, or reopened. The receiver verifies the X-Freshchat-Signature header against the public key from the webhook settings, using SHA256withRSA, to confirm the request came from Freshchat. An X-Freshchat-Payload-Version header names the payload shape.
An API token is generated by an admin in the admin settings and sent as a Bearer token on every request. It carries the full account-level access of the admin who created it, with no per-endpoint scoping, so any agent holding the token can call any method the account allows. The token has a defined lifetime, and an expired token returns a 401.
App-based integrations use an OAuth 2.0 flow that issues access tokens carrying granular scopes, like freshchat.conversation.create or freshchat.conversation.messages.view, so an app is limited to the areas it was granted. This contrasts with the admin-generated API token, which has no such per-scope limits.
The Freshchat API is split into areas an agent can act on, like conversations, messages, users, agents, groups, channels, and reports. Each area has its own methods, and writes in some areas send messages to customers or change who a conversation is assigned to.
Methods for creating conversations, updating their status and assignment, and reading or sending messages.
Methods for creating, reading, updating, and deleting the people who chat in.
Methods for listing, reading, creating, updating, and deleting support agents.
Methods for listing the groups agents belong to and the channels conversations route through.
Methods for extracting raw report data and sending or listing outbound messages.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Conversations & messagesMethods for creating conversations, updating their status and assignment, and reading or sending messages.5 | ||||||
| POST | /v2/conversations | Create a conversation, optionally with an initial message and assignment. | write | — | Current | |
The API token carries account-level access, so there is no per-method scope to narrow this. The matching OAuth scope (for app-based access) is freshchat.conversation.create. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/conversations/{conversation_id} | Retrieve a conversation by its id. | read | — | Current | |
Read-only. The API token has account-level access, so there is no per-method scope. OAuth scope: freshchat.conversation.view. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/conversations/{conversation_id} | Update a conversation's status, assignment, or properties. | write | — | Current | |
Reassigning or resolving here fires the conversation_assignment, conversation_resolution, or conversation_reopen webhook. OAuth scope: freshchat.conversation.edit. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook event conversation_assignmentRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/conversations/{conversation_id}/messages | List the messages in a conversation, paginated. | read | — | Current | |
Read-only. OAuth scope: freshchat.conversation.messages.view. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/conversations/{conversation_id}/messages | Send a message into a conversation as an agent or system actor. | write | — | Current | |
Delivers a message to the customer and fires the message_create webhook. OAuth scope: freshchat.conversation.message.create. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook event message_createRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Users (contacts)Methods for creating, reading, updating, and deleting the people who chat in.6 | ||||||
| POST | /v2/users | Create a user (a person who chats in). | write | — | Current | |
The API token carries account-level access, so there is no per-method scope to narrow this. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/users | List users matching the given criteria, paginated. | read | — | Current | |
Read-only. Returns user records, which include personal contact details. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/users/{user_id} | Retrieve a single user by id. | read | — | Current | |
Read-only. Returns the user's personal contact details. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/users/{user_id} | Update a user's information. | write | — | Current | |
The API token carries account-level access, so there is no per-method scope to narrow this. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/users/{user_id} | Permanently delete a user, for GDPR compliance. | write | — | Current | |
Irreversible. Removes the user record and is intended for data-erasure requests. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/users/{user_id}/conversations | List the conversations belonging to a user. | read | — | Current | |
Read-only. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AgentsMethods for listing, reading, creating, updating, and deleting support agents.6 | ||||||
| GET | /v2/agents | List all agents in the account. | read | — | Current | |
Read-only. Acts onagent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/agents | Create an agent. | write | — | Current | |
The API token carries account-level access, so there is no per-method scope to narrow this. Acts onagent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/agents/{agent_id} | Retrieve a single agent by id. | read | — | Current | |
Read-only. Acts onagent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/agents/{agent_id} | Update an agent's details or status. | write | — | Current | |
The API token carries account-level access, so there is no per-method scope to narrow this. Acts onagent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/agents/{agent_id} | Delete an agent from the account. | write | — | Current | |
Irreversible. Removes the agent account. Acts onagent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/agents/status | List the current status of agents (such as available or unavailable). | read | — | Current | |
Read-only. Acts onagent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Groups & channelsMethods for listing the groups agents belong to and the channels conversations route through.4 | ||||||
| GET | /v2/groups | List all groups agents are organised into. | read | — | Current | |
Read-only. Acts ongroup Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/channels | List all channels (topics) conversations route through. | read | — | Current | |
Read-only. Acts onchannel Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/roles | List the roles defined in the account. | read | — | Current | |
Read-only. Acts onrole Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/accounts/configuration | Retrieve the account's configuration. | read | — | Current | |
Read-only. OAuth scope: freshchat.account.view. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Reports & outboundMethods for extracting raw report data and sending or listing outbound messages.4 | ||||||
| POST | /reports/raw | Request a raw report export for a date range. | write | — | Current | |
Starts an export job; the result is fetched separately by its id. Exports account-level conversation data. Acts onreport Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /reports/raw/{id} | Retrieve a previously requested report export by its id. | read | — | Current | |
Read-only. Returns the export produced by the extract request. Acts onreport Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/outbound-messages/whatsapp | Send an outbound message (such as a WhatsApp template) to customers. | write | — | Current | |
Initiates a message to a customer outside an existing conversation. Acts onoutbound_message Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/outbound-messages | List outbound messages that have been sent. | read | — | Current | |
Read-only. Acts onoutbound_message Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Freshchat can notify an app when something happens in an account, like a message being created or a conversation being assigned, resolved, or reopened. It posts a signed payload naming the actor, the action, and the data that changed, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
message_create | A new message was created in a conversation, by a user, an agent, or the system. The payload names the actor and includes the message parts and whether it is normal or private. | /v2/conversations/{conversation_id}/messages |
conversation_assignment | A conversation was assigned to an agent or a group. | /v2/conversations/{conversation_id} |
conversation_resolution | A conversation was resolved or closed. | /v2/conversations/{conversation_id} |
conversation_reopen | A previously resolved conversation was reopened. | /v2/conversations/{conversation_id} |
Freshchat limits how fast an app can call, by a per-account quota that varies with the subscription plan. The ceiling and the remaining allowance are returned on every response, and going over returns an error.
Freshchat meters requests by a per-account quota rather than a per-method cost. The exact ceiling is not published and varies with the subscription plan. Every response returns the quota on three headers: X-RateLimit-Limit (the total permissible calls in the window), X-RateLimit-Remaining (how many are left), and X-RateLimitReset (when the window resets). Going over returns HTTP 429, at which point an integration backs off until the reset time.
List endpoints page with page (default 1) and items_per_page (default 10), and can order results with sort_by and sort_order (asc or desc, default asc). The response carries a pagination object with totals and a links object for moving between pages. The conversation messages endpoint defaults to 20 items per page and caps at 50.
A file upload is limited to 25 MB and is sent as multipart/form-data. The bulk user-fetch endpoint returns at most 100 users per request.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed or a parameter is invalid. The response body carries code, status, and a Freshchat-specific message describing the problem. | Read the message field, fix the request, and resend. The request is not retryable as-is. |
| 401 | Unauthenticated | No valid token was provided, or the token has expired. | Generate or refresh the API token in the admin settings and send it as a Bearer token. |
| 403 | Forbidden | The token is valid but not allowed to perform this action. | Confirm the account and the token's access cover the requested resource. |
| 404 | Not Found | The requested object does not exist or is not visible to this token. | Verify the id in the path and confirm it belongs to this account. |
| 429 | Too Many Requests | The per-account rate limit was exceeded. The X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimitReset headers describe the quota and when it resets. | Back off until the reset time and retry with exponential backoff, smoothing the request rate. |
| 500 | Internal Server Error | An error on Freshchat's side, which can also appear as 503 Service Unavailable. | Retry with backoff, and contact Freshchat support if it persists. |
Freshchat serves its REST API under a single major version in the path, and signs each webhook payload with a payload-version header so receivers can tell which shape they are parsing.
The Freshchat REST API is served under a single major version, v2, in the path, covering conversations, messages, users, agents, groups, channels, reports, and outbound messages. There is no dated per-request version string. Webhook payloads carry an X-Freshchat-Payload-Version header so receivers can tell which payload shape they are parsing.
Alongside the REST API, Freshchat ships a browser Web SDK with its own version line (v1 and v2), and mobile SDKs that continue to receive dated releases. These are separate from the REST API and are used to embed the chat widget rather than to call the API server-side.
The REST API is served under one major version; pin to it and watch the developer docs for additive changes.
Freshchat product updates ↗Bollard AI sits between a team's AI agents and Freshchat. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.