Onjiniyela

Sonny MCP Beta

Xhuma abasizi be-AI abahambisana ne-MCP — i-Claude, nanoma yiliphi iklayenti elikhuluma i-Model Context Protocol — endaweni yakho yokusebenza, ngemikhawulo nemingcele efanayo ne-API yomphakathi.

Funda umhlahlandlela we-API yomphakathi

Isiqalo esisheshayo

01
Engeza i-Sonny ku-Claude
Ku-Claude noma ku-Cowork, engeza isixhumi sangokwezifiso nge-URL https://www.usesonny.com/api/mcp. I-Sonny isekela ukubhaliswa kweklayenti okuzenzakalelayo, ngakho ayikho i-ID yeklayenti noma imfihlo okufanele uyikopishe.
02
Vumela ukufinyelela endaweni yokusebenza
I-Claude ivula i-Sonny esiphequlini sakho. Ngena, buyekeza izimvume eziceliwe, bese ukhetha indawo yokusebenza ozoyixhuma. I-OAuth 2.1 ne-PKCE igcina ama-token okufinyelela nawokuvuselela ekhawulelwe kulokho kuvuma.
03
Cela umsizi wakho asebenzise i-Sonny
Amathuluzi azichaza wona, ngakho umyalo onjengokuthi “Bala izingxoxo zami ezivuliwe” wanele. Abasizi babona ukuthi yimaphi amathuluzi okufunda kuphela nokuthi yimaphi asusayo, ngakho iklayenti elihle libuza ngaphambi kokushintsha noma yini.

Claude Code

claude mcp add --transport http sonny https://www.usesonny.com/api/mcp

Ukulungiselela kweklayenti kwe-JSON

{
  "mcpServers": {
    "sonny": {
      "url": "https://www.usesonny.com/api/mcp"
    }
  }
}

Ukuhambisana nokhiye we-API

Uma iklayenti lingakwazi ukuqedela i-OAuth, dala ukhiye onemikhawulo ku-Izilungiselelo → Unjiniyela bese uwuthumela njenge-header ye-Authorization Bearer. Okhiye be-API basasekelwa ngokuphelele kumaklayenti eseva-kuya-kuseva namadala.

"Authorization": "Bearer sonny_your_key"

Indlela i-Sonny egcina ngayo ukubiza amathuluzi kuphephile

Indawo yokusebenza eyodwa, imikhawulo ekhethiwe: Yonke ikholi isebenza ngaphakathi kwendawo yokusebenza ekhethwe ngesikhathi semvume ye-OAuth noma indawo yokusebenza engumnikazi wokhiye we-API. Ithuluzi lisebenza kuphela uma imininingwane yalo yokungena inemikhawulo edingekayo.
Izichasiselo zamathuluzi eziqotho: Amathuluzi okufunda kuphela amakwe ngokuthi okufunda kuphela; amathuluzi okubuyekeza nokususa amakwe ngokuthi ayasusa ukuze iklayenti lakho liqinisekise ngaphambi kokwenza.
Imithetho yebhizinisi efanayo: Amathuluzi asebenzisa izindlela zokusebenza ezifanayo ncamashi ne-API yomphakathi — umlando wokuhlola, izaziso, nama-webhook konke kuziphatha sengathi ozakwenu wenze ushintsho.

Gcina umsizi ngaphakathi kwe-inbox eyodwa

Iziteshi ezikhethiwe kukhiye we-API ziphoqelelwa ngokuzenzakalela kuyo yonke ikholi yethuluzi. Okhiye be-API nokuxhuma kwe-OAuth kuphinde kulandele ukufinyelela kwamanje kweziteshi kozakwenu oxhunyiwe. Ekuxhumeni kwe-OAuth noma kokhiye abanokufinyelela kuzo zonke iziteshi, izindawo zokusebenza zivame ukuba nemithombo eminingana — owodwa ngomkhiqizo noma ngophawu. Yenza umsizi wakho abize u-list_sources kanye ukuze ayithole, bese edlulisela u-sourceId ku-list_conversations ukuze imibuzo ngomkhiqizo owodwa ibuyise izingxoxo zalowo mkhiqizo kuphela. Yonke ingxoxo iphinde ibe no-sourceId wayo, ngakho imiphumela iyaqinisekiseka.

Qhuba umjikelezo wosizo ongabizi kakhulu

Thola izinguquko: qala ngohlu oluthembekile lwe-sync, londoloza i-nextCursor ngemva kokucubungula ikhasi ngalinye, bese ususa ama-ID emicimbi aphindiwe. Ukuze ukhethe umsebenzi, biza u-list_conversations nge-sourceId, awaitingReply: true, snoozed: "false", ne-compact: true. Amanothi angaphakathi awayifihli imilayezo yamakhasimende engakaphendulwa.
Funda umbhalo omusha kuphela: engxoxweni ngayinye eshintshile, biza u-list_messages nge-ID yomlayezo wakho wokugcina noma isikhathi se-ISO ku-after bese usetha u-includeHtml: false ngaphandle uma i-HTML ye-imeyili idingeka ngempela.
Linda izithombe namavidiyo: lapho u-list_messages ebuyisa u-readsInProgress, yenza ikholi ekwi-nextStep yayo. I-waitSeconds yayo ibamba impendulo kuze kulunge ukufundwa kwezithombe nemibhalo yamavidiyo, ngakho akudingeki ukulala.
Layisha umongo wekhasimende: u-get_conversation ubuyisa u-identityVerified, ama-verifiedTraits asayiniwe, nekhasi ingxoxo eqale kulo nomongo weklayenti. Uma ine-contact.id, dlulisela leyo ID ku-list_conversations ukuze ulayishe izingxoxo zangaphambili zekhasimende.
Vusa lapho kudingeka: sebenzisa i-webhook ehlungwe ngomthombo ye-message.created ukuvusa i-ejenti ngokushesha, bese ulandela nge-sync. Uhlu oluthembekile lusebenza ngokuzimela ekulethweni kwe-webhook. Sebenzisa imininingwane yokungena yazo zonke iziteshi ukuze uhlinzeke i-webhook futhi ukhawulele ama-ID emithombo yayo; i-ejenti igcina imininingwane yayo yokungena yesikhathi sokusebenza ekhawulelwe emthonjeni.

Uhlu lwamathuluzi

Yonke imisebenzi ye-API yomphakathi iyatholakala njengethuluzi. Imikhawulo edingekayo ibalwe eduze kwalo ngalinye.

get_connection_info: Read connection access; conversations:read
get_conversation_context: Read support context; conversations:read
list_conversation_checks: Read conversation checks; conversations:read
record_conversation_check: Record a conversation check; conversations:write
get_status: Check Sonny status; conversations:read
create_conversation: Create a conversation from a form; conversations:write
upload_attachment: Upload a message attachment; attachments:write
list_properties: List custom properties; contacts:read
get_contact_properties: Read contact properties; contacts:read
set_contact_property: Set a contact property; contacts:write
list_contact_memories: Read customer memories; contact-memory:read
create_contact_memory: Save a customer memory; contact-memory:write
delete_contact_memory: Remove a customer memory; contact-memory:write
get_report: Read a support report; reporting:read
sync: Read workspace changes; conversations:read
batch_update_conversations: Update conversations in a batch; conversations:write
list_members: List members; members:read
list_teams: List teams; members:read
list_tags: List tags; tags:read
create_tag: Create a tag; tags:write
get_tag: Get a tag; tags:read
update_tag: Update a tag; tags:write
delete_tag: Delete a tag; tags:write
add_conversation_tag: Add a conversation tag; conversations:write
remove_conversation_tag: Remove a conversation tag; conversations:write
list_contacts: List contacts; contacts:read
create_contact: Create a contact; contacts:write
get_contact: Get a contact; contacts:read
update_contact: Update a contact; contacts:write
archive_contact: Archive a contact; contacts:write
erase_contact: Permanently erase a contact; contacts:write
list_channels: List conversation channels; conversations:read
list_sources: List sources; conversations:read
list_conversations: List conversations; conversations:read
get_conversation: Get a conversation; conversations:read
update_conversation: Update a conversation; conversations:write
list_messages: List messages; messages:read
create_internal_note: Create an internal note; messages:write
edit_message: Edit a sent reply; messages:send
send_message: Send a reply to the customer; messages:send
list_webhooks: List webhook endpoints; webhooks:read
create_webhook: Create a webhook endpoint; webhooks:write
list_webhook_events: List webhook event types; webhooks:read
update_webhook: Update a webhook endpoint; webhooks:write
delete_webhook: Delete a webhook endpoint; webhooks:write
test_webhook: Queue a test event; webhooks:write
list_webhook_deliveries: List webhook deliveries; webhooks:read
retry_webhook_delivery: Retry a failed delivery; webhooks:write
list_kb_articles: List knowledge base articles; kb:read
create_kb_article: Create a knowledge base article; kb:write
get_kb_article: Get a knowledge base article; kb:read
update_kb_article: Update a knowledge base article; kb:write
delete_kb_article: Delete a knowledge base article; kb:write
list_kb_categories: List knowledge base categories; kb:read
create_kb_category: Create a knowledge base category; kb:write
update_kb_category: Update a knowledge base category; kb:write
delete_kb_category: Delete a knowledge base category; kb:write
get_csat_summary: Get CSAT scores; csat:read
list_csat_ratings: List CSAT ratings; csat:read
get_conversation_csat: Get a conversation's CSAT rating; csat:read
reorder_kb_articles: Reorder knowledge base articles; kb:write
upsert_kb_article: Sync a knowledge base article; kb:write
reorder_kb_categories: Reorder knowledge base categories; kb:write
upsert_kb_category: Sync a knowledge base category; kb:write
get_kb_category: Get a knowledge base category; kb:read
get_help_center: Get help center settings; kb:read
update_help_center: Update help center settings; kb:write
upload_kb_media: Upload a help center image; kb:write
list_kb_audiences: List audiences; kb:read
create_kb_audience: Create audience; kb:write
update_kb_audience: Update audience; kb:write
delete_kb_audience: Delete audience; kb:write

Ukugeleza komsebenzi kwama-ejenti

Hlunga, wenze, futhi uhlale uvumelana

I-REST ne-MCP zabelana ngezimvume nokugeleza komsebenzi okufanayo. Imininingwane yokungena ingakwazi kuphela ukunciphisa ukufinyelela kwakho kwamanje eziteshini; ukususa isiteshi kubulungu bakho kuyasisusa nasekuhlanganisweni kwakho.

Thola izingxoxo ezidinga ukunakwa

Hlunga nge-awaitingReply, unread, unassigned, assigneeId, agentGroupId, snoozed, priority, noma tagIds. I-awaitingReply ayinaki amanothi angaphakathi; i-unread ingeyozakwenu oqinisekisiwe kuphela. I-unassigned isho ukuthi akekho owabelwe ngamunye, ngisho noma ithimba labelwe. Amathegi afana nanoma iyiphi i-ID ehlinzekiwe.

list_conversations({ status: "open", awaitingReply: true, compact: true, sort: "waitingSince", direction: "asc" })

Hlela nge-waitingSince, lastMessageAt, createdAt, noma ukubaluleka kwebhizinisi ngendlela asc noma desc. Ama-ID ahlukanisa lapho kulingana. Izihlungi ezishiyiwe zigcina i-compact=false ne-snoozed=any. I-tagIds ye-REST yamukela ama-ID ahlukaniswe ngokhefana; i-MCP yamukela ne-array. I-waitingSince iqala emlayezweni wokuqala ongenayo ngemuva kwempendulo yokugcina; ukulandelela namanothi angaphakathi akuyiqali kabusha. Yenza lokhu kuskena kolayini olindile ngesheduli ngisho noma ingekho i-webhook efikayo, ukuze izingxoxo ezindala ziphinde zivele.

Landela ngaphandle kokuphinda ufunde i-inbox

Sebenzisa i-sync ne-conversations:read. I-feed eqinile ifaka izinguquko zezingxoxo, amathegi, imilayezo, izimfanelo zoxhumana nabo, izinkumbulo, namarekhodi okususa. I-payload ngayinye idinga nomkhawulo wayo wokufunda: imizimba yemilayezo idinga i-messages:read futhi izinkumbulo zidinga i-contact-memory:read. Imininingwane yokungena ekhawulelwe ithola iziteshi ezivunyelwe kuphela.

Qala ngaphandle kwe-cursor, landela i-nextCursor kuze kube yilapho i-hasMore iba false, bese ulondoloza leyo cursor.
Funda uhlu lwamanje lwezingxoxo/oxhumana nabo nanoma imuphi umlando owudingayo ukuze uthole isimo sakho sokuqala.
Phinda udlale kusuka ku-cursor egciniwe ukuze ubambe izinguquko ezenzeke ngesikhathi ufunda. Cubungula ikhasi ngalinye, bese ulondoloza i-nextCursor.

Susa okuphindwe kabili nge-id yomcimbi: ukuphinda kudlalwe okungenani kanye, ngakho izenzo ezilandelayo zidinga isivikelo sazo sokuphindwa. Isicelo esingenayo i-cursor sihlanganisa ihora lokugcina, hhayi isithombe esiphelele. Imicimbi igcinwa izinsuku ezingu-30; i-HTTP 410 resync_required isho ukuthi qala kabusha. Qala kabusha futhi ngemuva kokwandisa imikhawulo noma ukufinyelela eziteshini. Sebenzisa i-limit efika ku-100 ne-maxBodyChars efika ku-10,000 (okuzenzakalelayo ngu-500). Setha i-compact=true ukuze uthole izinkambu zemilayezo i-textPreview/textTruncated ezikhawulelwe ezinhlamvwini ezingu-200 esikhundleni se-body/bodyTruncated. Ama-webhook angavusa i-ejenti; i-feed ihlala itholakala ngaphandle kokubhalisela ama-webhook noma lapho ukulethwa kwama-webhook kusalele emuva.

Rekhoda ukuhlola kanye futhi wabelane ngomphumela

Ngaphambi kokuphinda uphenye, funda i-list_conversation_checks (GET /api/v1/conversations/{conversationId}/checks). Londoloza umphumela nge-record_conversation_check (PUT endleleni efanayo), uhlinzeke nge-key, result, checkedBy kanye ne-reference engaphoqelekile ye-ID yekhadi noma i-URL. Isibonelo: key=product-version, result=Shopstar Go verified, checkedBy=Engineer, reference=card-X. I-Sonny irekhoda i-actorId eqinisekisiwe nesitembu sesikhathi se-checkedAt. Ukusebenzisa futhi i-key kushintsha lokho kuhlola kuphela; lesi yisimo samanje, hhayi ilogi yomlando. Ukufunda kudinga i-conversations:read futhi ukubhala kudinga i-conversations:write, kokubili kukhawulelwe esiteshini sengxoxo. Lezi zikholi azithumeli impendulo futhi azimaki umthengisi njengophendulile.

Abela futhi ubuyekeze umsebenzi ngamaqoqo

Thola ozakwenu abasebenzayo nabangabelwa kanye namathimba nge-list_members / list_teams (members:read). Izimpendulo zifaka ukutholakala nokufinyelela okusebenzayo eziteshini, ngaphandle kwamakheli e-imeyili. Sebenzisa i-conversations:write ukuze ushintshe i-status, priority, assigneeId, agentGroupId, snoozedUntil, snoozedUntilReply, addTagIds, noma removeTagIds.

batch_update_conversations({
  conversationIds: ["conversation_1", "conversation_2"],
  updates: { agentGroupId: "team_1", assignment: "round_robin" }
})

I-round-robin ikhetha ilungu lethimba elitholakalayo elingafinyelela esiteshini sengxoxo. Uma lingekho ilungu elifanelekayo, isibuyekezo esisodwa sibuyisa i-409 futhi into esesiqoqweni iyehluleka. Iqoqo ngalinye lamukela ama-ID angafani afika ku-100 futhi lisebenzisa i-patch eyodwa ngokuphelele engxoxweni ngayinye. Hlola wonke umphumela we-{ id, ok, error? }; ezinye izinto zingase zehluleke. Amaqoqo asebenzisa umkhawulo wezicelo wamanje osekelwe ezicelweni, ngaphandle kokukhokhisa ngokwesisindo ngenani lezinto.

Yabelana ngomongo wekhasimende ne-Sonny AI

Bhala, londoloza, futhi ususe izinkumbulo zoxhumana nabo nge-contact-memory:read/write. Hlinzeka ngakho kokubili i-contactId ne-sourceId efinyelelekayo; oxhumana naye kufanele abe nengxoxo kulowo mthombo. Amaqiniso alondoloziwe asebenzisa ukuqinisekisa okufanayo, ukuphathwa kokuphindwayo, nemikhawulo efanayo nohlelo lokusebenza futhi arekhodwa njengezinkumbulo zesandla.

Funda izincazelo zezimfanelo ku-/api/v1/properties futhi ufunde noma usethe amanani ku-/api/v1/contacts/{contactId}/properties. I-MCP iveza i-list_properties, i-get_contact_properties, ne-set_contact_property. Lokhu kudinga i-contacts:read/write nokufinyelela kuzo zonke iziteshi. Setha i-propertyId eyodwa noma i-propertyName eyodwa ngqo, nenani lombhalo noma i-null ukuze ulisule. Amanani ombhalo, enombolo, e-URL, osuku, nawokukhetha aqinisekiswa ngokwencazelo yenkambu.

set_contact_property({ contactId: "contact_1", propertyName: "Plan", value: "Pro" })
list_contacts({ property: { Plan: "Pro" } })

Izihlungi zezimfanelo zifana nemibhalo egciniwe eqondile; izimfanelo eziningi kufanele zonke zifane. Amanani abhalwe yi-API abhalwa ukuthi ayimininingwane ye-API ku-Co-Pilot nakumphenduli ozenzakalelayo. Imithetho ekhona yekhasimende eliqinisekisiwe neyomthombo isasebenza. Amanani ezinkambu zangaphakathi afakwe ngesandla ajwayelekile ahlala engafakiwe kulo mongo we-AI.

Funda imibiko efanayo nethimba lakho

Nge-reporting:read, biza i-get_report({ kind, filters }). Izinhlobo yi-overview, volume, response-times, agents, sources, tags, csat, ai, knowledge, leads, ne-online-hours. I-overview ihlanganisa izibalo, izikhathi zokuphendula, ne-CSAT. Izihlungi yi-period (izinsuku ezingu-1–365, okuzenzakalelayo ngu-30), izinsuku ezibhangqiwe ze-from/to (i-to ayifakiwe), i-granularity (day/month), i-source, i-assigneeId, ne-tagId. I-source yamukela i-all, all-chat, all-email, website:{id}, noma email:{id}.

Imibiko isebenzisa ama-query edeshibhodi nokuhlolwa kokufinyelela kwamanje. I-knowledge isebenzisa izinsuku neziteshi ezivunyelwe, ngaphandle komthombo okhethiwe, owabelwe, noma ithegi. I-online-hours ilinganisa ukuba khona kozakwenu abafinyelelekayo endaweni yokusebenza; izibalo zayo zezingxoxo zihlala zikhawulelwe eziteshini. Ama-endpoint e-/csat akhona agcina umkhawulo wawo ohlukile we-csat:read futhi angase achaze iqembu elihlukile.

Thumela amafayela nezimpendulo noma amanothi angaphakathi

Nika i-attachments:write bese ulayisha ifayela elifika ku-25 MB lengxoxo. I-upload_attachment ithatha i-conversationId, fileName, contentType, ne-dataBase64. Impendulo iqukethe i-id ne-expiresAt. Dlulisela ama-attachmentIds afika ku-10 empendulweni noma enothini kungakapheli ihora elilodwa. Okulayishiwe ngakunye kuboshelwe kumsebenzisi wakho nasengxoxweni futhi kungasetshenziswa kanye kuphela. Okulayishiwe okungasetshenziswanga kuyasuswa ngemuva kokuphelelwa yisikhathi.

send_message({ conversationId: "conversation_1", attachmentIds: ["upload_1"] })

Izimpendulo zidinga i-messages:send; amanothi angaphakathi adinga i-messages:write futhi awalokothi afike kumakhasimende. Imilayezo enokunamathiselwe kuphela iyasekelwa. Izimpendulo ze-imeyili zifaka amafayela ngaphakathi kosayizi ovunyelwe we-imeyili nezixhumanisi zokulanda zalokho okusele; ama-imeyili engxoxo engekho ku-inthanethi afaka izixhumanisi zamafayela. Izixhumanisi ezithunyelwe nge-imeyili zihlala zisebenza inqobo nje uma okunamathiselwe kusekhona, ukuze abamukeli bazivule kamuva. Ukudlulisela i-imeyili kwabelana ngokufinyelela kulawo mafayela. Hlola i-emailDeliveryStatus ukuze ubone ukwehluleka kokulethwa.

Ukufunda imilayezo okugunyaziwe kufaka i-downloadUrl, downloadExpiresAt, aiStatus, aiDescription, ne-aiExtractedText, kanye ne-videoTranscripts yamavidiyo axhunyiwe (Loom, Vimeo nabanye). Izixhumanisi zokulanda zihlala imizuzu engu-15; phinda ufunde umlayezo ukuze uthole izixhumanisi ezintsha. Okulayishwe okusha kwe-API/MCP kunesitoreji sangasese. Okunamathiselwe okudala kuhlala kungokomphakathi futhi kumakwe nge-access=legacy_public: i-URL yokuqala ayiphelelwa yisikhathi. Ukufunda umlayezo kuqala ukufunda izithombe zawo uma indawo yokusebenza ine-Sonny AI. Ukufundwa kwezithombe nemibhalo yamavidiyo kuqeda ngemuva nje kokufika komlayezo: uma kusekhona okusaqhubeka, impendulo iqala nge-readsInProgress, okuthi i-nextStep yayo inikeze ikholi eqondile okufanele uyenze. Dlulisela i-waitSeconds (efika ku-30) ukuze ukulinde esicelweni esisodwa. Imilayezo ye-widget ebonwa amakhasimende neyesikhathi sangempela ayilokothi ifake okukhishiwe noma imibhalo yamavidiyo.

Hlola izivumelwano eziphelele zezicelo nezimpendulo

Isisekelo solwazi

Vumelanisa kusuka emthonjeni wangaphandle

Vumelanisa ama-athikili nezigaba usebenzisa ama-ID angaphandle azinzile, ngenisa i-Markdown noma i-HTML, layisha izithombe, setha ukuhleleka, futhi uphathe izethameli zabafundi. Ukuphinda i-upsert kubuyekeza okuqukethwe okukhona.

Khetha i-sourceId yesiteshi sakho bese unika i-kb:read ne-kb:write. Ukuze uthole okungaphoqelekile, i-list_sources nayo idinga i-conversations:read.
Dala isigaba, bese uvumelanisa i-athikili njengohlaka. Buyekeza ukufometha kwayo nokufinyelela ngaphambi kokushicilela.
Setha ukufinyelela kwesikhungo sosizo, shicilela, bese uhlola ukubuka komfundi. Sebenzisa ukuhlukaniswa kwamakhasi nama-ID angaphandle azinzile ezibuyekezweni zakamuva.

Landela umhlahlandlela ophelele wokuvumelanisa nge-MCP

Phatha izethameli zamakhasimende

Dala amaqembu kusuka ezimfanelweni zamakhasimende aqinisekisiwe bese uwasebenzisa esikhungweni sosizo, esigabeni, noma ku-athikili. Yonke imikhawulo ezuzwe ngefa kufanele ifane. Imininingwane yokungena ye-API ne-MCP isebenza njengabasebenzi ngaphakathi kwemikhawulo yayo; buka kuqala futhi uhlole iseshini yangempela yekhasimende ukuze uhlole ukufinyelela komfundi.

Setha futhi uhlole izethameli zesikhungo sosizo