IA

Performance of the CRM AI team

crm.ai.performance

Performance of the CRM AI team (operative positions such as the Setter, the Qualifier or the Seller) for a period, start and end (both required, epoch ms): the roster, AI conversations (states) created in the period and how many are still active, meetings booked vs a human baseline (won rate of the deals created in the period with a human owner), average and median time to booking vs time to win, and why finished conversations were handed off or closed (explicit request, stalled, guardrail, no AI credits, disqualified). Reads at most 2,000 AI states and 2,000 deals; truncated: true when a cap was hit, and truncation says which: states (the AI side counts only the first 2,000 states of the period) or human_deals (the human baseline comes from the first 2,000 deals of the period, not all of them, so its rate is not comparable: narrow the period). Org-wide numbers, as in the app. Use crm.ai_team.positions.list for the positions themselves.

Escopo

crm:read

Permissão

Ver o módulo · Ação do CRM: view_performance

Tool do MCP

crm_ai_performanceNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai.performance".

Custo declarado: até 4052 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

curl "https://api.mb-suite.com/v1/crm/ai/performance?start=0&end=0" \
  -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 "https://api.mb-suite.com/v1/crm/ai/performance?start=0&end=0" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Run the AI Deal Coach on a deal

crm.ai.deal_coach

Runs the CRM's AI Deal Coach on one deal and saves its note on the deal (ai_coach_note, the note the deal's Coach card shows; it replaces the previous one). The coach is the AI agent chosen in CRM settings → AI scoring → Coach, with that block's focus, offer context and things to avoid; it reads the deal (stage and days in it, value, owner, AI score, custom fields), its company, up to 6 contacts and the last 8 activities. Returns the saved note plus its parts: summary, next_best_action, 2-3 recommendations with priority and a risk_level (low, medium, high). Use it when asked what to do next with a deal. It does not move, edit or contact anything. language (es, en, pt-BR) defaults to the caller's language. The coach must be turned on (409 coach_not_configured). Spends the organization's AI credits, charged by the tokens the model actually used, its thinking included, at the price of the model that answered (a fallback model, if one did): before calling the AI it checks that the caller's credit pool covers the call with the model that will run, and if it does not it fails with 402 ai_credits_exhausted (details.reason: insufficient_credits, category_budget or personal_limit; details.detail, when the extra credits stop it: extras_limit, the owner's monthly cap reached, or frozen) without calling the AI. An answer the model gave is charged even when it cannot be used, unless this operation says otherwise; a model that fails (an error of the AI provider) is not charged. The SDKs do not retry a 502 ai_generation_failed on their own: retrying calls the AI again, and is charged again if the AI answers. Not available in the practice organization (test keys): 409 sandbox_external_unavailable. If the AI fails, or answers with an empty note (an answer that cannot be read at all counts as empty), nothing is saved and nothing is charged (502 ai_generation_failed, or 429 external_rate_limited when the AI provider is limiting); an answer that comes back malformed is charged and nothing is saved either (502 ai_generation_failed). Takes several seconds. Not idempotent: send an Idempotency-Key to retry safely. Requires edit_deal; a seller with restricted scope only coaches deals they can work. 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

Tool do MCP

crm_ai_deal_coachNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai.deal_coach".

Custo declarado: até 50 leituras e 1 escritas por chamada (contam na cota diária). Usa uma plataforma externa (ai): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/deals/{deal_id}/ai-coach" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

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. Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.

Draft an email for a deal with AI

crm.ai.draft_email

Writes a draft of one outbound sales email for a deal with AI (Gemini Pro) and returns it: subject, plain_body and a simple html_body (p, br, strong, em, a, lists; sanitized). It uses the deal (value, status, owner, company, primary contact and email) and the subjects of its last 5 activities (never email bodies), with a tone (formal, casual, direct; default direct), an intent (follow_up by default, intro, proposal, check_in, break_up, demo_request or custom), optional additional_context (up to 1,000 characters) and an optional seed_subject to adapt. language (es, en, pt-BR) defaults to the caller's language. It saves nothing and sends nothing: to send it use crm.email.send after the person reviews it. Spends the organization's AI credits, charged by the tokens the model actually used, its thinking included, at the price of the model that answered (a fallback model, if one did): before calling the AI it checks that the caller's credit pool covers the call with the model that will run, and if it does not it fails with 402 ai_credits_exhausted (details.reason: insufficient_credits, category_budget or personal_limit; details.detail, when the extra credits stop it: extras_limit, the owner's monthly cap reached, or frozen) without calling the AI. An answer the model gave is charged even when it cannot be used, unless this operation says otherwise; a model that fails (an error of the AI provider) is not charged. The SDKs do not retry a 502 ai_generation_failed on their own: retrying calls the AI again, and is charged again if the AI answers. Not available in the practice organization (test keys): 409 sandbox_external_unavailable. If the AI fails or returns an empty draft (an answer that cannot be read counts as empty), nothing is charged (502 ai_generation_failed, or 429 external_rate_limited when the AI provider is limiting). Not idempotent: send an Idempotency-Key to retry safely. Requires send_email on the deal. 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

Tool do MCP

crm_ai_draft_emailNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai.draft_email".

Custo declarado: até 25 leituras e 3 escritas por chamada (contam na cota diária). Usa uma plataforma externa (ai): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/deals/{deal_id}/ai-email-draft" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

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. Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.

Score a deal with AI

crm.ai.score_deal

Scores a deal (0-100) with the AI agent and criteria of the deals block in CRM settings → AI scoring, using the firmographics of one of its persons (person_id; default the deal's primary person), its source channel and value, and saves the result on the deal (ai_scoring, and ai_score for sorting), replacing the previous score. The score is a hybrid: 40% rules (email, phone, company, role, source) and 60% AI; it returns score, rules_score, ai_score, recommendation (qualified, needs_review, not_qualified), a short reasoning and the rule signals. If the AI fails, the score is rules only (it says so in reasoning) and nothing is charged; if the AI answers with something that cannot be used, the score is rules only too and that answer is charged. It runs even if automatic deal scoring is off. Errors: 409 deal_without_person when the deal has no primary person and no person_id is sent; 400 person_not_in_deal when person_id is not linked to the deal. Spends the organization's AI credits, charged by the tokens the model actually used, its thinking included, at the price of the model that answered (a fallback model, if one did): before calling the AI it checks that the caller's credit pool covers the call with the model that will run, and if it does not it fails with 402 ai_credits_exhausted (details.reason: insufficient_credits, category_budget or personal_limit; details.detail, when the extra credits stop it: extras_limit, the owner's monthly cap reached, or frozen) without calling the AI. An answer the model gave is charged even when it cannot be used, unless this operation says otherwise; a model that fails (an error of the AI provider) is not charged. The SDKs do not retry a 502 ai_generation_failed on their own: retrying calls the AI again, and is charged again if the AI answers. Not available in the practice organization (test keys): 409 sandbox_external_unavailable. Not idempotent: send an Idempotency-Key to retry safely. Requires edit_deal; a seller with restricted scope only scores deals they can work. 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

Tool do MCP

crm_ai_score_dealNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai.score_deal".

Custo declarado: até 20 leituras e 1 escritas por chamada (contam na cota diária). Usa uma plataforma externa (ai): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/deals/{deal_id}/ai-score" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

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. Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.

Score a prospect with AI

crm.ai.score_prospect

Scores an inbox prospect (0-100) with the AI agent and criteria of the prospects block in CRM settings → AI scoring, using the linked contact's firmographics (when there is one), the prospect's title, custom fields, source channel and value, and saves the result on the prospect (ai_scoring, and ai_score for sorting), replacing the previous score. Hybrid: 40% rules and 60% AI; returns score, rules_score, ai_score, recommendation (qualified, needs_review, not_qualified), a short reasoning and the rule signals. If the AI fails, the score is rules only and nothing is charged; if the AI answers with something that cannot be used, the score is rules only too and that answer is charged. It runs even if automatic scoring is off for the prospect's lead source. For several prospects use crm.ai.bulk.score_prospects. Spends the organization's AI credits, charged by the tokens the model actually used, its thinking included, at the price of the model that answered (a fallback model, if one did): before calling the AI it checks that the caller's credit pool covers the call with the model that will run, and if it does not it fails with 402 ai_credits_exhausted (details.reason: insufficient_credits, category_budget or personal_limit; details.detail, when the extra credits stop it: extras_limit, the owner's monthly cap reached, or frozen) without calling the AI. An answer the model gave is charged even when it cannot be used, unless this operation says otherwise; a model that fails (an error of the AI provider) is not charged. The SDKs do not retry a 502 ai_generation_failed on their own: retrying calls the AI again, and is charged again if the AI answers. Not available in the practice organization (test keys): 409 sandbox_external_unavailable. Not idempotent: send an Idempotency-Key to retry safely. Requires edit_prospect. 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

Tool do MCP

crm_ai_score_prospectNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai.score_prospect".

Custo declarado: até 20 leituras e 1 escritas por chamada (contam na cota diária). Usa uma plataforma externa (ai): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/prospects/{prospect_id}/ai-score" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

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. Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.

Score many prospects with AI

crm.ai.bulk.score_prospects

Scores up to 50 prospects with AI, like crm.ai.score_prospect one by one (5 at a time; repeated ids count once), and saves each score on its prospect. Ids that do not exist, and prospects the matrix does not let the caller edit (another person's, for a seller), are skipped. Returns scored, failed (everything not scored) and one row per id with its status (scored, not_found, denied, failed) and score. Spends the organization's AI credits, charged by the tokens the model actually used, its thinking included, at the price of the model that answered (a fallback model, if one did): before calling the AI it checks that the caller's credit pool covers the call with the model that will run, and if it does not it fails with 402 ai_credits_exhausted (details.reason: insufficient_credits, category_budget or personal_limit; details.detail, when the extra credits stop it: extras_limit, the owner's monthly cap reached, or frozen) without calling the AI. An answer the model gave is charged even when it cannot be used, unless this operation says otherwise; a model that fails (an error of the AI provider) is not charged. The SDKs do not retry a 502 ai_generation_failed on their own: retrying calls the AI again, and is charged again if the AI answers. Not available in the practice organization (test keys): 409 sandbox_external_unavailable. The credit check covers the whole batch before the first call. Bulk: outside the app it needs a dry run (it previews how many will be scored, which are skipped and the estimated credits, without calling the AI) and then the confirm_token. Takes up to a minute with 50 prospects. Not idempotent: send an Idempotency-Key to retry safely. Requires edit access to the CRM; edit_prospect is checked per prospect.

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_bulk_score_prospectsNa superfície completa; na compacta, mb_execute_operation com id: "crm.ai.bulk.score_prospects".

Custo declarado: até 320 leituras e 50 escritas por chamada (contam na cota diária). Usa uma plataforma externa (ai): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/prospects/bulk/ai-score" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prospect_ids": [
    "PROSPECT_ID"
  ],
  "dry_run": true
}'

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. Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.