Famysync
Skip to article

API & Agents overview

Search Famysync documentation

Search the full guides for topics such as renewal, ticket alerts, OAuth or knowledge refresh.

Access bots, knowledge, chat, conversations, leads, analytics and bookings through a scoped REST API or hosted MCP server. Available with live Growth or higher API access.

On this page

Offering bots to customers from an enterprise application? See the separate API Vendor guide for customer authorization and sponsored bots.

Authentication

Create a token in Dashboard → API & Agents. Tokens are scoped, can be limited to specific bots, and can expire. The token secret is shown once. Only workspace owners and admins can manage tokens or approve MCP OAuth access. Pass a token as a bearer header:

curl https://api-uat.famysync.com/v1/bots \
  -H "Authorization: Bearer mgpt_your_token_here"

Keep tokens on your server. Browsers cannot call the token endpoints (they send no CORS headers), so a token in a web page does not work. To call a bot from your own web page, use its public key (see below).

REST and MCP access requires API access on an active paid Growth or higher plan, or an active Growth trial. Enterprise contracts must include API access. Tokens and OAuth connections stop working while the workspace is not live; restoring access does not require replacing the token.

Endpoints

MethodPathScopeDescription
GET/v1/botsbots:readList bots
POST/v1/botsbots:writeCreate a bot (plan-limited)
GET/v1/bots/{id}/settingsbots:readInstructions, persona, fallback message and language settings
PATCH/v1/bots/{id}/instructionssettings:writeReplace instructions, persona and/or fallback message (returns the previous text)
GET/v1/kb?chatbotId=…kb:readList knowledge-base documents (limit/offset, status, type, q)
POST/v1/kb/ingestkb:writeAdd knowledge from a URL or raw text (queued)
DELETE/v1/kb/{id}kb:writeDelete a knowledge-base document
GET/v1/custom-answerskb:readList custom answers
POST/v1/custom-answerskb:writeAdd a custom answer (queued)
PATCH/v1/custom-answers/{id}kb:writeChange a custom answer
DELETE/v1/custom-answers/{id}kb:writeDelete a custom answer
POST/v1/chatchat:invokeChat with a bot — SSE stream or one JSON reply, counts toward quota
POST/v1/public/chatpublic keyChat from your own web page with a public key (mpk_…)
GET/v1/conversationsconversations:readList conversations (?q= search, ?channel=)
GET/v1/conversations/{sessionId}conversations:readFull transcript of one session
GET/v1/leadsleads:readList intent-scored leads (?chatbotId= filter)
GET/v1/analyticsanalytics:read30-day analytics summary
GET/v1/bookingsbookings:readList appointment requests (?status= pending|confirmed|rejected|cancelled)
GET/v1/bookings/{id}bookings:readOne booking — visitor, slot, status
PATCH/v1/bookings/{id}bookings:writeConfirm, reject, reschedule, or cancel — emails the visitor
GET/v1/openapi.json—This API as an OpenAPI 3.1 spec (no auth)

Full schemas: openapi.json

A token restricted to specific bots must pass an allowed chatbotId for knowledge, chat, leads and analytics requests. Bot-restricted tokens cannot create bots. Enterprise bot creation requires enterprise_plan_tier (starter, growth or scale) and an available slot of that tier. Knowledge ingestion checks the bot's page quota before queuing.

Chat

POST /v1/chat returns Server-Sent Events: the reply text as OpenAI-style chunks, then an event: done with sessionId, sources (pages the reply is based on), suggestions (follow-up questions) and actions (handoff, askContact, offerBooking), then data: [DONE]. Pass "stream": false to get the same as one JSON object with answer.

Every message is saved as a conversation (channel api) and counts toward your quota. Without sessionId a new conversation starts; its id comes back in the X-Session-Id header and the done event. Pass it back to continue.

curl https://api-uat.famysync.com/v1/chat \
  -H "Authorization: Bearer mgpt_…" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is your refund policy?","chatbotId":"…","sessionId":"user-42","language":"ja-JP","stream":false}'

# → {"data":{"sessionId":"user-42","answer":"…","sources":["https://…"],"suggestions":["…"],"handoff":false,"askContact":false,"offerBooking":false}}

Chat from your own web page

Create a public key (mpk_…) for a bot in Dashboard → API & Agents. It can only chat with that bot — it cannot read conversations, leads or settings — and works only from the bot's allowed domains, which must be switched on. Send it in the X-Famysync-Key header to POST /v1/public/chat; the request and reply are the same as /v1/chat without chatbotId. It is rate limited per key and per visitor, and messages count toward your quota.

const res = await fetch('https://api-uat.famysync.com/v1/public/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Famysync-Key': 'mpk_…' },
  body: JSON.stringify({ message: 'Hello', sessionId, stream: false }),
})
const { data } = await res.json()   // data.answer, data.sources, data.suggestions

Bookings

List appointment requests and confirm, reject, reschedule, or cancel them. Confirming emails the visitor and blocks that slot. Reschedule needs requestedSlot (ISO-8601 with offset) and emails the new time. Cancel emails the visitor. Same behaviour as the Bookings page. Scopes: bookings:read / bookings:write.

curl https://api-uat.famysync.com/v1/bookings?status=pending \
  -H "Authorization: Bearer mgpt_…"

curl https://api-uat.famysync.com/v1/bookings/BOOKING_ID \
  -X PATCH \
  -H "Authorization: Bearer mgpt_…" \
  -H "Content-Type: application/json" \
  -d '{"action":"confirm"}'

curl https://api-uat.famysync.com/v1/bookings/BOOKING_ID \
  -X PATCH \
  -H "Authorization: Bearer mgpt_…" \
  -H "Content-Type: application/json" \
  -d '{"action":"reschedule","requestedSlot":"2026-08-20T15:00:00+05:30"}'

curl https://api-uat.famysync.com/v1/bookings/BOOKING_ID \
  -X PATCH \
  -H "Authorization: Bearer mgpt_…" \
  -H "Content-Type: application/json" \
  -d '{"action":"cancel","cancelComment":"We need to close that day."}'

MCP server (for AI agents)

Famysync hosts a remote MCP server, so Claude and other MCP-capable agents can list bots, add and delete knowledge, manage custom answers, change a bot's instructions, ask questions, read conversations, leads & analytics, and list / confirm / reject / reschedule / cancel bookings. Connect through user-approved OAuth or a scoped API token; one connection covers one workspace. Tools: list_bots, list_knowledge, add_knowledge, delete_knowledge, list_custom_answers, add_custom_answer, update_custom_answer, delete_custom_answer, get_bot_settings, update_instructions, ask_bot, list_conversations, get_conversation, list_leads, get_analytics, list_bookings, get_booking, update_booking.

{
  "mcpServers": {
    "Famysync": {
      "url": "https://api-uat.famysync.com/mcp",
      "headers": { "Authorization": "Bearer mgpt_…" }
    }
  }
}

Get an API key in 2 minutes

Start the free trial, open Dashboard → API & Agents, create a token.

Start free trial

Related guides

Something unclear? Tell us.

Start free trial