Lists the positions of the CRM AI team ordered as in CRM settings → AI team: id, type (setter, qualifier, seller, prospect_qualifier, deal_qualifier, deal_coach), name, status (active, inactive, archived), enabled, the AI agent behind it and, for operative positions (setter, qualifier, seller), the virtual CRM user ai-<its id> that owns the deals and prospects it works. The scoring positions carry their criteria inside. Archived positions are left out unless include_archived. With include_workload, each operative position also brings workload: how many AI states it works now (live: in discovery, qualifying, proposing_slots, awaiting_response or paused) and in total (two counts per position); list them with crm.ai_team.states.list. To create, change or turn on positions use crm.ai_team.positions.create, update and set_enabled; to hand a record to one, crm.ai_team.positions.assign.
Escopo
crm:read
Permissão
Ver o módulo · Ação do CRM: view_inbox
Tool do MCP
crm_ai_team_positions_listNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai_team.positions.list".
Custo declarado: até 152 leituras e 0 escritas por chamada (contam na cota diária).
Parâmetros
include_archivedbooleanqueryopcional
Also list the archived positions (left out by default, as on the screen).
Padrão: false
include_workloadbooleanqueryopcional
Also count, for each operative position (setter, qualifier, seller), the AI states it works: workload.live (in a live phase: discovery, qualifying, proposing_slots, awaiting_response or paused) and workload.total (all, also the closed ones). Two counts per position.
Returns one AI team position by id. With include_config, also the working config of an operative position (Setter, Qualifier or Seller): assignments to humans, fields to capture, qualified and disqualified criteria, post-handoff mission, knowledge files, channels, templates, working schedule and advanced settings (config is null for the scoring positions, whose config lives inside the position). booking_email (Setter only) is what the Setter enforces about the lead's email to book: absent means required; optional asks once and books anyway; skip books with name and phone — this, not the Email row in fields_to_capture, is the rule. config.file_knowledge lists its knowledge entries (each entry's id is what crm.ai_team.knowledge.delete takes). With include_workload, position.workload counts the AI states it works (live and total). With include_brain, brain is the agent its AI really uses on each turn, and chosen_in says where it comes from: its own agent (ai_agent_id: an organization agent, or an MB Suite agent that talks to leads); when it has none or cannot use it (configured_agent_missing), the default agent the organization chose for that type of position in the AI areas; and otherwise MB Suite's agent for its type. null for the scoring positions and the coach. An organization agent restricted to roles or members that leave the caller out (as in ai.agents.list) is not named: brain says source organization_agent with agent_id null and name and resolved_name empty. To change the position use crm.ai_team.positions.update (with only what changes, or the whole configuration).
Escopo
crm:read
Permissão
Ver o módulo · Ação do CRM: view_inbox
Tool do MCP
crm_ai_team_positions_getNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai_team.positions.get".
Custo declarado: até 14 leituras e 0 escritas por chamada (contam na cota diária).
Parâmetros
position_idstringrotaobrigatório
The AI position: an id of crm.ai_team.positions.list.
include_configbooleanqueryopcional
Also bring the working configuration of an operative position (setter, qualifier, seller), with its knowledge entries.
Padrão: false
include_workloadbooleanqueryopcional
Also count, for each operative position (setter, qualifier, seller), the AI states it works: workload.live (in a live phase: discovery, qualifying, proposing_slots, awaiting_response or paused) and workload.total (all, also the closed ones). Two counts per position.
Padrão: false
include_brainbooleanqueryopcional
Also resolve the effective brain of an operative position as its AI does on each turn: its own agent (ai_agent_id: one of the organization, or one of MB Suite of the CRM's WhatsApp channel); when it has none or that agent cannot be used, the organization's default agent for its type in the AI areas (only one of the CRM's WhatsApp channel that is not a draft); and otherwise MB Suite's default system agent for its type (crm_setter, crm_qualifier or crm_seller, falling back to crm_setter). chosen_in says which one: position, areas or type_default.
Returns the AI state of one deal or prospect worked by an AI team position: goal, phase (discovery, qualifying, proposing_slots, awaiting_response, booked, disqualified, handed_off, handed_off_by_human, paused), goal progress (fields_captured keyed as the position's fields_to_capture, meeting proposed or booked), the running conversation summary, next wake-up and its reason, follow-up counters, last inbound and outbound and pause info. The state id is deal-<deal id> or prospect-<prospect id>. Not found if it does not exist or the caller cannot see that deal's or prospect's details (seller scope; a viewer, only their deals).
Escopo
crm:read
Permissão
Ver o módulo · Ação do CRM: view_inbox
Tool do MCP
crm_ai_team_states_getNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai_team.states.get".
Custo declarado: até 2 leituras e 0 escritas por chamada (contam na cota diária).
Parâmetros
state_idstringrotaobrigatório
The AI state of a record: an id of crm.ai_team.states.list (deal-<deal_id> or prospect-<prospect_id>).
Resposta
idstring
deal-<deal id> or prospect-<prospect id>.
ai_agent_user_idstring
The position's virtual user (ai-<position id>), the record's owner while the AI works it.
ai_agent_typestring
position_idstring
entityobject
The deal or prospect the AI works.
goalstring
phasestring
discovery, qualifying, proposing_slots, awaiting_response, booked, disqualified, handed_off, handed_off_by_human or paused.
goal_progressobject
created_atnumber
updated_atnumber
contact_idstring | null
The person it talks to (crm.persons.get).
conversation_idstring | null
The conversation it works in (crm.conversations.get).
conversation_idsarray<string>
conversation_summarystring
The running summary of the conversation the AI keeps (free text written by the AI).
next_run_atnumber | null
When the AI wakes up next (epoch ms).
next_run_reasonstring | null
pending_inboundany
The contact's message waiting for the AI's next turn.
turns_totalnumber
failed_runsnumber
consecutive_follow_ups_since_last_replynumber
follow_up_channels_since_last_replyarray<string>
channel_decisionobject | null
delivery_failure_countnumber
last_inbound_atnumber | null
last_outbound_atnumber | null
last_turn_atnumber | null
paused_untilnumber | null
paused_by_idstring | null
paused_by_namestring | null
Who paused it (null if no longer a member).
paused_reasonstring | null
booking_alert_sent_atnumber | null
simulatedboolean
A state of the practice organization: no turn ever runs for it.
Lists the AI states of one operative AI position (position_id, required): one per deal or prospect it works or worked, newest first, paginated by cursor (limit up to 200, default 50); filter with phase (discovery, qualifying, proposing_slots, awaiting_response, booked, disqualified, handed_off, handed_off_by_human, paused). Each item brings the state id (deal-<deal id> or prospect-<prospect id>), the entity (type and id, as in crm.ai_team.states.get), goal, phase, live (the AI still works it), goal progress (fields_captured keyed as the position defines them, meeting proposed or booked), the start channel it chose, next wake-up, turn and follow-up counters, delivery failures, last inbound, outbound and turn, pause info and simulated (a state of the practice organization). It leaves out what holds free text: the running conversation summary, the reason of each decision or pause and the pending inbound; read one state with crm.ai_team.states.get for them, and its log with crm.ai_team.turns.list. Same visibility as crm.ai_team.states.get, decided per page: a seller with restricted scope, or a viewer (only their deals), gets only the states of records they can see, and without the connected content permission the states that worked by email are left out; so a page can bring fewer than limit while has_more is true: follow next_cursor. To count them per position use crm.ai_team.positions.list asking for the workload. 404 ai_position_not_found if the position does not exist; a scoring position or the deal coach gives 409 ai_position_not_operative (they work no deals or prospects, so they have no AI states).
Escopo
crm:read
Permissão
Ver o módulo · Ação do CRM: view_inbox
Tool do MCP
crm_ai_team_states_listNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai_team.states.list".
Custo declarado: até 403 leituras e 0 escritas por chamada (contam na cota diária).
Parâmetros
position_idstringqueryobrigatório
The operative AI position whose states to list (crm.ai_team.positions.list).
limitintegerqueryopcional
How many items this page brings at most (see the maximum and the default in the schema).
Padrão: 50
cursorstringqueryopcional
The next_cursor of the previous page, exactly as it came (only for the same list and filters); without it, the first page.
Lists the turns of an AI state, newest first (the AI log of a deal or prospect): trigger (inbound, cron, on_assignment, manual, poke, resumed), the model's reasoning summary, the tool calls with their arguments, results and status, the state snapshot after the turn and the tokens and credits it cost. The full chain of thought is left out unless include_full_reasoning. Paginated by cursor (limit up to 200, default 50). Same visibility as crm.ai_team.states.get: not found if the state is out of the caller's scope.
Escopo
crm:read
Permissão
Ver o módulo · Ação do CRM: view_inbox
Tool do MCP
crm_ai_team_turns_listNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai_team.turns.list".
Custo declarado: até 204 leituras e 0 escritas por chamada (contam na cota diária).
Parâmetros
state_idstringrotaobrigatório
The AI state of a record: an id of crm.ai_team.states.list (deal-<deal_id> or prospect-<prospect_id>).
limitintegerqueryopcional
How many items this page brings at most (see the maximum and the default in the schema).
Padrão: 50
cursorstringqueryopcional
The next_cursor of the previous page, exactly as it came (only for the same list and filters); without it, the first page.
include_full_reasoningbooleanqueryopcional
Also bring each turn's full reasoning (long): by default only its summary.
Create an operative AI position of the CRM AI team
crm.ai_team.positions.create
EscritaDesde 2026-11-01
Creates an operative position of the CRM AI team with its working configuration: a Setter (position_type setter: talks to leads, qualifies them and books a meeting with the team), a Qualifier (qualifier: qualifies and hands the lead to a person) or a Seller (seller: sells over WhatsApp from a synced catalog). It is born turned OFF unless payload.enabled is true, with its own virtual CRM user ai-<position_id> that can own deals and prospects. payload: name, description, ai_agent_id (the AI agent behind it, which holds its persona and knowledge: an agent of ai.agents.list with channel whatsapp_crm, or one of MB Suite as sys_<key> with a key of ai.system_agents.list of that channel, such as sys_crm_setter; null = the CRM's default one), assignments.primary_human_user_id (the person in charge, required: a member of the organization or of its CRM team; escalate_to_user_id, deal_owner_user_id, booking_calendar_user_id, booking_event_type_id and email_from_user_id fall back to that person), fields_to_capture (what it asks the lead), booking_email (Setter only: required, optional or skip the lead's email to book), qualified_criteria and disqualified_criteria, post_handoff_mission (Qualifier only: what the person does after the handoff), qualified_pipeline_id (where it converts qualified prospects into deals; null = it only works deals), channels (whatsapp, email, booking, allowed_line_ids of the CRM's WhatsApp lines —left out = all of them—, default_outbound_line_id, preferred_outbound_channel, rotation, social networks with their allowed accounts), hsm (approved WhatsApp templates it may use outside the 24-hour window), schedule (inbound and outbound modes and business hours with their timezone), advanced (follow-up limits, out-of-window behavior and follow-up cadence) and seller_config (Seller only: order_taking or ecommerce, catalogs). What a key leaves out of channels, hsm, schedule (in the organization's timezone), advanced and fields_to_capture takes the values the app uses for a new position of that type. It works no lead until one is assigned to it (crm.ai_team.positions.assign) or an assignment rule sends it leads. Up to 25 AI positions per organization (409 limit_reached). Created off (the default) it attends no one and runs directly. Created on (payload.enabled true) it starts attending the leads it is given, so outside the app it needs a dry run (dry_run true: it returns what it creates and a confirm_token) and then the same call with that confirm_token. Errors: 400 ai_position_config_invalid when a rule of the configuration fails (no person in charge, no channel on, booking on without that person's booking enabled, a WhatsApp line that is not of the CRM, a social account not connected in the Social Inbox, templates missing for force_hsm, no business day, a catalog that does not exist; param says where), 400 ai_agent_not_found (ai_agent_id is not a saved agent of the organization, nor an MB Suite agent that exists and is not hidden) and 400 ai_agent_not_eligible (its channel is not whatsapp_crm), checked only when ai_agent_id changes, 400 owner_not_member (a person in assignments that is not of the organization), 404 pipeline_not_found. Returns the position and its configuration. Requires manage_ai_config (owner, admin or CRM admin). With TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).
Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação. Nesta, só quando: payload.enabled is true (the new AI position starts attending the leads it is given right away and may write to them; created off, the default, it attends no one).
Escopo
crm:write
Permissão
Editar no módulo · Ação do CRM: manage_ai_config
Tool do MCP
crm_ai_team_positions_createNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai_team.positions.create".
Custo declarado: até 85 leituras e 3 escritas por chamada (contam na cota diária).
Parâmetros
payloadobjectcorpoobrigatório
The position's configuration, the one CRM → AI Team edits: what is left out takes the values a new position opens with on the screen. It is born turned off unless enabled is true.
position_typeenumcorpoopcional
The kind of position: setter (qualifies and books a meeting), qualifier (qualifies and hands over) or seller (sells by WhatsApp). It cannot change later.
Change an operative AI position of the CRM AI team
crm.ai_team.positions.update
EscritaIdempotenteDesde 2026-11-01
Changes an operative AI position (Setter, Qualifier or Seller). Send either updates —only what changes: each part sent replaces that part whole (channels, schedule, assignments…) and null removes description, post_handoff_mission or seller_config— or payload —the whole configuration, as the app's drawer sends it (read it with crm.ai_team.positions.get include_config plus the position's name, description, enabled and ai_agent_id); optional parts left out are removed—, never both. The type never changes and its knowledge entries are kept. enabled true turns it on and resumes the follow-ups the pause left asleep; enabled false stops it. The same rules as crm.ai_team.positions.create; a person in charge is only checked again when it changes. It changes how an AI agent attends leads, so outside the app it always needs a dry run (dry_run true: it returns what changes and a confirm_token) and then the same call with that confirm_token. The dry run says which parts change, whether it stays on and how many records it works. A scoring position or the deal coach gives 409 ai_position_not_operative (use the app); 404 ai_position_not_found. Errors: 400 ai_position_config_invalid when a rule of the configuration fails (no person in charge, no channel on, booking on without that person's booking enabled, a WhatsApp line that is not of the CRM, a social account not connected in the Social Inbox, templates missing for force_hsm, no business day, a catalog that does not exist; param says where), 400 ai_agent_not_found (ai_agent_id is not a saved agent of the organization, nor an MB Suite agent that exists and is not hidden) and 400 ai_agent_not_eligible (its channel is not whatsapp_crm), checked only when ai_agent_id changes, 400 owner_not_member (a person in assignments that is not of the organization), 404 pipeline_not_found. Returns the position, its configuration and changes (the parts that changed). Requires manage_ai_config. With TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).
Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.
Escopo
crm:write
Permissão
Editar no módulo · Ação do CRM: manage_ai_config
Tool do MCP
crm_ai_team_positions_updateNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai_team.positions.update".
Custo declarado: até 2085 leituras e 2003 escritas por chamada (contam na cota diária).
Parâmetros
position_idstringrotaobrigatório
The AI position: an id of crm.ai_team.positions.list.
payloadobjectcorpoopcional
The whole configuration, as crm.ai_team.positions.get returns it with include_config: an optional part left out is removed. Exactly one of payload and updates.
updatesobjectcorpoopcional
Only what changes, over what is saved: each key sent replaces that whole part, and null removes an optional one. Exactly one of payload and updates.
Turns a position of the CRM AI team on (enabled true) or off (false) without touching the rest of its configuration, as the switch of the AI team table. An operative position (Setter, Qualifier, Seller) that comes back on resumes the follow-ups the pause left asleep (rearmed says how many) and works whatever is assigned to it; turned off it writes to no lead until it is on again. A scoring position (prospect_qualifier, deal_qualifier) or the deal coach also updates the scoring block the scoring engine reads; turning a scoring position on from an API key or an OAuth app gives 403 ai_scoring_screen_only (it queues up to 500 records for background AI scoring that a key cannot meter yet: turn it on in the app), turning it off works. Setting the state it already has changes nothing (changed false). It changes how an AI agent attends leads, so outside the app it always needs a dry run (dry_run true: it returns what changes and a confirm_token) and then the same call with that confirm_token. 404 ai_position_not_found. Returns the position. Requires manage_ai_config. With TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted (the permissions guide lists what each platform allows).
Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.
Escopo
crm:write
Permissão
Editar no módulo · Ação do CRM: manage_ai_config
Tool do MCP
crm_ai_team_positions_set_enabledNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai_team.positions.set_enabled".
Custo declarado: até 2002 leituras e 2002 escritas por chamada (contam na cota diária).
Parâmetros
position_idstringrotaobrigatório
The AI position: an id of crm.ai_team.positions.list.
Sets the order of the CRM AI team table: ordered_ids in the visual order, position = index (the app sends the active positions first, then the inactive ones). It only changes how the table lists them: no position works differently. Ids that do not exist are skipped. Returns how many were updated and skipped. Requires manage_ai_config.
Escopo
crm:write
Permissão
Editar no módulo · Ação do CRM: manage_ai_config
Tool do MCP
crm_ai_team_positions_reorderNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai_team.positions.reorder".
Custo declarado: até 200 leituras e 200 escritas por chamada (contam na cota diária).
Parâmetros
ordered_idsarray<string>corpoobrigatório
The position ids in the order of the AI Team table (place = index); ids that do not exist are skipped.
Adds a text to the knowledge of an operative AI position (Setter, Qualifier or Seller): it is stored as <title>.txt among its knowledge files (it shows and downloads like them), split into fragments and indexed with AI, and the position looks it up from its next turn to answer leads. Up to 50,000 characters, and up to 5 entries per position between files and texts (409 limit_reached, details.resource ai_position_knowledge). Spends the organization's AI credits for the indexing (about 1 credit per 40,000 characters): before calling the AI it checks that the caller's credit pool covers it, and if it does not it fails with 402 ai_credits_exhausted (details.reason) without calling the AI; a 502 ai_generation_failed stored and charged nothing. Files (PDF, Word, spreadsheets) are uploaded in the app. It changes how an AI agent attends leads, so outside the app it always needs a dry run (dry_run true: it returns what changes and a confirm_token) and then the same call with that confirm_token. The dry run says how many fragments and the estimated credits. In the practice organization it is simulated: the same checks and the same split into fragments, and the entry is listed on the position marked simulated (no file stored), without calling the AI and with credits_charged 0. Errors: 404 ai_position_not_found, 409 ai_position_not_operative, 409 ai_position_not_configured, 400 knowledge_text_empty. Not idempotent. Returns the entry, its fragments and the credits charged. Requires manage_ai_config.
Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.
Escopo
crm:write
Permissão
Editar no módulo · Ação do CRM: manage_ai_config
Tool do MCP
crm_ai_team_knowledge_add_textNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai_team.knowledge.add_text".
Custo declarado: até 6 leituras e 41 escritas por chamada (contam na cota diária). Usa uma plataforma externa (ai): conta na cota de operações externas.
Parâmetros
position_idstringrotaobrigatório
The AI position: an id of crm.ai_team.positions.list.
titlestringcorpoobrigatório
The entry's name in the position's knowledge, up to 120 characters (saved as <title>.txt).
textstringcorpoobrigatório
The text the position learns from, up to 50000 characters.
Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.Na prática esta operação é simulada: nada é enviado e a resposta traz simulated: true.
Remove an entry from the knowledge of an AI position
crm.ai_team.knowledge.delete
IrreversívelIdempotenteDesde 2026-11-01
Removes one knowledge entry, a file or a text (entry_id, from crm.ai_team.positions.get with include_config: config.fileKnowledge), from an operative AI position: its indexed fragments, its stored file and its row; the position stops using it from its next turn. It does not go to the trash and cannot be undone (upload it again). Removing an entry that is not there changes nothing (changed false). Outside the app it needs a dry run and its confirm_token, and a key allowed to delete. 404 ai_position_not_found, 409 ai_position_not_operative. Returns how many fragments were removed. Requires manage_ai_config.
Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.
Escopo
crm:writee «Permitir exclusões» (crm:delete no OAuth)
Permissão
Editar no módulo · Ação do CRM: manage_ai_config
Tool do MCP
crm_ai_team_knowledge_deleteNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai_team.knowledge.delete".
Custo declarado: até 1002 leituras e 1001 escritas por chamada (contam na cota diária).
Parâmetros
position_idstringrotaobrigatório
The AI position: an id of crm.ai_team.positions.list.
entry_idstringrotaobrigatório
The knowledge entry: an id of the position's knowledge (crm.ai_team.positions.get with include_config).
Put a deal or prospect in charge of an AI position
crm.ai_team.positions.assign
EscritaIdempotenteDesde 2026-11-01
Puts a deal (deal_id) or a prospect (prospect_id) in charge of an operative AI position, as choosing the position as the record's owner in the app: the owner becomes the position's virtual user ai-<position_id>, the record's AI state starts and its first turn runs now, synchronously (several seconds), so it may write to the lead right away over the position's channels (WhatsApp, email, social networks), spending AI credits like every turn of the position. Without AI credits for a turn in the organization's pool (or with the subscription that pays them blocked), that turn does not call the AI and writes to no one: the record goes at once to the position's escalation person (or to whoever the lead source's assignment rule picks), so owner_id already comes back as that person and the state as handed_off with next_run_reason no_ai_credits (or ai_subscription_required). A record handed off for lack of credits goes back to the position by itself when the pool covers a turn again (the renewal, extra credits, a new split or removed category caps; checked every 15 minutes, up to 30 days after the handoff), unless someone on the team touched it since (a message, an activity or a change to the record): that one stays with whoever has it. When the record's person (the deal's primary person or the prospect's person) is marked «Do not contact» or unsubscribed, the first turn does not run: the AI never writes first to them, and the returned state waits with next_run_reason do_not_contact until the person writes (the dry run says so). If the position already works the record, nothing changes (changed false). The position must be on (409 ai_position_inactive) and configured (409 ai_position_not_configured); a scoring position or the coach gives 409 ai_position_not_operative; if another AI position is working the record, 409 ai_state_conflict (take it over first with crm.ai_team.take_over). It changes how an AI agent attends leads, so outside the app it always needs a dry run (dry_run true: it returns what changes and a confirm_token) and then the same call with that confirm_token. The dry run says who works the record today. In the practice organization it is simulated: the same checks, the owner becomes ai-<position_id> and the AI state is created marked simulated, with no next run, without running any turn, writing to anyone or charging credits. 404 ai_position_not_found, deal_not_found or prospect_not_found. Returns owner_id, the record's owner after that first turn (ai-<position_id>, or the person the turn handed it to), and the AI state (phase, next run). Requires edit_deal on the deal (a seller with restricted scope, only deals they can work) or, for a prospect, a manager (owner, admin, CRM admin or sales manager), as changing a prospect's owner.
Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.
Escopo
crm:write
Permissão
Editar no módulo
Tool do MCP
crm_ai_team_positions_assignNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai_team.positions.assign".
Custo declarado: até 91 leituras e 20 escritas por chamada (contam na cota diária). Usa uma plataforma externa (ai): conta na cota de operações externas.
Parâmetros
position_idstringrotaobrigatório
The AI position: an id of crm.ai_team.positions.list.
deal_idstringcorpoopcional
The deal (crm.deals.list). Exactly one of deal_id and prospect_id.
prospect_idstringcorpoopcional
The prospect (crm.prospects.list). Exactly one of deal_id and prospect_id.
Resposta
position_idstring
entityobject
owner_idstring
The record's owner after the first turn: ai-<position_id>, or the person the turn handed the record to (no AI credits for the turn, a guardrail).
Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.Na prática esta operação é simulada: nada é enviado e a resposta traz simulated: true.
A person takes control of a deal (deal_id) or a prospect (prospect_id) that an AI position is working: the owner becomes that person (new_owner_id, default the caller: a member of the organization, or for a prospect also someone of its CRM team, never an AI) through the same change as crm.deals.update or crm.prospects.update (the record's history, the new owner's notification and, for a deal, crm.deal.updated), the AI state ends as handed_off_by_human so the AI does not write to the lead again, the conversation it is taken from (conversation_id, optional: it must be one of the record's conversations) loses the AI mark, the record's conversations show the new owner and a note with the AI's summary so far is added to its timeline (reason, optional, goes to the audit). It is the brake: it runs without confirmation. Giving it to someone else (new_owner_id other than the caller) needs a CRM manager: an owner, an admin, a CRM admin or a sales manager. The record's edit permission applies with the AI counted as no owner: a seller takes what the AI works but not a teammate's record, and with a restricted scope only a deal in a pipeline they work, never a prospect an AI position owns (403 crm_action_denied with edit_deal or edit_prospect), and an unassigned prospect the AI works only when its person and company are ones they can see: their own, unassigned, or of a deal of theirs (403 prospect_contact_not_visible). If the record is already that person's and no AI works it, nothing changes (changed false); if no AI works it and it belongs to someone else, 409 ai_not_in_charge (change owners with crm.deals.update or crm.prospects.update). 404 deal_not_found or prospect_not_found if it does not exist or the caller cannot see it; 404 conversation_not_found or 400 conversation_not_of_record for a conversation_id that is not one of the record's conversations; 400 owner_not_member. Returns the state id and the new owner. Requires full access to the CRM.
Escopo
crm:write
Permissão
Editar no módulo
Tool do MCP
crm_ai_team_take_overNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai_team.take_over".
curl-X POST "https://api.mb-suite.com/v1/crm/ai-team/take-over" \
-H"Authorization: Bearer $MB_API_KEY"
Testar com a sua API key de teste
Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.
curl-X POST "https://api.mb-suite.com/v1/crm/ai-team/take-over" \
-H"Authorization: Bearer $MB_TEST_KEY"
POST/v1/crm/ai-team/states/{state_id}/pause
Pause the AI in a deal or prospect
crm.ai_team.states.pause
EscritaIdempotenteDesde 2026-11-01
Pauses the AI in one deal or prospect (state_id deal-<deal id> or prospect-<prospect id>, see crm.ai_team.states.get): it runs no more turns —neither the follow-up cycle nor incoming messages— until someone resumes it with crm.ai_team.states.resume, and it keeps the phase it was in. It is a brake: it runs without confirmation. reason (optional) goes to the AI log. Pausing a paused one changes nothing (changed false); a conversation the AI already closed (booked, disqualified, handed off) gives 409 ai_state_closed. 404 ai_state_not_found if it does not exist or is out of the caller's scope. Requires manage_ai_config.
Escopo
crm:write
Permissão
Editar no módulo · Ação do CRM: manage_ai_config
Tool do MCP
crm_ai_team_states_pauseNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai_team.states.pause".
Custo declarado: até 8 leituras e 1 escritas por chamada (contam na cota diária).
Parâmetros
state_idstringrotaobrigatório
The AI state of a record: an id of crm.ai_team.states.list (deal-<deal_id> or prospect-<prospect_id>).
curl-X POST "https://api.mb-suite.com/v1/crm/ai-team/states/{state_id}/pause" \
-H"Authorization: Bearer $MB_API_KEY"
Testar com a sua API key de teste
Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.
curl-X POST "https://api.mb-suite.com/v1/crm/ai-team/states/{state_id}/pause" \
-H"Authorization: Bearer $MB_TEST_KEY"
POST/v1/crm/ai-team/states/{state_id}/resume
Resume the AI in a paused deal or prospect
crm.ai_team.states.resume
EscritaDesde 2026-11-01
Resumes the AI in a paused deal or prospect (state_id): it goes back to the phase it had and the next cycle (every 5 minutes) runs its turn, which may write to the lead (not when the lead's person is marked «Do not contact» or unsubscribed: that turn does not run, and the state waits with next_run_reason do_not_contact until the person writes; and without AI credits for a turn that turn does not call the AI and the record goes to the position's escalation person). It changes how an AI agent attends leads, so outside the app it always needs a dry run (dry_run true: it returns what changes and a confirm_token) and then the same call with that confirm_token. A state that is not paused gives 409 ai_state_not_paused; 404 ai_state_not_found if it does not exist or is out of the caller's scope. Not idempotent (a second call finds it running). Returns the restored phase. Requires manage_ai_config.
Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.
Escopo
crm:write
Permissão
Editar no módulo · Ação do CRM: manage_ai_config
Tool do MCP
crm_ai_team_states_resumeNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai_team.states.resume".
Custo declarado: até 10 leituras e 1 escritas por chamada (contam na cota diária).
Parâmetros
state_idstringrotaobrigatório
The AI state of a record: an id of crm.ai_team.states.list (deal-<deal_id> or prospect-<prospect_id>).
