Social direct messages

Reply to an Instagram, Messenger or TikTok DM that is in the CRM (CRM → Messages)

crm.social_dm.send

Replies with text in an Instagram, Messenger or TikTok direct-message conversation that is in the CRM (CRM → Messages: one passed from the Social Inbox or linked to a lead), through the connected account that received it, and records it in the conversation (it goes back to the open CRM inbox). A direct message that is still only in the Social Inbox is answered with social_inbox.items.reply. Meta accepts free text within 24 hours of the contact's last message; only a person replying from the screen can extend it up to 7 days, never an integration. The text limit depends on the network (Instagram counts bytes). Social conversations cannot be started from here: the contact writes first. The dry run checks what the send checks before going out (the connected account, the network's text limit and the reply window) without calling the network. When the network does not confirm the reply it answers external_outcome_unknown (it may have gone out: check the conversation before sending it again). Requires send_whatsapp on the conversation's owner (a member only in conversations they own or without owner). 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). 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).

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

crm:write

Permission

Edit in the module

MCP tool

crm_social_dm_sendOn the full surface; on the compact one, mb_execute_operation with id: "crm.social_dm.send".

Declared cost: up to 6 reads and 6 writes per call (they count against the daily quota). Touches an external platform (meta): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/crm/conversations/{conversation_id}/social-dm" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "TEXT",
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.