io.github.conquext/neuron

Assign a bot to handle incoming messages on a specific WhatsApp channel. Replaces any previously assigned bot.

Attach a knowledge base to a bot to enhance its responses with domain-specific knowledge. Optional priority determines retrieval order when multiple knowledge bases are attached.

Transcribe an audio recording and extract contact information (name, phone, email, notes, tags). Automatically saves the extracted contact to the organization's address book.

Block a WhatsApp contact. Blocked contacts cannot message the bot or see its profile.

Send a message to a bot via the API and receive a streaming or complete AI-generated response. Requires a valid API key with 'nrn_' prefix.

Retrieve configuration and status information about the bot associated with the provided API key.

Retrieve message history for a specific conversation with cursor-based pagination. Requires a valid API key.

Retrieve a paginated list of conversations managed by the bot. Supports filtering by conversation status. Requires a valid API key.

Send an outbound message through the bot API to a specified phone number. Supports text and media messages. Requires a valid API key.

Browse verified contact lists available in the shared marketplace pool. Filter by category, region, or search term.

Browse the shared marketplace pool of published bots, tools, knowledge bases, and reflections with optional filtering by type, category, tags, or search query.

Enable or disable multiple built-in tools at once for a bot. More efficient than toggling tools individually.

Browse available campaigns in the marketplace that your organization can join to earn rewards by sending messages.

Retrieve all participants who have joined a campaign you own, including their delivery counts and earned rewards.

Cancel the current active subscription. Access continues until the end of the current billing period.

Initiate a checkout session for a subscription plan upgrade. Returns a checkout URL or confirmation to complete the purchase.

Close an active conversation, marking it as completed. The bot will stop responding and the conversation is archived.

Compose and send a new message to a phone number via a specific channel. Automatically creates a new conversation if one does not exist.

Create an ad distribution request to send a message to contacts in pool lists matching target demographics. Deducts from wallet upon approval.

Create a new API key for programmatic access to a specific bot. Store the key securely as it cannot be retrieved later.

Create a new blog post in draft or published status with specified title, content, and optional metadata such as tags, excerpt, and SEO fields.

Create a new AI bot with specified name, model, and behavior instructions. Returns the created bot object.

Create a new broadcast message in draft status. Provide recipients directly or use recipientSources to resolve from contact lists. The WhatsApp channel is auto-resolved if not specified.

Create a new outreach campaign with target audience, messaging template, and schedule configuration. Requires a Pro or Business plan.

Create a new WhatsApp channel with either Meta Cloud API or Baileys (direct WhatsApp) integration. Meta Cloud channels require metaPhoneNumberId and metaAccessToken.

Create a new contact in the organization's address book. If notes are provided, they are saved as a structured note entry with source tracking.

Create a new contact list. Slug is auto-generated from name if not provided. For dynamic lists, provide criteria with rules and/or an AI prompt.

Add a new entry (note, document, or information piece) to a knowledge base.

Create a new knowledge base to store and organize information, documents, and entries.

Create a new WhatsApp Channel newsletter for one-way broadcast updates. Requires a connected Baileys session on the specified channel.

Register a new outbound webhook that sends HTTP POST requests to an external URL when specified bot events occur. Supported events: message.created, message.assistant, conversation.created, conversation.escalated, conversation.closed, bot.paused, bot.resumed.

Create a custom API tool that the bot can invoke during conversations to fetch external data or trigger actions.

Register a new inbound webhook endpoint that triggers bot actions when called by an external service.

Permanently delete a blog post by its ID. This action cannot be undone.

Permanently delete a bot and all its associated data. This action cannot be undone.

Permanently delete a broadcast and its recipient data. This action cannot be undone.

Permanently delete a campaign that is in 'draft' status. Active or funded campaigns cannot be deleted.

Permanently delete a WhatsApp channel and disconnect any active sessions. This action cannot be undone.

Permanently delete a contact and remove them from all contact lists. This action cannot be undone.

Permanently delete a contact list. System-protected lists (e.g., 'Do Not Contact') cannot be deleted.

Permanently delete a specific entry from a knowledge base.

Permanently delete a knowledge base and all its associated entries and documents.

Permanently delete a specific message from a conversation. This action cannot be undone.

Permanently delete a WhatsApp Channel newsletter and remove it from WhatsApp. This action cannot be undone.

Permanently remove an outbound webhook. The external endpoint will no longer receive event notifications from this bot.

Permanently remove a custom API tool integration from a bot. The bot will no longer be able to invoke this tool in conversations.

Permanently remove an inbound webhook from a bot. External services will no longer be able to trigger this endpoint.

Remove a knowledge base from a bot. The bot will no longer reference this knowledge base when generating responses.

Edit the content of a previously sent message in a conversation. Only the message sender can edit their messages.

Export all contacts as a downloadable dataset for the current organization.

Retrieve all contact lists that a specific contact belongs to.

Forward a WhatsApp message from one chat to another. Uses copy-send approach — the message content is re-sent to the destination.

Fund an approved campaign by deducting the total budget from the organization's wallet balance. Requires sufficient wallet funds.

Initialize a wallet funding transaction via Paystack. Returns a checkout URL to complete the payment in a browser.

Retrieve delivery analytics and performance breakdown for a specific ad request, including delivery rates and cost metrics.

Retrieve the saved bank account details currently configured as the organization's payout destination.

Retrieve the current billing information, subscription plan, and usage details for the organization.

Fetch the list of all blocked WhatsApp contacts for the bot on the given channel.

Retrieve a single blog post by its URL-friendly slug, including full content and metadata.

Retrieve detailed information about a specific bot including its configuration, status, and associated resources.

Retrieve analytics and usage statistics for a specific bot, including message counts, response times, and conversation metrics.

Retrieve detailed information about a specific broadcast, including its status, message content, and recipient summary.

Retrieve the paginated list of recipients for a specific broadcast with their individual delivery status.

Fetch the WhatsApp Business profile of an external contact, including description, website, category, and business hours.

Retrieve detailed information about a specific campaign including its status, budget, participants, and delivery metrics.

Retrieve detailed information about a specific WhatsApp channel, including its configuration, type, and connection status.

Retrieve the event log for a channel, including connection events, message events, and errors. Supports pagination.

Retrieve the current QR code for pairing a Baileys channel with WhatsApp. A session must be started first.

Retrieve the current connection status and session details for a specific channel (e.g., connected, disconnected, qr_pending).

Retrieve detailed information about a specific contact including their tags, notes, and associated lists.

Retrieve detailed information about a specific contact list, including member count and configuration.

Retrieve the members of a specific contact list with optional search filtering and pagination.

Retrieve detailed information about a specific conversation, including its status, participants, and metadata.

Retrieve contacts eligible to receive a campaign message. Respects deduplication rules and mutual contact requirements.

Get the invite link for a WhatsApp group. Only supported on Baileys channels where the bot is a group admin.

Retrieve the list of participants in a specific WhatsApp group accessible through a channel.

Retrieve detailed information about a specific knowledge base by its ID.

Retrieve messages from a specific conversation in chronological order, with optional cursor-based pagination.

Retrieve detailed information about a specific WhatsApp Channel newsletter, including subscriber count and metadata.

Retrieve detailed information about a specific organization, including its name, settings, and configuration.

Retrieve delivery logs for an outbound webhook to monitor event dispatch history and debug delivery failures.

Retrieve detailed information about a specific item in the marketplace pool, including its description, category, tags, and install count.

Fetch the bot's current WhatsApp privacy settings (last seen, online, profile picture, status, read receipts, groups add).

Retrieve the authenticated user's profile information including name, email, role, and current organization.

Retrieve execution logs for an inbound webhook to monitor incoming requests and debug processing issues.

Approve or reject pending join requests for a WhatsApp group. Requires admin privileges.

Bulk import multiple contacts into the organization's address book. Accepts an array of contact objects with name, phone, and optional fields.

Ingest content into a knowledge base. Supports deduplication via externalId and optional LLM processing (summarize, extract_facts, or custom instruction).

Install a resource from the marketplace pool into the current organization. Choose 'fork' for an independent copy or 'subscribe' to receive future updates from the publisher.

Send an invitation to a new member to join the organization. The invitee receives an email with a link to accept.

Join a marketplace campaign as a participant to earn rewards by sending messages through your WhatsApp channel.

Make the bot leave a WhatsApp group. This action is irreversible — the bot will need to be re-added by an admin.

Retrieve all ad requests for the current organization with optional status filtering and pagination.

Retrieve all API keys associated with a specific bot, including their names, creation dates, expiration status, and revocation status.

Retrieve audit logs for the organization, showing a chronological record of actions performed by members. Supports filtering by action type and resource.

Retrieve a paginated list of blog posts with optional filtering by status, author type, author ID, or tag.

Retrieve all WhatsApp channels connected to a specific bot, including primary and secondary connections.

Retrieve all knowledge bases attached to a specific bot, including their priorities and metadata.

Retrieve all bots accessible to the current user, including their configurations and status.

Retrieve a paginated list of all broadcasts with optional filtering by status such as draft, sent, or scheduled.

Retrieve all available built-in tools with their enabled/disabled status for a specific bot. Built-in tools include WhatsApp actions (send messages, delete messages, post status), utility functions (web search, QR codes, weather), scheduling, knowledge base search, and more.

Retrieve all campaigns for the current organization with optional status filtering and pagination.

Retrieve all WhatsApp groups that the channel is participating in, including group metadata.

Retrieve all WhatsApp channels configured in the current organization, including their type and connection status.

Retrieve all contact lists for the current organization with optional filtering by search term, type, and pagination.

Retrieve all contacts for the current organization with optional filtering by search term, tag, and pagination.

Retrieve a paginated list of conversations for a specific bot, with optional filtering by status.

List all items the current organization has installed from the marketplace pool.

Retrieve a list of all pending invitations for the organization that have not yet been accepted or revoked.

Retrieve all bots that are connected to or using a specific knowledge base.

Retrieve entries from a knowledge base with optional filtering and pagination.

Retrieve all knowledge bases accessible to the current user.

Retrieve a list of all members in the organization, including their roles and permissions.

Retrieve a paginated list of all WhatsApp Channel newsletters for the organization, with optional filtering by WhatsApp session channel.

Retrieve all organizations the authenticated user belongs to, including their roles in each.

Retrieve all outbound webhooks configured for a specific bot, including their target URLs and subscribed event types.

Retrieve the payout history for the organization, including amounts, statuses, and timestamps.

List all items the current organization has published to the marketplace pool.

Retrieve pending reflections that the bot has generated from conversations, awaiting human review. Optionally filter by approval status.

Retrieve all custom API tool integrations configured for a specific bot, including their endpoints and configuration.

Retrieve all inbound webhooks configured for a specific bot, including their status and configuration.

Retrieve contacts from the WhatsApp account connected to this channel, with optional search filtering.

Authenticate with Neuron. Three modes: 1. No args: Opens a browser URL for secure authorization (recommended — no credentials shared with AI) 2. token: Paste an MCP token from the Neuron dashboard 3. email+password: Legacy login (credentials visible to AI)

Clear the current auth token locally. Does NOT revoke server-side MCP tokens — revoke from the Neuron dashboard (Settings > MCP Tokens) for full invalidation.

Mark a WhatsApp message as read, sending read receipts to the sender.

Merge two or more contact lists into a single unified list, deduplicating entries. Window merge creates a virtual union; materialized merge creates a static copy.

Retrieve all campaigns the current organization has joined as a participant, including earnings and delivery stats.

Pause a bot to temporarily stop it from processing new messages. The bot retains its configuration and can be resumed later.

Pause an active campaign to temporarily stop message delivery. Can be resumed later with the resume action.

Enrich existing contacts with additional data from connected messaging channels. Syncs profile information from linked platforms.

Post a message to a WhatsApp Channel newsletter. All subscribers receive the message. Provide at least one of text or mediaUrl. This triggers delivery and cannot be undone.

Publish a blog post, making it publicly visible. The post must be in 'draft' status.

Publish a bot, tool, knowledge base, or reflection to the shared marketplace pool for other organizations to discover and install.

Pull the latest updates for a subscribed pool resource to sync with the publisher's changes. Only applies to items installed with 'subscribe' mode.

Trigger a refresh of a dynamic contact list. Re-evaluates criteria rules and/or AI prompt and materializes updated members.

Re-fetch metadata (name, description, subscriber count) for a WhatsApp Channel newsletter from WhatsApp to synchronize local data.

Refresh the access token using a refresh token. Automatically sets the new access token for subsequent API calls.

Register a new user account with name, email, password, and organization name. Creates both the user and an initial organization.

Reject a bot-generated reflection to prevent it from being incorporated into the bot's learned behavior.

Release a conversation back to the bot, returning control from a human agent. The bot will resume auto-responding.

Disconnect a WhatsApp channel from a bot. The bot will no longer respond to messages on this channel.

Remove one or more contacts from a list by their contact IDs. Does not delete the contacts themselves.

Permanently remove a member from the organization. The member loses all access immediately. This action cannot be undone.

Remove the bot's WhatsApp profile picture, reverting to the default.

Permanently delete a stored secret from a custom tool integration. The tool will lose access to this credential.

Request a numeric pairing code for a Baileys channel as an alternative to QR code scanning. Requires the phone number to pair with.

Request a payout to transfer funds from the organization wallet to the linked bank account. A bank account must be saved first.

Resume a previously paused bot so it begins processing new messages again.

Resume a previously paused campaign to restart message delivery.

Permanently revoke an API key to immediately invalidate it and prevent further programmatic access. This action cannot be undone.

Revoke the current group invite link and generate a new one. The old link will stop working. Requires admin.

Revoke a pending organization invitation so it can no longer be accepted. This action cannot be undone.

Rewrite or rephrase text using AI with specified tone, style, or instructions (e.g., make it more formal, translate, summarize).

Save a verified bank account as the organization's payout destination. Verify the account first using neuron_verify_bank_account.

Search contacts by a query string across name, phone number, and email fields. Returns matching contacts ranked by relevance.

Perform semantic search across all entries and documents in a knowledge base to find relevant information.

Search contacts using natural language AI-powered semantic search. Finds contacts based on the meaning of their notes — skills, services, schedules, preferences, etc. Returns ranked results with relevance scores and AI-generated match reasons.

Send a broadcast message to all its recipients. The broadcast must be in draft status. This triggers message delivery and cannot be undone.

Send a campaign message to selected eligible contacts via WhatsApp. Requires the campaign to be in 'active' status and contacts to be eligible.

Send a vCard contact card via WhatsApp with name, phone, and optional organization.

Send a location pin via WhatsApp with coordinates and optional name/address.

Send a message to an existing conversation. Supports text, image, and document message types with optional media attachments.

Send a poll message via WhatsApp. Polls support 2-12 options and optional multi-select. Only supported on Baileys channels.

Send or remove an emoji reaction on a WhatsApp message. Pass an empty emoji string to remove a reaction.

Send a WebP sticker image via WhatsApp. Only supported on Baileys channels.

Send a WhatsApp message to a phone number or group. Auto-resolves which channel to use (org default > first connected). Supports text, image, audio, video, and document types.

Set or clear the default WhatsApp channel for the organization. The default channel is used by neuron_send_whatsapp for auto-resolving which channel to send through.

Enable or disable join approval mode for a WhatsApp group. When enabled, join requests must be manually approved by admins. Requires admin.

Set typing indicator or online/offline presence on a WhatsApp chat. Only supported on Baileys channels.

Start a Baileys (direct WhatsApp) session for the channel. Generates a QR code for device pairing. Only applicable to Baileys-type channels.

Permanently stop an active campaign and refund the remaining unspent budget to the organization's wallet. This action cannot be undone.

Stop the active Baileys session for the channel and disconnect from WhatsApp. The channel can be restarted later.

Submit a draft campaign for admin review and approval. The campaign must be in 'draft' status.

Submit a contact list to the shared pool marketplace for other organizations to discover and use for ad distribution.

Switch the MCP server to target a different Neuron backend instance. Auth tokens are preserved per instance — if you've previously logged in to an instance, switching back restores your session automatically. Call with no args to list known instances and see which is active.

Switch to a different organization. Returns a new access token scoped to the target organization and automatically sets it.

Trigger a synchronization operation to refresh embeddings, reindex content, or update the knowledge base state.

Synchronize and import WhatsApp Channels from a connected WhatsApp session into Neuron. Discovers channels created outside Neuron.

Synchronize all approved reflections into the bot's active knowledge base, applying learned insights to future conversations.

Synchronize contacts from all connected WhatsApp channels into the organization's contact database. Creates new contacts for unseen numbers.

Transfer control of a conversation from the bot to a human agent. The bot will stop auto-responding until the conversation is released.

Execute a dry-run test of a custom API tool with sample arguments to verify the endpoint responds correctly.

Toggle a built-in tool on or off for a specific bot. Enabled tools become available in the bot's conversations. Example tool IDs: delete_message, post_to_channel, post_status, web_search, send_direct_message, react_to_message, set_reminder, create_poll.

Toggle the featured status of a pool item. Featured items appear prominently in the marketplace. Requires admin privileges.

Remove the bot assignment from a WhatsApp channel. The channel will stop auto-responding to messages.

Unblock a previously blocked WhatsApp contact.

Permanently remove a published item from the marketplace pool. Organizations that installed this item will retain their copies.

Update an existing blog post's content, metadata, status, or SEO fields. Only provided fields are changed.

Update an existing bot's configuration. Only provided fields are modified; omitted fields remain unchanged.

Update an existing broadcast's name, message content, or media before sending. The broadcast must still be in draft status.

Update a campaign that is in 'draft' or 'rejected' status. Active or completed campaigns cannot be modified.

Update configuration of an existing WhatsApp channel. Only provided fields are modified; omitted fields remain unchanged.

Update an existing contact's details. If notes are provided, they are appended as a new structured note entry without overwriting existing notes.

Update an existing contact list's name, slug, description, criteria, or refresh schedule.

Update the description of a WhatsApp group. Requires the bot to be a group admin.

Add, remove, promote, or demote members in a WhatsApp group. Provide phone numbers or JIDs. Requires admin privileges.

Change WhatsApp group settings: 'announcement' (only admins send), 'not_announcement' (everyone sends), 'locked' (only admins edit info), 'unlocked' (everyone edits info). Requires admin.

Update the name/subject of a WhatsApp group. Requires the bot to be a group admin.

Update the content, title, folder, or source of an existing knowledge base entry.

Update the properties of an existing knowledge base such as name, description, or root instruction.

Update a member's permissions within the organization, such as conversation access. Only provided fields are changed.

Update the name or description of an existing WhatsApp Channel newsletter. Only provided fields are changed.

Update organization settings such as name, description, or configuration preferences. Only provided fields are changed.

Modify an existing outbound webhook's configuration, including its destination URL, subscribed event types, or filter prompt.

Update the metadata of a pool item you have published, such as title, description, category, or tags.

Update a specific WhatsApp privacy setting. Settings: lastSeen (all/contacts/contact_blacklist/none), online (all/match_last_seen), profilePicture (all/contacts/contact_blacklist/none), status (all/contacts/contact_blacklist/none), readReceipts (all/none), groupsAdd (all/contacts/contact_blacklist).

Update the bot's WhatsApp display name on the given channel.

Update the bot's WhatsApp profile picture from an image URL.

Update the bot's WhatsApp status/bio text.

Modify an existing custom API tool's configuration, including its endpoint, authentication, or request template.

Modify an existing inbound webhook's configuration, such as its name, event type, or processing prompt.

Update WhatsApp Business API credentials for the organization. These credentials are required for sending messages via the WhatsApp Cloud API.

Upload a text document to a knowledge base. The document will be automatically chunked and indexed for semantic search.

Upload a media file (image, video, audio, or document) by providing its base64-encoded content. Returns a URL for use in messages and broadcasts.

Verify a Nigerian bank account number via Paystack to confirm the account holder name before saving.

Verify a wallet funding transaction using the Paystack payment reference to confirm the payment was successful.

Retrieve the current wallet balance for the organization, including available and pending amounts.

Retrieve the wallet transaction history for the organization, with optional filtering by transaction type.

Check which Neuron account is currently logged in, including user name, email, role, and organization.