Conversas

List inbox conversations

crm.conversations.list

Lists the CRM inbox conversations (channel whatsapp; instagram, facebook —Messenger— or tiktok direct messages; or email, the AI Setter's email bridge), most recent activity first, paginated by cursor (limit up to 200). Filter by status (open by default; closed, archived or all), channel (one of those five), WhatsApp line (phone_number_id) or the person, deal, company or prospect they are linked to. phone (with its country code) returns the WhatsApp conversations with that number on every line (one per line), matched the way the CRM matches an incoming message (the Argentine 9 and the Mexican 1 are folded), so it is the way to find the right thread before writing; an invalid number is 400 invalid_phone. last_inbound_after (epoch ms) keeps only the conversations where the contact wrote after that time (last_inbound_at), for example the replies since the last check. Conversations on a line that belongs to another part of the product are not included, and a seller with restricted scope only gets the conversations they own or those on lines they work; those filters apply to the page read, so a page can bring fewer than limit while has_more is true (follow next_cursor). Each conversation brings its contact (with contact_match_key, the key two threads of the same number share), line, linked records, the assignee and the owner with their names (assignee_name, human_owner_name), the last message and the unread count. Use crm.messages.list for the messages of one conversation. With TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their fields are left out of the response (the permissions guide lists what each platform allows).

Escopo

crm:read

Permissão

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

Tool do MCP

crm_conversations_listNa superfície completa; na compacta, mb_execute_operation com id: "crm.conversations.list".

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

Parâmetros

Resposta

Erros

Exemplo

curl "https://api.mb-suite.com/v1/crm/conversations" \
  -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/conversations" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one conversation with its reply window

crm.conversations.get

Returns one inbox conversation (channel, contact, WhatsApp line, linked persons, deals, companies and prospects, owner, status, unread count, last message) plus reply_window: open (free text can be sent now), human_agent (Meta direct messages between 24 hours and 7 days: only a person replying from the screen), closed (WhatsApp more than 24 hours after the contact's last message: only an approved template) or no_window. Not found if the id does not exist, belongs to another module's line or is outside the seller's scope. With TikTok, their terms limit it through the API and the MCP: what they do not allow answers 403 platform_terms_restricted, and their fields are left out of the response (the permissions guide lists what each platform allows).

Escopo

crm:read

Permissão

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

Tool do MCP

crm_conversations_getNa superfície completa; na compacta, mb_execute_operation com id: "crm.conversations.get".

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

Parâmetros

Resposta

Erros

Exemplo

curl "https://api.mb-suite.com/v1/crm/conversations/{conversation_id}" \
  -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/conversations/{conversation_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Close a conversation

crm.conversations.close

Closes a conversation: it leaves the open inbox until the contact writes again, a message is sent in it or it is reopened. Its messages are kept. Idempotent. A seller with restricted scope only closes conversations they own or on lines they work.

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_conversations_closeNa superfície completa; na compacta, mb_execute_operation com id: "crm.conversations.close".

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/conversations/{conversation_id}/close" \
  -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/conversations/{conversation_id}/close" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Reopen a conversation

crm.conversations.reopen

Reopens a closed or archived conversation so it returns to the open inbox. Idempotent. Same scope rules as crm.conversations.close.

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_conversations_reopenNa superfície completa; na compacta, mb_execute_operation com id: "crm.conversations.reopen".

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/conversations/{conversation_id}/reopen" \
  -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/conversations/{conversation_id}/reopen" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Archive or unarchive a conversation

crm.conversations.archive

Archives a conversation, or brings it back to the open inbox with unarchive: true. An archived conversation keeps its messages and returns to the inbox by itself when the contact writes again. Idempotent. Same scope rules as crm.conversations.close.

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_conversations_archiveNa superfície completa; na compacta, mb_execute_operation com id: "crm.conversations.archive".

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/conversations/{conversation_id}/archive" \
  -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/conversations/{conversation_id}/archive" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Set the inbox assignee of a conversation

crm.conversations.assign

Sets the inbox assignee (assignee_id, a member of the organization) of a conversation. This is not the responsible seller shown in the inbox, which follows the owner of the linked deal, prospect or person (change that owner instead). Idempotent. A seller with restricted scope only assigns conversations they own or on lines they work.

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_conversations_assignNa superfície completa; na compacta, mb_execute_operation com id: "crm.conversations.assign".

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/conversations/{conversation_id}/assign" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "assignee_id": "ASSIGNEE_ID"
}'

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/conversations/{conversation_id}/assign" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "assignee_id": "ASSIGNEE_ID"
}'

Find and link the CRM person of a conversation by phone

crm.conversations.resolve_person

Finds the CRM person whose phones include the given number (it also tries the Argentina 9 and Mexico 1 mobile variants, like the inbound webhook) and links them to the conversation if they were not linked yet. Returns person_id, or null when no person has that phone. Idempotent; it never creates persons (use crm.persons.create).

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_conversations_resolve_personNa superfície completa; na compacta, mb_execute_operation com id: "crm.conversations.resolve_person".

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/conversations/{conversation_id}/resolve-person" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "phone": "PHONE"
}'

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/conversations/{conversation_id}/resolve-person" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "phone": "PHONE"
}'

Start a WhatsApp conversation with a first text message

crm.conversations.start

Starts a WhatsApp conversation with a phone number (E.164, with country code) by sending a first free-text message from a line (from_phone_number_id, default: the organization's first active WhatsApp line), optionally linked to a person (person_id) and a deal (deal_id). Both are checked before anything is sent: they must exist in this organization and be visible to the caller (deal_not_found or person_not_found, also for what a seller with restricted scope cannot see), a seller with restricted scope only links a deal they work (crm_action_denied with edit_deal for one they can only see), with both the person must be the deal's primary person or one of its persons (person_not_in_deal), a merged deal is deal_merged, and a merged person is replaced by the person they were merged into. If that number already has a conversation on that line it is reused and reopened (the links only go to a new conversation). Meta only delivers free text within 24 hours of the contact's last message: for a cold contact use crm.whatsapp.send_template instead. To a person marked «Do not contact» or unsubscribed it still goes out (free text only reaches a contact who wrote in the last 24 hours, so it is a reply), and the response carries do_not_contact. Requires send_whatsapp; a seller with restricted scope only starts from lines they work. From a line that belongs to another part of the product (not the CRM) it needs that part's edit permission and its write scope instead of the CRM's, and the conversation it opens or reuses belongs to that part. From such a line nothing of the CRM is linked: deal_id and person_id are refused (400 invalid_input) and the deals and persons of the CRM are not touched. With an API key marked as an AI agent's (an owner or admin sets it on the key; it is never chosen per call), the message is recorded as sent by AI, like the AI Setter's (crm.messages.list marks it as sent by AI, with the key's user as its AI agent), the AI badge in the inbox, and it counts as AI, not as a person, in reports and in caps (crm.messages.count with ai_agent_user_id). Its dry run checks the line, the recipient and the links without calling Meta, and warns when the 24-hour window of that number's conversation on that line is closed.

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_conversations_startNa superfície completa; na compacta, mb_execute_operation com id: "crm.conversations.start".

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/conversations" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "PHONE",
  "text": "TEXT",
  "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.