Developers

MCP server

Connect AI assistants such as Claude to your account. Tools are generated from the REST API: every endpoint is a tool when your scopes allow it.

Server address

It uses Streamable HTTP and keeps no session. The assistant only sees tools within the API key's scopes or the access you granted: a read-only key can't send messages.

URL
https://hiboty.com/api/mcp

Ways to connect

  • OAuth (recommended): give an OAuth-capable client just the address, then sign in, choose an organization and allow access in your browser. Remove the connection any time under Settings → API.
  • API key: send an Authorization: Bearer hb_live_… header. The key's role and scopes apply as they are.

Setup in clients

Claude Code (OAuth)
claude mcp add --transport http hiboty https://hiboty.com/api/mcp

After the command, type /mcp inside Claude Code, select the hiboty server and sign in through your browser.

Claude Code (API key)
claude mcp add --transport http hiboty https://hiboty.com/api/mcp --header "Authorization: Bearer $HIBOTY_API_KEY"

Claude web and desktop: enter the server address under Settings → Connectors → Add custom connector, then allow access in your browser.

Cursor: .cursor/mcp.json
{
  "mcpServers": {
    "hiboty": { "url": "https://hiboty.com/api/mcp" }
  }
}
VS Code: .vscode/mcp.json
{
  "servers": {
    "hiboty": { "type": "http", "url": "https://hiboty.com/api/mcp" }
  }
}
Other clients (Streamable HTTP)
{
  "url": "https://hiboty.com/api/mcp",
  "headers": { "Authorization": "Bearer hb_live_YOUR_API_KEY" }
}
Try the connection from the command line
curl -X POST "https://hiboty.com/api/mcp" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Security

  • Take care when handing out a key that can message your customers; grant only the scopes needed.
  • An assistant or the API can create campaigns, but sending only starts after an admin approves them in the dashboard.
  • Message contents, contact names and Mini App submissions are customer data; the server tells the assistant not to follow instructions inside them.
  • Assistants see tools with external effects and irreversible tools through hints; keep approval prompts on for these tools in your client.

Tools with external effects

These tools message customers, call external systems or change something on the channel.

Tool list

228 tools. The tool name is the OpenAPI operationId; the input schema comes from the endpoint (path and query parameters are flat, the body goes under body, Idempotency-Key becomes idempotency_key).

See the API reference for parameters and samples.

Messages

ToolWhat it doesScopeType
sendMessageSends a message to a contactmessages:sendwrite, external effect
listMessagesLists a conversation's messages from newest to oldestreadread-only
retryMessageRetries a failed messageconversations:writewrite, external effect
rateAiReplyRates an AI replyconversations:writewrite

Bots

ToolWhat it doesScopeType
listBotsLists the organization's botsreadread-only
createBotCreates a botbots:writewrite
listBotTemplatesLists gallery templatesbots:readread-only
createBotDraftGenerates a bot draft with AI (saves nothing)bots:writewrite, external effect
importBotCreates a new draft bot from a bot filebots:writewrite
previewBotImportValidates a bot file without savingbots:writewrite
getBotBot detailsbots:readread-only
updateBotUpdates bot and AI settingsbots:writewrite
deleteBotDeletes a botbots:writewrite, external effect, irreversible
connectBotConnects a bot to its channelbots:writewrite, external effect
disconnectBotRemoves the channel connectionbots:writewrite, external effect, irreversible
pauseBotPauses a botbots:writewrite, external effect
resumeBotResumes a botbots:writewrite, external effect
getBotReadinessGo-live readiness checkbots:readread-only
exportBotExports the bot filebots:readread-only
testBotReplyTries an AI replybots:writewrite
listKnowledgeSourcesLists knowledge sourcesbots:readread-only
createKnowledgeSourceAdds a knowledge sourcebots:writewrite, external effect
getKnowledgeSourceA knowledge source's contentbots:readread-only
updateKnowledgeSourceUpdates a knowledge sourcebots:writewrite
deleteKnowledgeSourceDeletes a knowledge sourcebots:writewrite, irreversible
refreshKnowledgeSourceFetches a URL source againbots:writewrite, external effect
listBotToolsLists custom AI toolsbots:readread-only
createBotToolAdds a custom AI toolbots:writewrite, external effect
updateBotToolUpdates a custom AI toolbots:writewrite, external effect
deleteBotToolDeletes a custom AI toolbots:writewrite, irreversible
testBotToolCalls a custom tool with sample inputbots:writewrite, external effect
listBotVersionsLists configuration versionsbots:readread-only
getBotVersionVersion diff and restore previewbots:readread-only
restoreBotVersionRestores a versionbots:writewrite, irreversible
getBotProfileChannel profile textsbots:readread-only, external effect
updateBotProfileWrites profile texts to the channelbots:writewrite, external effect, irreversible
suggestBotProfileGenerates a profile suggestion with AIbots:writewrite
listBotEvalCasesLists AI evaluation casesbots:readread-only
createBotEvalCaseAdds an evaluation casebots:writewrite
updateBotEvalCaseUpdates an evaluation casebots:writewrite
deleteBotEvalCaseDeletes an evaluation casebots:writewrite, irreversible
listBotEvalRunsLists evaluation runsbots:readread-only
runBotEvalRuns an evaluationbots:writewrite
getBotEvalRunRun resultsbots:readread-only
listAcquisitionLinksLists acquisition linksbots:readread-only
createAcquisitionLinkCreates an acquisition linkbots:writewrite
deleteAcquisitionLinkDeletes an acquisition linkbots:writewrite, irreversible
listWhatsAppTemplatesAll WhatsApp templatesbots:readread-only, external effect
createWhatsAppTemplateCreates a WhatsApp templatebots:writewrite, external effect
deleteWhatsAppTemplateDeletes a WhatsApp templatebots:writewrite, external effect, irreversible
listAiFeedbackLists disliked AI repliesbots:readread-only
resolveAiFeedbackResolves a disliked replybots:writewrite
listTemplatesA WhatsApp bot's approved templatesreadread-only
refreshBotWebhookSets up the Telegram webhook againbots:writewrite, external effect
setBotCommandsSets up the Telegram command menubots:writewrite, external effect
getBotPaymentSettingsGets the card payment settingbots:readread-only
updateBotPaymentSettingsSaves the card payment provider tokenbots:writewrite
listPublishApprovalsLists changes awaiting approvalbots:readread-only
approveBotVersionApproves a pending bot changebots:writewrite
rejectBotVersionRejects a pending bot changebots:writewrite
bulkBotActionBulk action on several botsbots:writewrite, external effect
runAllBotEvaluationsRuns the evaluation set on all botsbots:writewrite
getFleetEvaluationFleet evaluation summarybots:readread-only
listOrgBotTemplatesLists the organization's bot templatesbots:readread-only
createOrgBotTemplateSaves a bot as a templatebots:writewrite
getOrgBotTemplateGets an organization templatebots:readread-only
updateOrgBotTemplateRenames a template or changes its descriptionbots:writewrite
deleteOrgBotTemplateDeletes a templatebots:writewrite, irreversible
createBotFromOrgTemplateCreates a bot from a templatebots:writewrite
listWhatsAppAccountsLists WhatsApp accountsbots:readread-only
getWhatsAppAccountGets a WhatsApp accountbots:readread-only
listWhatsAppAccountTemplatesLists a WhatsApp account's templatesbots:readread-only

Contacts

ToolWhat it doesScopeType
listContactsLists contacts from newest to oldestreadread-only
createContactCreates a contactcontacts:writewrite
getContactReturns a single contact (including tags, notes and custom fields)readread-only
updateContactUpdates name, notes, tags and custom fieldswritewrite
deleteContactPermanently deletes a contact (GDPR)contacts:writewrite, irreversible
getContactConsentCurrent consent and consent history (newest first, up to 50)readread-only
updateContactConsentUpdates messaging consent (and optional tags)writewrite, irreversible
importContactsImports contacts from CSV textcontacts:writewrite
exportContactsExports contacts as CSV chunkscontacts:readread-only
bulkContactsApplies a bulk action to contactscontacts:writewrite, irreversible
clearContactMemoryClears the contact's AI memorycontacts:writewrite, irreversible
revokeContactLinksRevokes links sent to the contactcontacts:writewrite, irreversible
linkContactProfileLinks the record to another record's customer profilecontacts:writewrite
unlinkContactProfileRemoves the record from its customer profilecontacts:writewrite, irreversible
listContactTagsLists tags with usage countscontacts:readread-only
renameContactTagRenames a tagcontacts:writewrite, irreversible
mergeContactTagsMerges tags into onecontacts:writewrite, irreversible
deleteContactTagsRemoves tags from all contactscontacts:writewrite, irreversible
listContactFieldsLists custom field definitionscontacts:readread-only
createContactFieldCreates a custom fieldcontacts:writewrite
updateContactFieldUpdates a custom fieldcontacts:writewrite, irreversible
deleteContactFieldDeletes a custom fieldcontacts:writewrite, irreversible

Conversations

ToolWhat it doesScopeType
listConversationsLists conversations by latest messagereadread-only
updateConversationStatusChanges the conversation statuswritewrite, external effect
getConversationConversation detailsconversations:readread-only
assignConversationAssigns a conversation to a team memberconversations:writewrite, external effect
markConversationReadMarks a conversation as readconversations:writewrite
snoozeConversationSnoozes a conversationconversations:writewrite
clearConversationFloodClears the message flood pauseconversations:writewrite
replyToConversationSends an agent replymessages:sendwrite, external effect
listConversationNotesLists internal notesconversations:readread-only
createConversationNoteAdds an internal noteconversations:writewrite
deleteConversationNoteDeletes an internal noteconversations:writewrite, irreversible
bulkConversationsRuns a bulk action on conversationsconversations:writewrite, external effect

Campaigns

ToolWhat it doesScopeType
listCampaignsLists campaignsreadread-only
createCampaignCreates a campaign (awaits approval)writewrite, external effect
getCampaignCampaign and variant resultsreadread-only
updateCampaignUpdates a campaign that hasn't startedcampaigns:writewrite
deleteCampaignDeletes a campaign that was never sentcampaigns:writewrite, irreversible
cancelCampaignCancels an unfinished campaignwritewrite, irreversible
getCampaignResultsVariant results and the A/B decisioncampaigns:readread-only
countCampaignAudienceCounts opted-in contacts matching a segmentcampaigns:readread-only
getCampaignBestTimeSuggested send timecampaigns:readread-only
listGrowthCampaignsLists growth campaignscampaigns:readread-only
createGrowthCampaignCreates a growth campaigncampaigns:writewrite
getGrowthCampaignGets a growth campaigncampaigns:readread-only
updateGrowthCampaignUpdates a growth campaigncampaigns:writewrite
deleteGrowthCampaignDeletes a growth campaigncampaigns:writewrite, irreversible
getGrowthCampaignReportGrowth campaign funnel and source comparisoncampaigns:readread-only
addGrowthCampaignSourceLinks a source to the campaign or opens a new linkcampaigns:writewrite, external effect
removeGrowthCampaignSourceRemoves a source from the campaigncampaigns:writewrite, irreversible

Mini Apps

ToolWhat it doesScopeType
listMiniAppsLists Mini Appsreadread-only
createMiniAppCreates a Mini Appminiapps:writewrite
listMiniAppSubmissionsMini App submissions and ordersreadread-only
getOrderOrder detailsminiapps:readread-only
updateOrderChanges the order statuswritewrite, external effect
getMiniAppMini App detailsminiapps:readread-only
updateMiniAppDraftUpdates the draftminiapps:writewrite
deleteMiniAppDeletes a Mini Appminiapps:writewrite, external effect, irreversible
publishMiniAppPublishes the draftminiapps:writewrite, external effect
unpublishMiniAppUnpublishes the appminiapps:writewrite, external effect
rollbackMiniAppRolls back to an earlier versionminiapps:writewrite, external effect
setMiniAppMenuButtonSets the Telegram menu buttonminiapps:writewrite, external effect
listMiniAppVersionsLists versionsminiapps:readread-only
getMiniAppPreviewDraft previewminiapps:readread-only
listOrdersLists ordersminiapps:readread-only
importMiniAppFeedImports a product feed into the catalogminiapps:writewrite, external effect, irreversible
approveMiniAppVersionPublishes a Mini App version awaiting approvalminiapps:writewrite, external effect
rejectMiniAppVersionRejects a Mini App version awaiting approvalminiapps:writewrite

Automations

ToolWhat it doesScopeType
listAutomationsLists automationsreadread-only
createAutomationCreates an automationautomations:writewrite
getAutomationAutomation detailsautomations:readread-only
saveAutomationSaves an automationautomations:writewrite
updateAutomationActivates or stops an automationwritewrite, irreversible
deleteAutomationDeletes an automationautomations:writewrite, irreversible
listAutomationRunsLists an automation's runsautomations:readread-only

Webhooks

ToolWhat it doesScopeType
listWebhooksLists webhooksreadread-only
createWebhookCreates a webhookwritewrite, external effect
getWebhookWebhook detailswebhooks:readread-only
updateWebhookUpdates a webhookwebhooks:writewrite, external effect
deleteWebhookDeletes a webhookwritewrite, irreversible
enableWebhookTurns a disabled webhook back onwritewrite, external effect
listWebhookDeliveriesLists delivery historywebhooks:readread-only
testWebhookSends a test event (ping)webhooks:writewrite, external effect

System

ToolWhat it doesScopeType
getUsagePlan and this month's usagereadread-only

Custom Mini Apps

ToolWhat it doesScopeType
listCustomMiniAppRequestsLists custom Mini App requestsminiapps:readread-only
createCustomMiniAppRequestOpens a custom Mini App requestminiapps:writewrite, external effect
getCustomMiniAppRequestCustom Mini App request detailsminiapps:readread-only
acceptCustomMiniAppQuoteAccepts the quoteminiapps:writewrite, external effect, irreversible
approveCustomMiniAppPreviewApproves the previewminiapps:writewrite, external effect, irreversible
cancelCustomMiniAppRequestCancels the requestminiapps:writewrite, external effect, irreversible

Saved replies

ToolWhat it doesScopeType
listSavedRepliesLists saved repliesconversations:readread-only
createSavedReplyAdds a saved replyconversations:writewrite
getSavedReplySaved reply detailsconversations:readread-only
updateSavedReplyUpdates a saved replyconversations:writewrite
deleteSavedReplyDeletes a saved replyconversations:writewrite, irreversible

Reports

ToolWhat it doesScopeType
getReportOverviewReport overviewreports:readread-only
getDeliveryTelemetryDelivery telemetryreports:readread-only
getAgentReportAgent performancereports:readread-only
getCsatReportSatisfaction reportreports:readread-only
getAiQualityReportAI quality reportreports:readread-only
getCohortReportAudience cohortsreports:readread-only
getRevenueReportRevenue attribution and ROIreports:readread-only
getUsageReportPlan and usagereports:readread-only
setReportCostSets the cost of a campaign or linkcampaigns:writewrite
importReportCostsImports ad costscampaigns:writewrite

Communities

ToolWhat it doesScopeType
listCommunitiesLists Telegram communitiescommunities:readread-only
getCommunityCommunity detailscommunities:readread-only
updateCommunityUpdates community settingscommunities:writewrite
removeCommunityRemoves a communitycommunities:writewrite, irreversible
refreshCommunityMembersRefreshes the member count from Telegramcommunities:writewrite, external effect
listCommunityInviteLinksLists invite linkscommunities:readread-only
createCommunityInviteLinkCreates an invite linkcommunities:writewrite, external effect
revokeCommunityInviteLinkRevokes an invite linkcommunities:writewrite, external effect, irreversible

Scheduled posts

ToolWhat it doesScopeType
listScheduledPostsLists scheduled postscommunities:readread-only
createScheduledPostSchedules a post or publishes it nowcommunities:writewrite, external effect
getPostCalendarReturns a month's calendar with its postscommunities:readread-only
getScheduledPostScheduled post detailscommunities:readread-only
updateScheduledPostEdits a scheduled postcommunities:writewrite
cancelScheduledPostCancels a scheduled postcommunities:writewrite, irreversible
publishScheduledPostPublishes a post nowcommunities:writewrite, external effect
approveScheduledPostApproves a pending postcommunities:writewrite, external effect
rejectScheduledPostRejects a pending postcommunities:writewrite
resendUncertainPostResends a post with an unknown outcomecommunities:writewrite, external effect

Organization

ToolWhat it doesScopeType
getOrganizationGets the organization settingsorganization:readread-only
updateOrganizationUpdates the organization settingsorganization:writewrite, external effect, irreversible
getContentPolicyGets the content policyorganization:readread-only
updateContentPolicyReplaces the content policyorganization:writewrite
getAiSettingsGets the AI settingsorganization:readread-only
updateAiSettingsUpdates the AI settingsorganization:writewrite, external effect
listStoresLists store connectionsorganization:readread-only
saveStoreSaves a store connectionorganization:writewrite, external effect
deleteStoreRemoves a store connectionorganization:writewrite, irreversible
testStoreTests a store connectionorganization:writewrite, external effect
listCrmConnectionsLists CRM connectionsorganization:readread-only
saveCrmConnectionSaves a CRM connectionorganization:writewrite, external effect
deleteCrmConnectionRemoves a CRM connectionorganization:writewrite, irreversible
testCrmConnectionTests a CRM connectionorganization:writewrite, external effect
listConnectionsLists connectionsorganization:readread-only

Media

ToolWhat it doesScopeType
listMediaLists the media libraryorganization:readread-only
uploadMediaUploads an imageorganization:writewrite
getMediaUsageGets where an image is usedorganization:readread-only
deleteMediaDeletes an imageorganization:writewrite, irreversible

Audit log

ToolWhat it doesScopeType
listAuditLogsLists the audit logorganization:readread-only

Team

ToolWhat it doesScopeType
listTeamMembersLists team membersteam:readread-only
updateTeamMemberChanges a member's role and bot accessteam:writewrite, irreversible
removeTeamMemberRemoves a member from the teamteam:writewrite, irreversible
listTeamInvitationsLists pending invitationsteam:readread-only
createTeamInvitationSends a team invitationteam:writewrite, external effect
cancelTeamInvitationCancels an invitationteam:writewrite, irreversible

API keys

ToolWhat it doesScopeType
listApiKeysLists API keysapi_keys:readread-only
revokeApiKeyRevokes an API keyapi_keys:writewrite, external effect, irreversible
listConnectedAppsLists apps connected with OAuthapi_keys:readread-only
revokeConnectedAppRemoves a connected app's accessapi_keys:writewrite, external effect, irreversible
getApiRequestLogAPI request logapi_keys:readread-only

Billing

ToolWhat it doesScopeType
getBillingGets the plan, limits, usage and subscription stateorganization:readread-only