Bulk SMS Tool

The ai_send_bulk_sms_tool lets the AI Assistant broadcast one message to up to 50 contacts at once. It uses a two-step confirmation flow to prevent accidental mass sends.

How It Works

1. The assistant calls the tool with confirmed: false to preview the recipient list and message.
2. The user reviews the preview in the chat.
3. The assistant calls the tool again with confirmed: true to execute the send.

Each message is attributed to the session member (sent_by_member_id) with ai_origin: "assistant".

Parameters

Parameter	Type	Required	Description
contact_ids	Vec<Uuid>	Yes	Contact IDs to message (max 50)
body	String	Yes	Message text (same for all recipients)
phone_number_id	Uuid	Yes	Sender phone line to use
confirmed	bool	Yes	false for preview, true to send

Phone Resolution

The tool resolves one phone number per contact:

1. Prefers the contact’s phone marked is_preferred: true
2. Falls back to the first available phone number
3. Skips contacts with no phone on file

Resolution uses resolve_contact_phone_map(), which batch-fetches phones with a single WHERE contact_id IN (...) query.

Attribution

CreateMessageInput {
    ai_origin: Some(AiOrigin::Assistant),
    sent_by_member_id: Some(session.member_id),
    // ...
}

Every message sent through this tool records the member who initiated the assistant conversation. See AI Origin & Member Attribution for the full attribution model.

Comparison with Single Send

	ai_send_sms_tool	ai_send_bulk_sms_tool
Recipients	One contact	Up to 50 contacts
Message	Personalized per contact	Same body for all
Confirmation	No	Yes (two-step)
Use case	Individual outreach	Announcements, reminders

Use the single-send tool for personalized drafts reviewed one contact at a time. Use bulk send for identical broadcasts.

Related

• AI Origin & Member Attribution — how sent_by_member_id and ai_origin are tracked
• Assistant Tools Overview — all available assistant tools