Abaphuhlisi

I-MCP yeSonny Beta

Qhagamshela abancedisi be-AI abahambelana ne-MCP — iClaude, nawuphi na umxhasi othetha iModel Context Protocol — kwindawo yakho yokusebenzela, ngemida efanayo ne-API yoluntu.

Funda isikhokelo se-API yoluntu

Ukuqalisa ngokukhawuleza

01
Yongeza iSonny kwiClaude
KwiClaude okanye kwiCowork, yongeza isixhumi esilungiselelweyo ne-URL ethi https://www.usesonny.com/api/mcp. ISonny ixhasa ubhaliso lwabaxhasi oluzenzekelayo, ngoko akukho Client ID okanye imfihlo yokukopa.
02
Vuma ufikelelo kwindawo yokusebenzela
IClaude ivula iSonny kwibrawuza yakho. Ngena, phonononga iimvume ezicelwayo, uze ukhethe indawo yokusebenzela ozakuyiqhagamshela. I-OAuth 2.1 ne-PKCE igcina iithokheni zofikelelo nezokuhlaziya ezivelayo zinqunyelwe kweso sivumelwano.
03
Cela umncedisi wakho asebenzise iSonny
Izixhobo ziyazichaza, ngoko isicelo esifana no-“Dwelisa iincoko zam ezivuliweyo” sanele. Abancedisi babona ukuba zeziphi izixhobo ezifundwa kuphela nezitshabalalisayo, ngoko umxhasi olungileyo uyabuza phambi kokutshintsha nantoni na.

Claude Code

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

Uqwalaselo lomxhasi lwe-JSON

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

Ukuhambelana nezitshixo ze-API

Ukuba umxhasi akakwazi ukugqiba i-OAuth, yenza isitshixo esinemida kwi-Iisetingi → Umphuhlisi uze usithumele njenge-header ye-Authorization Bearer. Izitshixo ze-API zihlala zixhaswa ngokupheleleyo kwiseva-ukuya-kwiseva nakubaxhasi abadala.

"Authorization": "Bearer sonny_your_key"

Indlela iSonny egcina ngayo ukubizwa kwezixhobo kukhuselekile

Indawo enye yokusebenzela, imida ekhethiweyo: Konke ukubiza kusebenza ngaphakathi kwendawo yokusebenzela ekhethwe ngexesha lemvume ye-OAuth okanye kwindawo yokusebenzela engumnini wesitshixo se-API. Isixhobo sisebenza kuphela xa iinkcukacha zaso zokungena zinomda ofunekayo.
Amagqabantshintshi ezixhobo anyanisekileyo: Izixhobo zokufunda kuphela ziphawulwe njengezokufunda kuphela; izixhobo zokuhlaziya nokucima ziphawulwe njengezitshabalalisayo ukuze umxhasi wakho aqinisekise phambi kokwenza into.
Imithetho yeshishini efanayo: Izixhobo ziqhuba kanye iinkqubo eziqhutywa yi-API yoluntu — imbali yophicotho, izaziso nee-webhook zonke ziziphatha ngokungathi ilungu leqela lenze utshintsho.

Gcina umncedisi ngaphakathi kwibhokisi enye engenayo

Izitishi ezikhethiweyo kwisitshixo se-API zinyanzeliswa ngokuzenzekelayo kuko konke ukubizwa kwezixhobo. Izitshixo ze-API noqhagamshelo lwe-OAuth zikwalandela ufikelelo lwangoku lwezitishi lwelungu leqela eliqhagamshelweyo. Kuqhagamshelo lwe-OAuth okanye izitshixo ezinofikelelo kuzo zonke izitishi, iindawo zokusebenzela zihlala zinemithombo emininzi — omnye kwimveliso nganye okanye ibrendi. Yenza umncedisi wakho abize i-list_sources kanye ukuze ayifumane, uze udlulise i-sourceId ku-list_conversations ukuze imibuzo engemveliso enye ibuyise kuphela iincoko zaloo mveliso. Yonke incoko ikwaphethe i-sourceId yayo, ngoko iziphumo ziyaqinisekiseka.

Qhuba umjikelo wenkxaso ongabizi kakhulu

Fumana utshintsho: qalisa ngomsinga ozinzileyo othi sync, gcina i-nextCursor emva kokuqhuba iphepha ngalinye, uze ususe ii-ID zeziganeko eziphindiweyo. Ukuze ukhethe umsebenzi, biza i-list_conversations ene-sourceId, awaitingReply: true, snoozed: "false" ne-compact: true. Iinowuthi zangaphakathi azifihli imiyalezo yabathengi engaphendulwanga.
Funda kuphela umbhalo omtsha: kwincoko nganye etshintshileyo, biza i-list_messages ne-ID yomyalezo wakho wokugqibela okanye i-ISO timestamp kwi-after uze useta i-includeHtml: false ngaphandle kokuba i-HTML ye-imeyile iyafuneka ngokwenene.
Linda imifanekiso neevidiyo: xa i-list_messages ibuyisa i-readsInProgress, yenza ukubiza okukwi-nextStep yayo. I-waitSeconds yayo ibamba impendulo de ukufundwa kwemifanekiso nemibhalo yeevidiyo kulungile, ngoko akufuneki kulinda.
Layisha iinkcukacha zomthengi: i-get_conversation ibuyisa i-identityVerified, i-verifiedTraits etyikityiweyo, nephepha elivela kulo incoko neenkcukacha zomxhasi. Xa ine-contact.id, dlulisela loo ID ku-list_conversations ukuze ulayishe iincoko zangaphambili zomthengi.
Vusa xa kufuneka: sebenzisa i-webhook ehluzwe ngomthombo ye-message.created ukuze uvuse iarhente kwangoko, uze ufumane konke nge-sync. Umsinga ozinzileyo usebenza ngokuzimeleyo ekuhanjisweni kwee-webhook. Sebenzisa iinkcukacha zokungena zazo zonke izitishi ukulungiselela i-webhook nokunciphisa ii-ID zayo zomthombo; iarhente igcina iinkcukacha zayo zokungena ezinomda womthombo.

Ikhathalogu yezixhobo

Wonke umsebenzi we-API yoluntu uyafumaneka njengesixhobo. Umda ofunekayo udweliswe ecaleni kwesixhobo ngasinye.

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

Iinkqubo zeearhente

Hlela, yenza, uze uhlale uvumelana

I-REST ne-MCP zabelana ngeemvume neenkqubo ezifanayo. Iinkcukacha zokungena zinokunciphisa kuphela ufikelelo lwakho lwangoku lwezitishi; ukususa isitishi kubulungu bakho kukwasisusa kwimidibaniso yakho.

Fumana iincoko ezifuna ingqwalasela

Hluza nge-awaitingReply, unread, unassigned, assigneeId, agentGroupId, snoozed, priority okanye tagIds. Ukulinda impendulo akukhathali ngeenowuthi zangaphakathi; i-unread ithe ngqo kwilungu leqela eliqinisekisiweyo. I-unassigned ithetha ukuba akukho mntu mnye wabelweyo, nokuba iqela labelwe. Iithegi zihambelana nayiphi na i-ID enikiweyo.

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

Lungelelanisa nge-waitingSince, lastMessageAt, createdAt okanye ukubaluleka kweshishini nge-direction asc okanye desc. Ii-ID zahlula xa zilingana. Izihluzi ezingafakwanga zigcina i-compact=false ne-snoozed=any. I-tagIds ye-REST yamkela ii-ID ezahlulwe ngeekoma; i-MCP yamkela ne-array. I-waitingSince iqala kumyalezo wokuqala ongenayo emva kwempendulo yokugqibela; ukulandelela neenowuthi zangaphakathi azibuyiseli kwakhona. Qhuba olu hlolo lomgca wokulinda ngeshedyuli nokuba akukho webhook ifikayo, ukuze imisonto emidala iphinde ivele.

Fumana konke ngaphandle kokuphinda ufunde ibhokisi engenayo

Sebenzisa i-sync ene-conversations:read. Umsinga ozinzileyo uquka utshintsho lweencoko, iithegi, imiyalezo, iimpawu zabaqhagamshelwano, iinkumbulo neerekhodi zokucima. Umthwalo ngamnye ukwafuna umda wawo wokufunda: imizimba yemiyalezo ifuna i-messages:read kwaye iinkumbulo zifuna i-contact-memory:read. Iinkcukacha zokungena ezithintelweyo zifumana kuphela izitishi ezivunyelweyo.

Qala ngaphandle kwesikhombisi, landela i-nextCursor de i-hasMore ibe yi-false, uze ugcine eso sikhombisi.
Funda uluhlu lwangoku lweencoko/lwabaqhagamshelwano nayo nayiphi na imbali oyidingayo kwimeko yakho yokuqala.
Dlala kwakhona ukusuka kwisikhombisi esigciniweyo ukuze ubambe utshintsho ngexesha lokufunda. Qhuba iphepha ngalinye, uze ugcine i-nextCursor.

Susa eziphindiweyo nge-id yesiganeko: ukudlala kwakhona kwenzeka ubuncinane kanye, ngoko izenzo ezilandelayo zifuna ukhuseleko lwazo kwiziphindiweyo. Isicelo esingenasikhombisi sigubungela iyure yokugqibela, hayi umfanekiso opheleleyo. Iziganeko zigcinwa iintsuku ezingama-30; i-HTTP 410 resync_required ithetha qalisa kwakhona. Qalisa kwakhona nasemva kokwandisa imida okanye ufikelelo lwezitishi. Sebenzisa i-limit ukuya kuthi ga ku-100 ne-maxBodyChars ukuya kuthi ga ku-10,000 (okwesiqhelo yi-500). Seta i-compact=true kumabala e-textPreview/textTruncated emiyalezo anomda wabalinganiswa abangama-200 endaweni ye-body/bodyTruncated. Ii-webhook zingavusa iarhente; umsinga uhlala ufumaneka ngaphandle kobhaliso lwee-webhook okanye xa ukuhanjiswa kwee-webhook kusalela emva.

Bhala uhlolo kanye uze wabelane ngesiphumo

Phambi kokuphinda uphando, funda i-list_conversation_checks (GET /api/v1/conversations/{conversationId}/checks). Gcina isiphumo nge-record_conversation_check (PUT kwindlela efanayo), unikeze i-key, result, checkedBy ne-reference engenyanzelekanga ye-ID yekhadi okanye i-URL. Umzekelo: key=product-version, result=Shopstar Go verified, checkedBy=Engineer, reference=card-X. ISonny ibhala i-actorId eqinisekisiweyo ne-timestamp ye-checkedAt. Ukuphinda usebenzise i-key kutshintsha olo hlolo kuphela; le yimeko yangoku, ayiyolog yembali. Ukufunda kufuna i-conversations:read kwaye ukubhala kufuna i-conversations:write, zombini zinqunyelwe kwisitishi sencoko. Oku kubiza akuthumeli mpendulo okanye kuphawule umthengisi njengophendulweyo.

Abela uze uhlaziye umsebenzi ngamaqela

Fumana amalungu eqela namaqela asebenzayo anokwabelwa nge-list_members / list_teams (members:read). Iimpendulo ziquka ukufumaneka nofikelelo lwezitishi olusebenzayo, ngaphandle kweedilesi ze-imeyile. Sebenzisa i-conversations:write ukutshintsha i-status, priority, assigneeId, agentGroupId, snoozedUntil, snoozedUntilReply, addTagIds okanye removeTagIds.

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

Ukwabela ngokujikelezayo kukhetha ilungu leqela elikhoyo elinokufikelela kwisitishi sencoko. Xa kungekho lungu lifanelekileyo, uhlaziyo olunye lubuyisa i-409 kwaye into enye kwiqela ayiphumeleli. Iqela ngalinye lamkela ukuya kuthi ga kwii-ID ezahlukileyo eziyi-100 kwaye lisebenzisa i-patch enye ngokupheleleyo kwincoko nganye. Hlola sonke isiphumo se-{ id, ok, error? }; ezinye izinto zingaphumeleli. Amaqela asebenzisa umda wezicelo wangoku osekelwe kwizicelo, ngaphandle kokuhlawulisa ngobunzima ngokwenani lezinto.

Yabelana ngeenkcukacha zomthengi neSonny AI

Dwelisa, gcina uze ususe iinkumbulo zabaqhagamshelwano nge-contact-memory:read/write. Nika zombini i-contactId ne-sourceId efikelelekayo; oqhagamshelwano kufuneka abe nencoko kuloo mthombo. Iinyani ezigciniweyo zisebenzisa ukuqinisekisa okufanayo, ukuphatha eziphindiweyo nemida njenge-app kwaye zibhalwa njengeenkumbulo zesandla.

Funda iinkcazo zeempawu kwi-/api/v1/properties uze ufunde okanye usete amaxabiso kwi-/api/v1/contacts/{contactId}/properties. I-MCP iveza i-list_properties, get_contact_properties ne-set_contact_property. Ezi zifuna i-contacts:read/write nofikelelo kuzo zonke izitishi. Seta kanye i-propertyId enye okanye i-propertyName, ngexabiso le-string okanye i-null ukuze ulicoce. Amaxabiso ombhalo, enani, e-URL, omhla nawokhetho aqinisekiswa ngokwenkcazo yebala.

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

Izihluzi zeempawu zihambelana nee-string ezigciniweyo ngokuchanekileyo; iimpawu ezininzi kufuneka zonke zihambelane. Amaxabiso abhalwe yi-API aphawulwa njengedatha ye-API kwi-Co-Pilot nakumphenduli ozenzekelayo. Imithetho esele ikhona yabathengi abaqinisekisiweyo neyemithombo isasebenza. Amaxabiso amabala angaphakathi aqhelekileyo afakwe ngesandla ahlala engabandakanywa kwezi nkcukacha ze-AI.

Funda iingxelo ezifanayo neqela lakho

Nge-reporting:read, biza i-get_report({ kind, filters }). Iintlobo zezi: overview, volume, response-times, agents, sources, tags, csat, ai, knowledge, leads ne-online-hours. I-overview idibanisa amanani, amaxesha okuphendula ne-CSAT. Izihluzi zezi: period (iintsuku ezi-1–365, okwesiqhelo zingama-30), imihla edibeneyo ye-from/to (i-to ayibandakanywa), granularity (day/month), source, assigneeId ne-tagId. I-source yamkela i-all, all-chat, all-email, website:{id} okanye email:{id}.

Iingxelo zisebenzisa imibuzo yedashbhodi nokujonga ufikelelo kwangoku. I-knowledge isebenzisa imihla nezitishi ezivunyelweyo, ngaphandle komthombo okhethiweyo, owabelweyo okanye ithegi. Iiyure zokuba kwi-intanethi zilinganisa ubukho bamalungu eqela afikelelekayo kwindawo yokusebenzela; amanani alo eencoko ahlala enqunyelwe kwizitishi. Ii-endpoint ze-/csat esele zikhona zigcina umda wazo owahlukileyo we-csat:read kwaye zinokuchaza iqela elahlukileyo.

Thumela iifayile neempendulo okanye iinowuthi zangaphakathi

Nika i-attachments:write uze ulayishe ifayile ukuya kuthi ga kwi-25 MB yencoko. I-upload_attachment ithatha i-conversationId, fileName, contentType ne-dataBase64. Impendulo iqulethe i-id ne-expiresAt. Dlulisela ukuya kuthi ga kwii-attachmentIds ezili-10 kwimpendulo okanye kwinowuthi kwisithuba seyure enye. Into nganye elayishiweyo ibotshelelwe kumsebenzisi wakho nakwincoko kwaye ingasetyenziswa kanye kuphela. Izinto ezilayishiweyo ezingasetyenziswanga ziyacocwa emva kokuphelelwa.

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

Iimpendulo zifuna i-messages:send; iinowuthi zangaphakathi zifuna i-messages:write kwaye azize zifike kubathengi. Imiyalezo eneefayile kuphela iyaxhaswa. Iimpendulo ze-imeyile ziquka iifayile ngaphakathi kobungakanani be-imeyile namakhonkco okukhuphela azo zonke ezinye; ii-imeyile zechat engekho kwi-intanethi ziquka amakhonkco eefayile. Amakhonkco athunyelwe nge-imeyile ahlala esebenza ngelixa into eqhotyoshelweyo ikhona, ngoko abamkeli bangawavula kamva. Ukudlulisela i-imeyile kwabelana ngofikelelo kwezo fayile. Jonga i-emailDeliveryStatus ukuze ubone ukungaphumeleli kokuhanjiswa.

Ukufunda imiyalezo okugunyazisiweyo kuquka i-downloadUrl, downloadExpiresAt, aiStatus, aiDescription ne-aiExtractedText, kunye ne-videoTranscripts yeevidiyo ezinekhonkco (Loom, Vimeo nezinye). Amakhonkco okukhuphela ahlala imizuzu eli-15; phinda ufunde umyalezo ukuze ufumane amakhonkco amatsha. Izinto ezintsha ezilayishwe nge-API/MCP zinogcino lwabucala. Izinto ezindala eziqhotyoshelweyo zihlala zezoluntu kwaye ziphawulwe njenge-access=legacy_public: i-URL yazo yokuqala ayiphelelwa. Ukufunda umyalezo kuqalisa ukufunda imifanekiso yawo xa indawo yokusebenzela ineSonny AI. Ukufundwa kwemifanekiso nemibhalo yeevidiyo kugqitywa kungekudala emva kokuba umyalezo ufikile: ngelixa kukho ezisaqhubekayo, impendulo iqala nge-readsInProgress, ene-nextStep enika kanye ukubiza ekufuneka ukwenzile. Dlulisela i-waitSeconds (ukuya kuthi ga ku-30) ukuze uzilinde kwisicelo esinye. Iwijethi ebonwa ngabathengi nemiyalezo yexesha lokwenyani azize ziquke ukukhutshwa kombhalo okanye imibhalo yeevidiyo.

Phonononga izivumelwano ezipheleleyo zezicelo neempendulo

Isiseko solwazi

Vumelanisa ukusuka kumthombo wangaphandle

Vumelanisa amanqaku neendidi usebenzisa ii-ID zangaphandle ezizinzileyo, ngenisa i-Markdown okanye i-HTML, layisha imifanekiso, seta ulandelelwano, uze ulawule abaphulaphuli abangabafundi. Ukuphinda i-upsert kuhlaziya umxholo osele ukhona.

Khetha i-sourceId yesitishi sakho uze unike i-kb:read ne-kb:write. Ukuze ufumane ngokungenyanzelekanga, i-list_sources ikwafuna i-conversations:read.
Yenza udidi, uze uvumelanise inqaku njengedrafti. Phonononga ufomatho nofikelelo lwalo phambi kokupapasha.
Lungiselela ufikelelo lweziko loncedo, papasha, uze uvavanye umboniso womfundi. Sebenzisa amaphepha nee-ID zangaphandle ezizinzileyo kuhlaziyo lwamva.

Landela isikhokelo esipheleleyo sokuvumelanisa nge-MCP

Lawula abaphulaphuli abangabathengi

Yenza amaqela ukusuka kwiimpawu zabathengi eziqinisekisiweyo uze uwasebenzise kwiziko loncedo, udidi okanye inqaku. Zonke izithintelo ezifunyenwe njengelifa kufuneka zihambelane. Iinkcukacha zokungena ze-API ne-MCP zisebenza njengabasebenzi ngaphakathi kwemida yazo; jonga kuqala uze uvavanye iseshoni yomthengi wokwenyani ukuze ujonge ufikelelo lomfundi.

Lungiselela uze uvavanye abaphulaphuli beziko loncedo