{"openapi":"3.1.0","info":{"title":"Freshchat (BYOK) API","version":"0.1.0","description":"Freshchat (BYOK) lets an AI assistant read your own Freshchat data through the Freshchat API with a key you supply (Freshchat API token (Admin > Configure > API Tokens)). Read-only: 9 tools (get_account_configuration, list_agents, list_groups, list_channels, list_roles, search_users, list_user_conversations, get_conversation, list_conversation_messages). The BYOK key travels with each request, is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-freshchat.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-freshchat/docs"},"termsOfService":"https://connectorbay.com/byok-freshchat/terms"},"servers":[{"url":"https://byok-freshchat.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-freshchat/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_account_configuration":{"post":{"operationId":"get_account_configuration","summary":"Get the Freshchat account configuration: domain, plan type, data center and app id. Use for \"Which Freshchat plan and da","description":"Get the Freshchat account configuration: domain, plan type, data center and app id. Use for \"Which Freshchat plan and data center is my account on\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Freshchat account name, the part before .freshchat.com (for example 'acme' for acme.freshchat.com). Chat accounts built into Freshsales Suite (myfreshworks.com) are not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"}},"required":["account"],"title":"get_account_configurationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_agents":{"post":{"operationId":"list_agents","summary":"List Freshchat agents with name, email, role, groups, availability and whether they are deactivated. Use for \"Which Fres","description":"List Freshchat agents with name, email, role, groups, availability and whether they are deactivated. Use for \"Which Freshchat agents are available right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Freshchat account name, the part before .freshchat.com (for example 'acme' for acme.freshchat.com). Chat accounts built into Freshsales Suite (myfreshworks.com) are not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"availability_status":{"anyOf":[{"enum":["AVAILABLE","UNAVAILABLE"],"type":"string"},{"type":"null"}],"default":null,"description":"Only agents with this status.","title":"Availability Status"},"is_deactivated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only deactivated agents, false for only active ones.","title":"Is Deactivated"},"groups":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only agents that belong to this group id.","title":"Groups"},"items_per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (the default is 10).","title":"Items Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction.","title":"Sort Order"},"sort_by":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Field to sort by, for example name.","title":"Sort By"}},"required":["account"],"title":"list_agentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_groups":{"post":{"operationId":"list_groups","summary":"List Freshchat groups with name, description and routing type. Use for \"Which groups does my Freshchat have\".","description":"List Freshchat groups with name, description and routing type. Use for \"Which groups does my Freshchat have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Freshchat account name, the part before .freshchat.com (for example 'acme' for acme.freshchat.com). Chat accounts built into Freshsales Suite (myfreshworks.com) are not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"items_per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (the default is 10).","title":"Items Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction.","title":"Sort Order"},"sort_by":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Field to sort by, for example name.","title":"Sort By"}},"required":["account"],"title":"list_groupsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_channels":{"post":{"operationId":"list_channels","summary":"List Freshchat channels (topics) with name, enabled and public flags and tags. Use for \"Which Freshchat channels are ena","description":"List Freshchat channels (topics) with name, enabled and public flags and tags. Use for \"Which Freshchat channels are enabled\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Freshchat account name, the part before .freshchat.com (for example 'acme' for acme.freshchat.com). Chat accounts built into Freshsales Suite (myfreshworks.com) are not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"locale":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Language code to list channels for, for example en.","title":"Locale"},"items_per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (the default is 10).","title":"Items Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction.","title":"Sort Order"},"sort_by":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Field to sort by, for example name.","title":"Sort By"}},"required":["account"],"title":"list_channelsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_roles":{"post":{"operationId":"list_roles","summary":"List Freshchat agent roles with name and whether the role is custom. Use for \"What roles exist in Freshchat\".","description":"List Freshchat agent roles with name and whether the role is custom. Use for \"What roles exist in Freshchat\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Freshchat account name, the part before .freshchat.com (for example 'acme' for acme.freshchat.com). Chat accounts built into Freshsales Suite (myfreshworks.com) are not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"items_per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (the default is 10).","title":"Items Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction.","title":"Sort Order"},"sort_by":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Field to sort by, for example name.","title":"Sort By"}},"required":["account"],"title":"list_rolesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_users":{"post":{"operationId":"search_users","summary":"Find Freshchat customers (end users) by first name, last name, email, reference id or phone number. At least one search ","description":"Find Freshchat customers (end users) by first name, last name, email, reference id or phone number. At least one search field is required. Use for \"Find the Freshchat customer with email jane@example.com\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Freshchat account name, the part before .freshchat.com (for example 'acme' for acme.freshchat.com). Chat accounts built into Freshsales Suite (myfreshworks.com) are not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Exact email to match.","title":"Email"},"first_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"First name to match.","title":"First Name"},"last_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Last name to match.","title":"Last Name"},"reference_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Your own reference id for the customer.","title":"Reference Id"},"phone_no":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Phone number to match.","title":"Phone No"},"items_per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (the default is 10).","title":"Items Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction.","title":"Sort Order"}},"required":["account"],"title":"search_usersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_user_conversations":{"post":{"operationId":"list_user_conversations","summary":"List the ids of all Freshchat conversations of one customer. Use for \"Which Freshchat conversations does this customer h","description":"List the ids of all Freshchat conversations of one customer. Use for \"Which Freshchat conversations does this customer have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Freshchat account name, the part before .freshchat.com (for example 'acme' for acme.freshchat.com). Chat accounts built into Freshsales Suite (myfreshworks.com) are not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"user_id":{"description":"Freshchat user id (from search_users).","maxLength":200,"title":"User Id","type":"string"}},"required":["account","user_id"],"title":"list_user_conversationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_conversation":{"post":{"operationId":"get_conversation","summary":"Get one Freshchat conversation: status, channel, assigned agent and group. Use for \"Who is assigned to this Freshchat co","description":"Get one Freshchat conversation: status, channel, assigned agent and group. Use for \"Who is assigned to this Freshchat conversation\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Freshchat account name, the part before .freshchat.com (for example 'acme' for acme.freshchat.com). Chat accounts built into Freshsales Suite (myfreshworks.com) are not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"conversation_id":{"description":"Freshchat conversation id.","maxLength":200,"title":"Conversation Id","type":"string"}},"required":["account","conversation_id"],"title":"get_conversationArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_conversation_messages":{"post":{"operationId":"list_conversation_messages","summary":"List the messages of one Freshchat conversation with type, sender, time and message parts (text, images, files). Use for","description":"List the messages of one Freshchat conversation with type, sender, time and message parts (text, images, files). Use for \"What was said in this Freshchat conversation\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account":{"description":"Your Freshchat account name, the part before .freshchat.com (for example 'acme' for acme.freshchat.com). Chat accounts built into Freshsales Suite (myfreshworks.com) are not supported.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Account","type":"string"},"conversation_id":{"description":"Freshchat conversation id.","maxLength":200,"title":"Conversation Id","type":"string"},"from_time":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only messages created at or after this UTC date-time, for example 2026-01-01T10:00:00.000Z.","title":"From Time"},"items_per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many messages per page (at most 50, default 20).","title":"Items Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["account","conversation_id"],"title":"list_conversation_messagesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}