Send a message to a lead
Sends a message to the lead on their most recent conversation, from the owning agent's channel. This reaches a real person — it requires write and the approval grant. The grant is a separate boolean, not a rung: an admin key without it is still refused.
Side effect: a successful send pauses the AI on this lead, exactly as replying from the dashboard does. Resume it with PATCH /api/v1/leads/{leadId} and { "ai_paused": false }.
Pass an Idempotency-Key header to make retries safe: a repeat with the same key returns 200 with deduplicated: true and does not re-send. Without one, an identical message within a 5-minute window is still deduplicated.
WhatsApp Cloud conversations are subject to Meta's 24-hour reply window; outside it you get 422 with code: CHANNEL_ERROR and details.reason: "whatsapp_window_expired".
Authorization
bearerAuth An API key from Settings → Integrations → Webhook (org admins only), sent as Authorization: Bearer rf_org_….
The scope is ranked — a key satisfies any requirement at or below its own tier:
read— see leads, conversations, transcripts and handoffs. Never changes anything.write— create and update leads, claim and resolve handoffs.admin— mint and revoke tokens, and change org-wide integration settings.
There is no approve scope. It was a rung once; it is not one now, and a key requested with it is rejected.
Tokens are org-scoped: one sees every agent's leads in its org. There is no project dimension. The token is shown once at creation and stored only as a hash.
In: header
Path Parameters
The lead to reply to.
uuidHeader Parameters
Up to 255 characters. Makes a retry safe.
length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/leads/497f6eca-6276-4993-bfeb-53cbbbba6f08/messages" \ -H "Content-Type: application/json" \ -d '{ "text": "Hi Jane — free for a viewing tomorrow at 4pm?" }'{ "object": "message_send", "lead_id": "3f1c2e00-9a1b-4c77-8d2e-2b6a1f0e9c34", "conversation_id": "8c2d41aa-0f3e-4d61-9d0b-77b1c4e2a910", "channel": "whatsapp", "deduplicated": true}