Messages the agent starts

By default an agent only replies. You can let it start a message to one of its people on its own, for example a reminder or a "your report is ready" note, and optionally let it message people who never wrote to it.

Turn it on

In the app, open the agent's settings. On the General tab, the Starting chats card has two switches, both off for a new agent:

Switch	What it allows
Send without being asked	The agent can message a chat on its own, such as a reminder. Turning it off also stops sends that are queued or held.
Message new people	The agent can start a chat with someone who never wrote to it. Available only while Send without being asked is on.

Each switch saves at once. In the terminal:

catalex agents edit AGENT_ID --proactive-send on
catalex agents edit AGENT_ID --message-new-people on

warning

Getting a person's consent under the messaging app's policy is your responsibility. CatalEx does not check it.

Once allowed, the agent sends these messages itself with its relay_send tool. CatalEx delivers exactly the text it is given.

Set limits

These limits are on by default. Change them on the Access tab in the Limits card, or in the terminal:

Limit	Default	Flag
Sends without being asked, per hour	20	--proactive-hour
Sends without being asked, per day	100	--proactive-day
New people messaged, per day	10	--proactive-new-people-day

catalex agents limits set AGENT_ID --proactive-hour 10 --proactive-day 50
catalex agents limits show AGENT_ID

none restores a default. Hours and days follow the agent's time zone; see access and limits. A send over a limit is refused with The agent reached its limit on messages sent without being asked.

Send a message from the terminal

You can send on the agent's behalf, for example from a scheduled job:

catalex messages send --agent AGENT_ID --to CONTACT_REF --text 'Your report is ready' --idempotency-key report-1

• --to names the person by contact reference. Leave it out only when the agent has exactly one person.
• To message someone new, use --new-recipient instead: a phone number in international format for WhatsApp (+15551234567), or the person's workspace email for Slack. The agent needs Message new people. The result names the person's reference; use --to with it from then on.
• Use a new --idempotency-key for each message, and reuse it only to retry the same one.
• Add --app or --account when more than one app or account reaches the person.

Then check the outcome:

catalex messages status --agent AGENT_ID SEND_ID

Outcomes

Result	Meaning	Exit code
queued	Recorded; no answer from the app yet. Check it later with messages status.	0
delivered	The app accepted the message.	0
held	Outside the app's delivery window. It is not sent now and must not be sent again; it goes out when the person next writes.	0
refused	Not sent, for example because sending is off, a limit is reached or the person is unknown. The output names the code and the command that fixes it.	1
failed	The app did not accept the message.	1

If Send without being asked is off, the command reports The agent may not send without being asked. (PROACTIVE_SEND_DISABLED); fix it with catalex agents edit AGENT_ID --proactive-send on.

WhatsApp only accepts a message outside its delivery window through an approved template with exactly one body parameter. Register the template your WhatsApp app approved, or the message is held until the person writes:

catalex accounts template set ACCOUNT_ID --name agent_message --language en
catalex accounts template show ACCOUNT_ID

Google Chat and WhatsApp Personal cannot start a conversation with someone who never wrote to the agent.

What people see in the chat

In the app, a message the agent started is marked under the text: Sent without being asked, Waiting for them to write while it is held, or Not delivered if it failed.

Test with your own number or account first: allow sends, send one message with the CLI, confirm it arrives, then check messages status reports delivered.

To pass a message to another agent instead of a person, see Messages between agents.