send_message
Send a message on behalf of an agent's user or an SMB across WhatsApp (free during launch), SMS, email, or voice. Five message types: transactional, reminder, follow_up, notification, marketing. Every send routes through a non-bypassable compliance gate (TCPA, GDPR, CASL, PDPL across 26 jurisdictions) that enforces opt-in consent for marketing/promotional content — marketing without recorded consent is rejected at runtime with a structured compliance_violation receipt. Channel is abstracted: specify intent and recipient; the service selects and falls back across channels.
EXAMPLE USER QUERIES THAT MATCH THIS TOOL: user: "Text the salon I'll be 10 minutes late" -> call send_message({"recipient": {"id_type": "smb_id", "id_value": "smb_xyz"}, "message_type": "notification", "content": {"body": "Running about 10 minutes late for my appointment."}, "preferred_channel": "sms"}) user: "Email the dentist about insurance" -> call send_message({"recipient": {"id_type": "email", "id_value": "front-desk@example-dental.com"}, "message_type": "transactional", "content": {"body": "Do you accept Cigna insurance?"}, "preferred_channel": "email"})
WHEN TO USE: Use to: (a) confirm a booking the agent just made, (b) reply to a customer who messaged the SMB first, (c) follow up on a quote the user requested, (d) send appointment reminders the SMB owes its customer, (e) send marketing messages to recipients who have opted in (with consent_record_id). The gate verifies consent on every send. WHEN NOT TO USE: Do NOT use for OTPs or critical transactional confirmations — use send_transactional_confirmation. Do NOT attempt to send marketing without a consent_record_id pointing at a real opt-in — the gate will reject the send and log a compliance_violation. Do NOT attempt bulk / list-based / drip / cold outreach — those are out of scope and the rate limiter will throttle abuse. COST: from $0.02 per_call_variable (see preview_cost for exact) LATENCY: ~800ms EXECUTION: sync_fast (use get_outcome to retrieve result)
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| recipient | Yes | ||
| business_id | No | Optional stable id for the recipient business. Enables global demand shaping (we rate-limit total inbound across ALL agents so businesses stay responsive instead of blocking us). | |
| send_at_iso | No | NOT SUPPORTED YET. We do not schedule messages. Supplying a time more than 2 minutes in the future is REFUSED (reason_code scheduling_not_supported) rather than sent immediately, which is what used to happen. Call send_message at the moment you want delivery, or omit this field. | |
| message_type | Yes | Intent tag for the message. Five permitted types. 'marketing' is allowed only when paired with a valid consent_record_id; the compliance gate verifies the consent at send time and rejects (compliance_violation receipt) if it's missing, expired, or revoked. | |
| on_behalf_of | No | Who this message is FOR (your end-user's name/label). On WhatsApp this opens a tracked conversation and travels in-message as '#4821 for Sara (via HatchLoop)', so the business knows who it is talking to and their reply is matched back to this exact request instead of guessed. Strongly recommended for two-way channels. | |
| idempotency_key | No | Optional client-supplied key for safe retries. Replaying the same key within 24h returns the original receipt - the operation is NOT re-executed and NOT re-charged. | |
| preferred_channel | No | auto |