MB SuiteMB Suite
Menu

Referência da API · CRM

Mensagens

crm · messages · 4 operações

GET/v1/crm/conversations/{conversation_id}/messagesGET/v1/crm/messages/countPOST/v1/crm/messages/{message_id}/starPOST/v1/crm/messages/{message_id}/react
GET/v1/crm/conversations/{conversation_id}/messages

List the messages of a conversation

crm.messages.list

LeituraIdempotenteDesde 2026-11-01

Lists the messages of a conversation, newest first, paginated by cursor (limit up to 200): direction, content (the text), media, template, delivery status (sent, delivered, read, or failed with error_code and error_message), who sent it (sent_by_id and sent_by_name for a member; sent_by_ai and ai_agent_user_id for an AI agent; sent_by_system and sent_by_source for a sequence or a booking notice) and its WhatsApp message id (external_id, used by crm.whatsapp.mark_read and to quote it). A template message brings template_id (the template's name) and template_variables keyed by its {{n}} (1, 2…). Attachments (a photo, a PDF, an audio) come in media_urls as links signed for one hour that download the file without a session (media_urls_expire_at, epoch ms); list again for fresh links. A link to another site (an Instagram attachment, a product image) comes as it is, and a deleted message carries no links and nothing of what it said or showed (no text, transcription or image description). The raw platform payload is not included. Same visibility as crm.conversations.get. 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).

Escopo
crm:read
Permissão
Ver o módulo · Ação do CRM: view_inbox
Tool do MCP
crm_messages_listNa superfície completa; na compacta, mb_execute_operation com id: "crm.messages.list".

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

Parâmetros

conversation_idstringrotaobrigatório

The conversation: an id from crm.conversations.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.

Resposta

dataarray<object>
has_moreboolean
next_cursorstring

Erros

conversation_not_foundcrm_action_deniedinvalid_inputunknown_fieldauthentication_requiredscope_insufficientmodule_access_deniedoperation_not_foundrate_limitedquota_exceeded

Exemplo

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

Count the messages one person or one AI agent sent in a time window

crm.messages.count

LeituraIdempotenteDesde 2026-11-01

Counts the CRM messages (WhatsApp and Instagram, Messenger or TikTok direct messages) one author sent between since and until (epoch ms; until is exclusive and defaults to now; at most 31 days): pass exactly one of sent_by_id, a person sending from MB Suite (the screen, MIA or a key without the AI-agent mark), or ai_agent_user_id, an AI agent (the user of a key marked as an AI agent's, or an AI Team position's ai-… user). Any channel and any CRM line; failed sends count too (an attempt is an attempt). Messages on another module's line are left out, as everywhere in the CRM. It is an aggregation, not a list: one read per 1,000 messages counted plus one for the lines (and, in an organization with lines of another module, the reads of those lines' conversations active in the window and their messages), so it is the cheap way to check a daily cap before sending (for example 40 messages per agent per day). For the load of each WhatsApp line use crm.whatsapp.sent_by_line. Anyone who reads the inbox can count their own messages; counting someone else's requires view_all_performance.

Escopo
crm:read
Permissão
Ver o módulo · Ação do CRM: view_inbox
Tool do MCP
crm_messages_countNa superfície completa; na compacta, mb_execute_operation com id: "crm.messages.count".

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

Parâmetros

sinceintegerqueryobrigatório

From, epoch ms (included).

untilintegerqueryopcional

Until, epoch ms (excluded); without it, now.

ai_agent_user_idstringqueryopcional

Count what this AI agent sent: the user of a key marked as an AI agent's, or an AI Team position's ai-… user. Exactly one of ai_agent_user_id and sent_by_id.

sent_by_idstringqueryopcional

Count what this person sent from MB Suite (the screen, MIA or a key without the AI-agent mark).

Resposta

countnumber
sincenumber
untilnumber

Erros

crm_action_deniedinvalid_inputunknown_fieldauthentication_requiredscope_insufficientmodule_access_deniedoperation_not_foundrate_limitedquota_exceeded

Exemplo

curl "https://api.mb-suite.com/v1/crm/messages/count?since=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/messages/count?since=0" \
  -H "Authorization: Bearer $MB_TEST_KEY"
POST/v1/crm/messages/{message_id}/star

Star or unstar a message

crm.messages.star

EscritaIdempotenteDesde 2026-11-01

Stars (starred: true) or unstars a message of a conversation, so it shows in the starred filter of the inbox. Idempotent. A seller with restricted scope only stars messages of conversations they own or on lines they work.

Escopo
crm:write
Permissão
Editar no módulo
Tool do MCP
crm_messages_starNa superfície completa; na compacta, mb_execute_operation com id: "crm.messages.star".

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

Parâmetros

message_idstringrotaobrigatório

The message: an id from crm.messages.list.

starredbooleancorpoobrigatório

true stars it, false removes the star.

Resposta

oktrue

Erros

message_not_foundinvalid_inputunknown_fieldauthentication_requiredscope_insufficientcrm_action_deniedidempotency_key_reusedrate_limitedquota_exceeded

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/messages/{message_id}/star" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "starred": 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.

curl -X POST "https://api.mb-suite.com/v1/crm/messages/{message_id}/star" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "starred": true
}'
POST/v1/crm/messages/{message_id}/react

React to a message with an emoji

crm.messages.react

EscritaIdempotenteDesde 2026-11-01

Sets the caller's emoji reaction on a message of a conversation, replacing their previous one (one reaction per person, as in WhatsApp); an empty emoji removes it. It is an internal mark for the team inside MB Suite: it is NOT sent to WhatsApp or the contact. Idempotent: repeating the same emoji changes nothing. Returns the message's reactions after the change (emoji, user_id, user_name when known, at), the contact's own reactions from WhatsApp included. Not found if the message does not exist. A seller with restricted scope only reacts to messages of conversations they own or on lines they work.

Escopo
crm:write
Permissão
Editar no módulo
Tool do MCP
crm_messages_reactNa superfície completa; na compacta, mb_execute_operation com id: "crm.messages.react".

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

Parâmetros

message_idstringrotaobrigatório

The message: an id from crm.messages.list.

emojistringcorpoobrigatório

One emoji: it sets (or replaces) the caller's reaction; an empty string removes it.

Resposta

reactionsarray<object>

Erros

message_not_foundinvalid_inputunknown_fieldauthentication_requiredscope_insufficientcrm_action_deniedidempotency_key_reusedrate_limitedquota_exceeded

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/messages/{message_id}/react" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "emoji": "EMOJI"
}'

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/messages/{message_id}/react" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "emoji": "EMOJI"
}'