# CarlyChat

CarlyChat creates grounded support chatbots for websites.

MCP endpoint: https://carlychat.com/mcp
Transport: Streamable HTTP (JSON-RPC 2.0)

Authentication
- Account key: Authorization: Bearer ca_sk_...
  Creates and manages chatbots for an account.
- Bot key: Authorization: Bearer cc_sk_...
  Manages one existing chatbot.

Create a free account at https://carlychat.com/signup, then copy the account key
from Account. Never expose either key in browser code or a public repository.

Recommended agent workflow
1. Call create_bot with a name and optional websiteUrl.
2. Call configure_bot to set instructions, messages, visibility, domains, lead
   capture, brand color, and page or identified-customer targeting.
3. Call add_website_source with maxPages=100 to train on the whole public site,
   or add_text_source for additional exact knowledge.
4. Call create_action for any live customer lookup, account update, inline form,
   or safe function that should run in the installed website.
5. Call configure_webhook for any CRM or internal system. Use configure_crm when
   an Attio, Carly CRM, or HubSpot preset is useful.
6. Use get_bot and list_actions to inspect the trained sources and runtime.
7. Call get_install_code and add the returned widget script or iframe to the site.
8. After launch, use list_conversations, get_conversation, list_contacts,
   get_customer_history, and get_analytics to query customer activity and
   improve coverage.

Available tools
- create_bot
- list_bots
- get_bot
- configure_bot
- add_text_source
- add_website_source
- get_install_code
- create_action
- list_actions
- delete_action
- configure_crm
- test_crm_connection
- configure_webhook
- test_webhook_connection
- list_conversations
- get_conversation
- list_leads
- get_customer_history
- list_contacts
- get_analytics

Hosted chat: https://carlychat.com/embed/{botId}
REST chat: POST https://carlychat.com/api/chat/{botId}
REST body: {"message":"Your question"}

Customer data REST endpoints (bot key required)
- GET https://carlychat.com/api/bots/{botId}/conversations?q=&externalId=&lead=1
- GET https://carlychat.com/api/bots/{botId}/conversations/{conversationId}
- GET https://carlychat.com/api/bots/{botId}/leads?format=json
- GET https://carlychat.com/api/bots/{botId}/contacts?q=&externalId=
- GET/POST https://carlychat.com/api/bots/{botId}/actions
- GET/PATCH/POST https://carlychat.com/api/bots/{botId}/crm
- GET/PATCH/POST https://carlychat.com/api/bots/{botId}/webhooks

Machine-readable integration contract
- https://carlychat.com/integrations.json
- The REST API, MCP tools, signed webhooks, and actions are the canonical
  integration surface. Named CRM presets only provide default object mappings.

Verified customer identity
- POST https://carlychat.com/api/bots/{botId}/identity-token from a trusted server.
- Pass the returned short-lived token with CarlyChat.identify({token}).
- Protected actions receive only verified customer records.

Widget browser API
- CarlyChat.open(), CarlyChat.close(), CarlyChat.toggle(), CarlyChat.resetChat()
- CarlyChat.identify({token: signedCustomerJwt})
- Verified customers automatically resume their most recent conversation across devices.
- CarlyChat.registerTools({action_name: async (args) => result})
- CarlyChat.setContext({productId, section, ...}) for page-specific support
- CarlyChat.on("conversation-started" | "conversation-restored" | "user-message" | "assistant-message" | "tool-call", handler)

Server actions are signed with X-CarlyChat-Signature. Verify HMAC-SHA256 with
the bot's action secret over timestamp + "." + rawBody. Keep CRM and application
credentials in the receiving endpoint; do not send them to CarlyChat.

Integration webhooks are signed with X-CarlyChat-Signature and can send:
contact.upserted, conversation.started, lead.captured, message.created,
agent.message_created, handoff.requested, action.completed, and
feedback.submitted. Each delivery includes a stable ID for idempotency and is
retried up to three times on transient failures.
Verify the signature as HMAC-SHA256(webhookSecret, timestamp + "." + rawBody),
where timestamp comes from X-CarlyChat-Timestamp.

Generic integration mapping
- Call configure_webhook or PATCH /api/bots/{botId}/webhooks with an endpoint,
  selected events, and optional customer/conversation/ticket mapping.
- Each mapping entity accepts object, operation (create, upsert, or update),
  matchingAttribute, and parentObject. Omitted fields use safe defaults.
- The receiving bridge translates the canonical CarlyChat payload to its own
  API. Keep that system's OAuth token or API key in the bridge.

Attio preset
- Use provider="attio". New chatbots default to this provider.
- source.mapping in every delivery defines People upserted by email_addresses,
  conversation Notes parented to People, and a support_tickets custom object
  upserted by external_id.
- The bridge should call Attio with its own OAuth token or workspace API key.
  CarlyChat does not receive or store that Attio credential.
- The custom ticket object slug can be translated inside the bridge.

Carly CRM preset
- Use provider="carly".
- source.mapping defines Contacts keyed by external_id, Conversations attached
  to Contacts, and Support Tickets keyed by external_id.
- The bridge translates these contract names to the live Carly CRM schema.

HubSpot preset
- Use provider="hubspot".
- source.mapping defines Contacts upserted by email, Notes associated with the
  Contact, and Tickets created and associated with the Contact.
- The bridge selects the workspace's HubSpot ticket pipeline and stage.

Two-way CRM actions
- configure_crm actionsEndpoint receives the same signed action payload contract.
- installActions=true installs get_customer_record and create_support_ticket.
- Both actions require verified identity; ticket creation requires confirmation.
- Keep Attio, HubSpot, Carly CRM, and private CRM credentials in the receiving bridge.
- For any other system, create_action exposes the same signed, verified-customer
  read/write pattern without waiting for a first-party connector.

Page targeting
- configure_bot targetInclude accepts rules such as /pricing* or contains: /account/
- targetExclude prevents the widget from appearing on matching pages
- targetKnownOnly keeps the launcher hidden until CarlyChat.identify({token})

Public tool discovery does not require authentication. Tool calls do.