Start a conversation

Sends a first message to a phone number on WhatsApp or to an email address, and records it as a conversation so the recipient’s reply threads into it. This is the endpoint behind the dashboard’s “New message” composer. Use it when you have an address but not necessarily a contact. If you already have a contactId and do not need the message in a thread, POST /api/whatsapp/send and POST /api/email/send are the lower-level sends.

How it works.

1. The recipient is validated: E.164 for whatsapp, a valid address for email.
2. The contact is looked up anywhere in the workspace. Email matching ignores case; WhatsApp matches whatsapp_number exactly. An unknown recipient is created in the workspace’s “Manual Conversations” campaign. A contact already enrolled elsewhere is not moved.
3. The message is delivered through the channel’s provider, with every guard of the lower-level send applied (compliance, opt-out, 24-hour window, daily cap).
4. Only after delivery succeeds is the conversation found, reopened or created, using the same thread key inbound messages use, and the message stored with metadata.manual = true.

On WhatsApp, pass templateId to reach a contact outside WhatsApp’s 24-hour window. message is then optional, and the thread records [template] <templateId> as the content. On email, subject is required. webchat, instagram and messenger cannot be started from here.

Side effects. Sends a real WhatsApp message or a real email from the workspace’s connected mailbox. Consumes one unit of the channel’s daily send cap. The unit is refunded if the provider rejects the send. It does not draw on the AI-message allowance. The AI reply to the contact’s answer does. May create a contact, and the “Manual Conversations” campaign on first use. Broadcasts a realtime update to the dashboard and writes an audit entry.

Idempotency. Not idempotent. A retry after a timeout delivers the message a second time. The conversation row is reused, so both copies land in the same thread. Check GET /api/conversations/{conversationId} before retrying.

Webhook events. audit.log_recorded for subscribers that selected it explicitly. See Webhooks.

Access

• Required scope: write.
• Rate limit: General API (120–600 requests/min per workspace by plan) and the configuration-mutations limiter — 10 requests/min per workspace, a budget shared with other configuration mutations. See Rate limits.
• Plan: Available on every plan. The workspace needs at least one agent, a WhatsApp sender that is ONLINE for WhatsApp, and a connected mailbox for email.